Docker Build Example

1. Introduction

Docker is a tool to avoid the usual headaches of conflicts, dependencies, and inconsistent environments, which is an important problem for distributed applications, where we need to install or upgrade several nodes with the same configuration.

Docker is a container manager, which means that is able to create and execute containers that represent specific runtime environments for your software. A specific runtime environment is called a Docker image and containers are specific executions of Docker images. It is the same concept that classes and objects/instances, which allow defining, for example, different network configurations for each container.

Dockerhub is a repository of docker images. Docker users can upload their docker images and share them with the community. It allows that users of software providers do not need to deal with installation guides. They just need to download the image and create as many containers as they need. In fact, it is especially useful when system administrators need to scale the same software in a cluster of machines.

The purpose of this tutorial is to explain how to build docker images using the docker build command and the supported building options. As we will see below, docker allows building images using different approaches.

2. Installation & Usage

The docker build command is available from your docker installation, which depends on your operative system and is widely explained (here for Mac, here for Windows, and here for Ubuntu). Once, you have followed the installation instructions, you should be able to run the docker build command.

Docker usage command

docker build --help

It prints the following output:

docker build
docker build

The docker build command builds Docker images from a Dockerfile and a context. In order to specify a context, you need to reference a local file directory or a URL. The contents of this context can be referenced from ADD instructions of the Dockerfile to reference a file in the context.

3. Context definition

The context of a docker build command could be a local directory (PATH), a Git repository (URL) or the standard input (-). This section explains the usage scenarios of these different contexts.

docker build - docker-build-alternatives

3.1 Build with PATH

Probably, you are assuming that the docker daemon is always running in your machine. However, when you are building docker images for a remote machine, this command is sending to the daemon a tar file with the contents of the local directory you have specified to proceed with the build command. For example:

Docker build from path

docker build .

Sends the contents of the execution directory to the docker daemon.

3.2 Build with URL

URLs are specially designed for Git repositories. In this case, the build command clones the Git repository and uses the cloned repository as context. The Dockerfile at the root of the repository is used as Dockerfile. Alternatively to HTTP or HTTPS, you can specify an arbitrary Git repository by using the git:// or git@ schema. For a GitHub repository, we can use docker build as follows:

Docker build from git

docker build

3.3 Build with –

This will read a Dockerfile from STDIN without context. It is commonly used to send a compressed file. The Supported formats are bzip2, gzip, and gz. For example:

Docker build from the standard output

docker build - < context.tar.gz

4.Dockerfile location

The Dockerfile location is by default in the root directory of the specified context and it is called Dockerfile. However, you can specify another one with the -f option, but always it must be located inside the build context. For example:

Docker build with an specific dockerfile

docker build -f Dockerfile.debug .

5. Example

Now, let’s build an Ubuntu image with Java from a Github project used in a previous JavaCodeGeeks example. Run the following command:

Docker build command with a real project

docker build -t javacodegeeks/buildsample

Now, in order to check if the image is available, execute docker images. This command shows the available images for your docker daemon. It should show something similar to the following output:

docker build - dockerimages
docker images

6. Summary

This tutorial explains what is a docker image and how to build it using the command docker build. This command requires to specify a context, which is the location of the files that we need to add into the image and also the Dockerfile. Finally, our example shows how to build an image from a Github project and how to verify what are the available images in our docker daemon with the docker images command.

Remember that creating docker images is extremely useful to set up a specific execution environment that needs to be installed in a cluster of machines. Therefore, it allows avoiding problems caused by differences between production and development environments.

Last updated on Dec. 17th, 2021

Want to know how to develop your skillset to become a Java Rockstar?

Join our newsletter to start rocking!

To get you started we give you our best selling eBooks for FREE!


1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design


and many more ....


Receive Java & Developer job alerts in your Area

I have read and agree to the terms & conditions


Raquel Pau

Raquel has graduated from Computer Engineering in the Universitat Politecnica de Catalunya. She also holds a Master degree in Computation (Software Engineering) from the same university. She has an I+D profile focused about model driven development. Additionally, she is the project leader of Walkmod, an open source project to code conventions, which is part of the result of her interest in the model driven development. Currently, Raquel works as a Software Architect in the Sparsity-Technologies.
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button