Dockerfile reference
Docker can build images automatically by reading the instructions from a Dockerfile.
A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image.
Using docker build users can create an automated build that executes several command-line instructions in succession.
This page describes the commands you can use in a Dockerfile. When you are done reading this page, refer to the Dockerfile Best Practices for a tip-oriented guide.
Usage
The docker build command builds an image from a Dockerfile and a context.
The build’s context is the set of files at a specified location PATH or URL.
The PATH is a directory on your local filesystem.
The URL is a Git repository location.
A context is processed recursively.
So, a PATH includes any subdirectories and the URL includes the repository and its submodules.
This example shows a build command that uses the current directory as context:
$ docker build . Sending build context to Docker daemon 6.51 MB ...
The build is run by the Docker daemon, not by the CLI.
The first thing a build process does is send the entire context (recursively) to the daemon.
In most cases, it’s best to start with an empty directory as context and keep your Dockerfile in that directory. Add only the files needed for building the Dockerfile.
Warning: Do not use your root directory,
/, as thePATHas it causes the build to transfer the entire contents of your hard drive to the Docker daemon.
To use a file in the build context, the Dockerfile refers to the file specified in an instruction, for example, a COPY instruction.
To increase the build’s performance, exclude files and directories by adding a .dockerignore file to the context directory.
For information about how to create a .dockerignore file see the documentation on this page.
Traditionally, the Dockerfile is called Dockerfile and located in the root of the context.
You use the -f flag with docker build to point to a Dockerfile anywhere in your file system.
$ docker build -f /path/to/a/Dockerfile .
You can specify a repository and tag at which to save the new image if the build succeeds:
$ docker build -t shykes/myapp .
To tag the image into multiple repositories after the build, add multiple -t parameters when you run the build command:
$ docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest .
Before the Docker daemon runs the instructions in the Dockerfile, it performs a preliminary validation of the Dockerfile and returns an error if the syntax is incorrect:
$ docker build -t test/myapp . Sending build context to Docker daemon 2.048 kB Error response from daemon: Unknown instruction: RUNCMD
The Docker daemon runs the instructions in the Dockerfile one-by-one, committing the result of each instruction to a new image if necessary, before finally outputting the ID of your new image. The Docker daemon will automatically clean up the context you sent.
Note that each instruction is run independently, and causes a new image to be created - so RUN cd /tmp will not have any effect on the next instructions.
Whenever possible, Docker will re-use the intermediate images (cache), to accelerate the docker build process significantly. This is indicated by the Using cache message in the console output. (For more information, see the Build cache section in the Dockerfile best practices guide):