diff options
Diffstat (limited to 'devdocs/docker/engine%2Freference%2Fbuilder%2Findex.html')
| -rw-r--r-- | devdocs/docker/engine%2Freference%2Fbuilder%2Findex.html | 527 |
1 files changed, 527 insertions, 0 deletions
diff --git a/devdocs/docker/engine%2Freference%2Fbuilder%2Findex.html b/devdocs/docker/engine%2Freference%2Fbuilder%2Findex.html new file mode 100644 index 00000000..533d2592 --- /dev/null +++ b/devdocs/docker/engine%2Freference%2Fbuilder%2Findex.html @@ -0,0 +1,527 @@ +<h1>Dockerfile reference</h1> + <p>Docker can build images automatically by reading the instructions from a <code class="language-plaintext highlighter-rouge">Dockerfile</code>. A <code class="language-plaintext highlighter-rouge">Dockerfile</code> is a text document that contains all the commands a user could call on the command line to assemble an image. Using <code class="language-plaintext highlighter-rouge">docker build</code> users can create an automated build that executes several command-line instructions in succession.</p> <p>This page describes the commands you can use in a <code class="language-plaintext highlighter-rouge">Dockerfile</code>. When you are done reading this page, refer to the <a href="https://docs.docker.com/develop/develop-images/dockerfile_best-practices/"><code class="language-plaintext highlighter-rouge">Dockerfile</code> Best Practices</a> for a tip-oriented guide.</p> <h2 id="usage">Usage</h2> <p>The <a href="../commandline/build/index">docker build</a> command builds an image from a <code class="language-plaintext highlighter-rouge">Dockerfile</code> and a <em>context</em>. The build’s context is the set of files at a specified location <code class="language-plaintext highlighter-rouge">PATH</code> or <code class="language-plaintext highlighter-rouge">URL</code>. The <code class="language-plaintext highlighter-rouge">PATH</code> is a directory on your local filesystem. The <code class="language-plaintext highlighter-rouge">URL</code> is a Git repository location.</p> <p>The build context is processed recursively. So, a <code class="language-plaintext highlighter-rouge">PATH</code> includes any subdirectories and the <code class="language-plaintext highlighter-rouge">URL</code> includes the repository and its submodules. This example shows a build command that uses the current directory (<code class="language-plaintext highlighter-rouge">.</code>) as build context:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build . + +Sending build context to Docker daemon 6.51 MB +... +</pre></div> <p>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.</p> <blockquote class="warning"> <p><strong>Warning</strong></p> <p>Do not use your root directory, <code class="language-plaintext highlighter-rouge">/</code>, as the <code class="language-plaintext highlighter-rouge">PATH</code> for your build context, as it causes the build to transfer the entire contents of your hard drive to the Docker daemon.</p> </blockquote> <p>To use a file in the build context, the <code class="language-plaintext highlighter-rouge">Dockerfile</code> refers to the file specified in an instruction, for example, a <code class="language-plaintext highlighter-rouge">COPY</code> instruction. To increase the build’s performance, exclude files and directories by adding a <code class="language-plaintext highlighter-rouge">.dockerignore</code> file to the context directory. For information about how to <a href="#dockerignore-file">create a <code class="language-plaintext highlighter-rouge">.dockerignore</code> file</a> see the documentation on this page.</p> <p>Traditionally, the <code class="language-plaintext highlighter-rouge">Dockerfile</code> is called <code class="language-plaintext highlighter-rouge">Dockerfile</code> and located in the root of the context. You use the <code class="language-plaintext highlighter-rouge">-f</code> flag with <code class="language-plaintext highlighter-rouge">docker build</code> to point to a Dockerfile anywhere in your file system.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build -f /path/to/a/Dockerfile . +</pre></div> <p>You can specify a repository and tag at which to save the new image if the build succeeds:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build -t shykes/myapp . +</pre></div> <p>To tag the image into multiple repositories after the build, add multiple <code class="language-plaintext highlighter-rouge">-t</code> parameters when you run the <code class="language-plaintext highlighter-rouge">build</code> command:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest . +</pre></div> <p>Before the Docker daemon runs the instructions in the <code class="language-plaintext highlighter-rouge">Dockerfile</code>, it performs a preliminary validation of the <code class="language-plaintext highlighter-rouge">Dockerfile</code> and returns an error if the syntax is incorrect:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build -t test/myapp . + +[+] Building 0.3s (2/2) FINISHED + => [internal] load build definition from Dockerfile 0.1s + => => transferring dockerfile: 60B 0.0s + => [internal] load .dockerignore 0.1s + => => transferring context: 2B 0.0s +error: failed to solve: rpc error: code = Unknown desc = failed to solve with frontend dockerfile.v0: failed to create LLB definition: +dockerfile parse error line 2: unknown instruction: RUNCMD +</pre></div> <p>The Docker daemon runs the instructions in the <code class="language-plaintext highlighter-rouge">Dockerfile</code> 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.</p> <p>Note that each instruction is run independently, and causes a new image to be created - so <code class="language-plaintext highlighter-rouge">RUN cd /tmp</code> will not have any effect on the next instructions.</p> <p>Whenever possible, Docker uses a build-cache to accelerate the <code class="language-plaintext highlighter-rouge">docker build</code> process significantly. This is indicated by the <code class="language-plaintext highlighter-rouge">CACHED</code> message in the console output. (For more information, see the <a href="https://docs.docker.com/develop/develop-images/dockerfile_best-practices/"><code class="language-plaintext highlighter-rouge">Dockerfile</code> best practices guide</a>):</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build -t svendowideit/ambassador . + +[+] Building 0.7s (6/6) FINISHED + => [internal] load build definition from Dockerfile 0.1s + => => transferring dockerfile: 286B 0.0s + => [internal] load .dockerignore 0.1s + => => transferring context: 2B 0.0s + => [internal] load metadata for docker.io/library/alpine:3.2 0.4s + => CACHED [1/2] FROM docker.io/library/alpine:3.2@sha256:e9a2035f9d0d7ce 0.0s + => CACHED [2/2] RUN apk add --no-cache socat 0.0s + => exporting to image 0.0s + => => exporting layers 0.0s + => => writing image sha256:1affb80ca37018ac12067fa2af38cc5bcc2a8f09963de 0.0s + => => naming to docker.io/svendowideit/ambassador 0.0s +</pre></div> <p>By default, the build cache is based on results from previous builds on the machine on which you are building. The <code class="language-plaintext highlighter-rouge">--cache-from</code> option also allows you to use a build-cache that’s distributed through an image registry refer to the <a href="../commandline/build/index#specifying-external-cache-sources">specifying external cache sources</a> section in the <code class="language-plaintext highlighter-rouge">docker build</code> command reference.</p> <p>When you’re done with your build, you’re ready to look into <a href="../../scan/index">scanning your image with <code class="language-plaintext highlighter-rouge">docker scan</code></a>, and <a href="https://docs.docker.com/docker-hub/repos/">pushing your image to Docker Hub</a>.</p> <h2 id="buildkit">BuildKit</h2> <p>Starting with version 18.09, Docker supports a new backend for executing your builds that is provided by the <a href="https://github.com/moby/buildkit">moby/buildkit</a> project. The BuildKit backend provides many benefits compared to the old implementation. For example, BuildKit can:</p> <ul> <li>Detect and skip executing unused build stages</li> <li>Parallelize building independent build stages</li> <li>Incrementally transfer only the changed files in your build context between builds</li> <li>Detect and skip transferring unused files in your build context</li> <li>Use external Dockerfile implementations with many new features</li> <li>Avoid side-effects with rest of the API (intermediate images and containers)</li> <li>Prioritize your build cache for automatic pruning</li> </ul> <p>To use the BuildKit backend, you need to set an environment variable <code class="language-plaintext highlighter-rouge">DOCKER_BUILDKIT=1</code> on the CLI before invoking <code class="language-plaintext highlighter-rouge">docker build</code>.</p> <p>To learn about the Dockerfile syntax available to BuildKit-based builds <a href="https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax/">refer to the documentation in the BuildKit repository</a>.</p> <h2 id="format">Format</h2> <p>Here is the format of the <code class="language-plaintext highlighter-rouge">Dockerfile</code>:</p> <div class="highlight"><pre class="highlight" data-language=""># Comment +INSTRUCTION arguments +</pre></div> <p>The instruction is not case-sensitive. However, convention is for them to be UPPERCASE to distinguish them from arguments more easily.</p> <p>Docker runs instructions in a <code class="language-plaintext highlighter-rouge">Dockerfile</code> in order. A <code class="language-plaintext highlighter-rouge">Dockerfile</code> <strong>must begin with a <code class="language-plaintext highlighter-rouge">FROM</code> instruction</strong>. This may be after <a href="#parser-directives">parser directives</a>, <a href="#format">comments</a>, and globally scoped <a href="#arg">ARGs</a>. The <code class="language-plaintext highlighter-rouge">FROM</code> instruction specifies the <a href="https://docs.docker.com/glossary/#parent-image"><em>Parent Image</em></a> from which you are building. <code class="language-plaintext highlighter-rouge">FROM</code> may only be preceded by one or more <code class="language-plaintext highlighter-rouge">ARG</code> instructions, which declare arguments that are used in <code class="language-plaintext highlighter-rouge">FROM</code> lines in the <code class="language-plaintext highlighter-rouge">Dockerfile</code>.</p> <p>Docker treats lines that <em>begin</em> with <code class="language-plaintext highlighter-rouge">#</code> as a comment, unless the line is a valid <a href="#parser-directives">parser directive</a>. A <code class="language-plaintext highlighter-rouge">#</code> marker anywhere else in a line is treated as an argument. This allows statements like:</p> <div class="highlight"><pre class="highlight" data-language=""># Comment +RUN echo 'we are running some # of cool things' +</pre></div> <p>Comment lines are removed before the Dockerfile instructions are executed, which means that the comment in the following example is not handled by the shell executing the <code class="language-plaintext highlighter-rouge">echo</code> command, and both examples below are equivalent:</p> <div class="highlight"><pre class="highlight" data-language="">RUN echo hello \ +# comment +world +</pre></div> <div class="highlight"><pre class="highlight" data-language="">RUN echo hello \ +world +</pre></div> <p>Line continuation characters are not supported in comments.</p> <blockquote> <p><strong>Note on whitespace</strong></p> <p>For backward compatibility, leading whitespace before comments (<code class="language-plaintext highlighter-rouge">#</code>) and instructions (such as <code class="language-plaintext highlighter-rouge">RUN</code>) are ignored, but discouraged. Leading whitespace is not preserved in these cases, and the following examples are therefore equivalent:</p> <div class="highlight"><pre class="highlight" data-language=""> # this is a comment-line + RUN echo hello +RUN echo world +</pre></div> <div class="highlight"><pre class="highlight" data-language=""># this is a comment-line +RUN echo hello +RUN echo world +</pre></div> <p>Note however, that whitespace in instruction <em>arguments</em>, such as the commands following <code class="language-plaintext highlighter-rouge">RUN</code>, are preserved, so the following example prints ` hello world` with leading whitespace as specified:</p> <div class="highlight"><pre class="highlight" data-language="">RUN echo "\ + hello\ + world" +</pre></div> </blockquote> <h2 id="parser-directives">Parser directives</h2> <p>Parser directives are optional, and affect the way in which subsequent lines in a <code class="language-plaintext highlighter-rouge">Dockerfile</code> are handled. Parser directives do not add layers to the build, and will not be shown as a build step. Parser directives are written as a special type of comment in the form <code class="language-plaintext highlighter-rouge"># directive=value</code>. A single directive may only be used once.</p> <p>Once a comment, empty line or builder instruction has been processed, Docker no longer looks for parser directives. Instead it treats anything formatted as a parser directive as a comment and does not attempt to validate if it might be a parser directive. Therefore, all parser directives must be at the very top of a <code class="language-plaintext highlighter-rouge">Dockerfile</code>.</p> <p>Parser directives are not case-sensitive. However, convention is for them to be lowercase. Convention is also to include a blank line following any parser directives. Line continuation characters are not supported in parser directives.</p> <p>Due to these rules, the following examples are all invalid:</p> <p>Invalid due to line continuation:</p> <div class="highlight"><pre class="highlight" data-language=""># direc \ +tive=value +</pre></div> <p>Invalid due to appearing twice:</p> <div class="highlight"><pre class="highlight" data-language=""># directive=value1 +# directive=value2 + +FROM ImageName +</pre></div> <p>Treated as a comment due to appearing after a builder instruction:</p> <div class="highlight"><pre class="highlight" data-language="">FROM ImageName +# directive=value +</pre></div> <p>Treated as a comment due to appearing after a comment which is not a parser directive:</p> <div class="highlight"><pre class="highlight" data-language=""># About my dockerfile +# directive=value +FROM ImageName +</pre></div> <p>The unknown directive is treated as a comment due to not being recognized. In addition, the known directive is treated as a comment due to appearing after a comment which is not a parser directive.</p> <div class="highlight"><pre class="highlight" data-language=""># unknowndirective=value +# knowndirective=value +</pre></div> <p>Non line-breaking whitespace is permitted in a parser directive. Hence, the following lines are all treated identically:</p> <div class="highlight"><pre class="highlight" data-language="">#directive=value +# directive =value +# directive= value +# directive = value +# dIrEcTiVe=value +</pre></div> <p>The following parser directives are supported:</p> <ul> <li><code class="language-plaintext highlighter-rouge">syntax</code></li> <li><code class="language-plaintext highlighter-rouge">escape</code></li> </ul> <h2 id="syntax">syntax</h2> <div class="highlight"><pre class="highlight" data-language=""># syntax=[remote image reference] +</pre></div> <p>For example:</p> <div class="highlight"><pre class="highlight" data-language=""># syntax=docker/dockerfile:1 +# syntax=docker.io/docker/dockerfile:1 +# syntax=example.com/user/repo:tag@sha256:abcdef... +</pre></div> <p>This feature is only available when using the <a href="#buildkit">BuildKit</a> backend, and is ignored when using the classic builder backend.</p> <p>The syntax directive defines the location of the Dockerfile syntax that is used to build the Dockerfile. The BuildKit backend allows to seamlessly use external implementations that are distributed as Docker images and execute inside a container sandbox environment.</p> <p>Custom Dockerfile implementations allows you to:</p> <ul> <li>Automatically get bugfixes without updating the Docker daemon</li> <li>Make sure all users are using the same implementation to build your Dockerfile</li> <li>Use the latest features without updating the Docker daemon</li> <li>Try out new features or third-party features before they are integrated in the Docker daemon</li> <li>Use <a href="https://github.com/moby/buildkit#exploring-llb">alternative build definitions, or create your own</a> +</li> </ul> <h3 id="official-releases">Official releases</h3> <p>Docker distributes official versions of the images that can be used for building Dockerfiles under <code class="language-plaintext highlighter-rouge">docker/dockerfile</code> repository on Docker Hub. There are two channels where new images are released: <code class="language-plaintext highlighter-rouge">stable</code> and <code class="language-plaintext highlighter-rouge">labs</code>.</p> <p>Stable channel follows <a href="https://semver.org">semantic versioning</a>. For example:</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">docker/dockerfile:1</code> - kept updated with the latest <code class="language-plaintext highlighter-rouge">1.x.x</code> minor <em>and</em> patch release</li> <li> +<code class="language-plaintext highlighter-rouge">docker/dockerfile:1.2</code> - kept updated with the latest <code class="language-plaintext highlighter-rouge">1.2.x</code> patch release, and stops receiving updates once version <code class="language-plaintext highlighter-rouge">1.3.0</code> is released.</li> <li> +<code class="language-plaintext highlighter-rouge">docker/dockerfile:1.2.1</code> - immutable: never updated</li> </ul> <p>We recommend using <code class="language-plaintext highlighter-rouge">docker/dockerfile:1</code>, which always points to the latest stable release of the version 1 syntax, and receives both “minor” and “patch” updates for the version 1 release cycle. BuildKit automatically checks for updates of the syntax when performing a build, making sure you are using the most current version.</p> <p>If a specific version is used, such as <code class="language-plaintext highlighter-rouge">1.2</code> or <code class="language-plaintext highlighter-rouge">1.2.1</code>, the Dockerfile needs to be updated manually to continue receiving bugfixes and new features. Old versions of the Dockerfile remain compatible with the new versions of the builder.</p> <p><strong>labs channel</strong></p> <p>The “labs” channel provides early access to Dockerfile features that are not yet available in the stable channel. Labs channel images are released in conjunction with the stable releases, and follow the same versioning with the <code class="language-plaintext highlighter-rouge">-labs</code> suffix, for example:</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">docker/dockerfile:labs</code> - latest release on labs channel</li> <li> +<code class="language-plaintext highlighter-rouge">docker/dockerfile:1-labs</code> - same as <code class="language-plaintext highlighter-rouge">dockerfile:1</code> in the stable channel, with labs features enabled</li> <li> +<code class="language-plaintext highlighter-rouge">docker/dockerfile:1.2-labs</code> - same as <code class="language-plaintext highlighter-rouge">dockerfile:1.2</code> in the stable channel, with labs features enabled</li> <li> +<code class="language-plaintext highlighter-rouge">docker/dockerfile:1.2.1-labs</code> - immutable: never updated. Same as <code class="language-plaintext highlighter-rouge">dockerfile:1.2.1</code> in the stable channel, with labs features enabled</li> </ul> <p>Choose a channel that best fits your needs; if you want to benefit from new features, use the labs channel. Images in the labs channel provide a superset of the features in the stable channel; note that <code class="language-plaintext highlighter-rouge">stable</code> features in the labs channel images follow <a href="https://semver.org">semantic versioning</a>, but “labs” features do not, and newer releases may not be backwards compatible, so it is recommended to use an immutable full version variant.</p> <p>For documentation on “labs” features, master builds, and nightly feature releases, refer to the description in <a href="https://github.com/moby/buildkit/blob/master/README/">the BuildKit source repository on GitHub</a>. For a full list of available images, visit the <a href="https://hub.docker.com/r/docker/dockerfile">image repository on Docker Hub</a>, and the <a href="https://hub.docker.com/r/docker/dockerfile-upstream">docker/dockerfile-upstream image repository</a> for development builds.</p> <h2 id="escape">escape</h2> <div class="highlight"><pre class="highlight" data-language=""># escape=\ (backslash) +</pre></div> <p>Or</p> <div class="highlight"><pre class="highlight" data-language=""># escape=` (backtick) +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">escape</code> directive sets the character used to escape characters in a <code class="language-plaintext highlighter-rouge">Dockerfile</code>. If not specified, the default escape character is <code class="language-plaintext highlighter-rouge">\</code>.</p> <p>The escape character is used both to escape characters in a line, and to escape a newline. This allows a <code class="language-plaintext highlighter-rouge">Dockerfile</code> instruction to span multiple lines. Note that regardless of whether the <code class="language-plaintext highlighter-rouge">escape</code> parser directive is included in a <code class="language-plaintext highlighter-rouge">Dockerfile</code>, <em>escaping is not performed in a <code class="language-plaintext highlighter-rouge">RUN</code> command, except at the end of a line.</em></p> <p>Setting the escape character to <code class="language-plaintext highlighter-rouge">`</code> is especially useful on <code class="language-plaintext highlighter-rouge">Windows</code>, where <code class="language-plaintext highlighter-rouge">\</code> is the directory path separator. <code class="language-plaintext highlighter-rouge">`</code> is consistent with <a href="https://technet.microsoft.com/en-us/library/hh847755.aspx">Windows PowerShell</a>.</p> <p>Consider the following example which would fail in a non-obvious way on <code class="language-plaintext highlighter-rouge">Windows</code>. The second <code class="language-plaintext highlighter-rouge">\</code> at the end of the second line would be interpreted as an escape for the newline, instead of a target of the escape from the first <code class="language-plaintext highlighter-rouge">\</code>. Similarly, the <code class="language-plaintext highlighter-rouge">\</code> at the end of the third line would, assuming it was actually handled as an instruction, cause it be treated as a line continuation. The result of this dockerfile is that second and third lines are considered a single instruction:</p> <div class="highlight"><pre class="highlight" data-language="">FROM microsoft/nanoserver +COPY testfile.txt c:\\ +RUN dir c:\ +</pre></div> <p>Results in:</p> <div class="highlight"><pre class="highlight" data-language="">PS E:\myproject> docker build -t cmd . + +Sending build context to Docker daemon 3.072 kB +Step 1/2 : FROM microsoft/nanoserver + ---> 22738ff49c6d +Step 2/2 : COPY testfile.txt c:\RUN dir c: +GetFileAttributesEx c:RUN: The system cannot find the file specified. +PS E:\myproject> +</pre></div> <p>One solution to the above would be to use <code class="language-plaintext highlighter-rouge">/</code> as the target of both the <code class="language-plaintext highlighter-rouge">COPY</code> instruction, and <code class="language-plaintext highlighter-rouge">dir</code>. However, this syntax is, at best, confusing as it is not natural for paths on <code class="language-plaintext highlighter-rouge">Windows</code>, and at worst, error prone as not all commands on <code class="language-plaintext highlighter-rouge">Windows</code> support <code class="language-plaintext highlighter-rouge">/</code> as the path separator.</p> <p>By adding the <code class="language-plaintext highlighter-rouge">escape</code> parser directive, the following <code class="language-plaintext highlighter-rouge">Dockerfile</code> succeeds as expected with the use of natural platform semantics for file paths on <code class="language-plaintext highlighter-rouge">Windows</code>:</p> <div class="highlight"><pre class="highlight" data-language=""># escape=` + +FROM microsoft/nanoserver +COPY testfile.txt c:\ +RUN dir c:\ +</pre></div> <p>Results in:</p> <div class="highlight"><pre class="highlight" data-language="">PS E:\myproject> docker build -t succeeds --no-cache=true . + +Sending build context to Docker daemon 3.072 kB +Step 1/3 : FROM microsoft/nanoserver + ---> 22738ff49c6d +Step 2/3 : COPY testfile.txt c:\ + ---> 96655de338de +Removing intermediate container 4db9acbb1682 +Step 3/3 : RUN dir c:\ + ---> Running in a2c157f842f5 + Volume in drive C has no label. + Volume Serial Number is 7E6D-E0F7 + + Directory of c:\ + +10/05/2016 05:04 PM 1,894 License.txt +10/05/2016 02:22 PM <DIR> Program Files +10/05/2016 02:14 PM <DIR> Program Files (x86) +10/28/2016 11:18 AM 62 testfile.txt +10/28/2016 11:20 AM <DIR> Users +10/28/2016 11:20 AM <DIR> Windows + 2 File(s) 1,956 bytes + 4 Dir(s) 21,259,096,064 bytes free + ---> 01c7f3bef04f +Removing intermediate container a2c157f842f5 +Successfully built 01c7f3bef04f +PS E:\myproject> +</pre></div> <h2 id="environment-replacement">Environment replacement</h2> <p>Environment variables (declared with <a href="#env">the <code class="language-plaintext highlighter-rouge">ENV</code> statement</a>) can also be used in certain instructions as variables to be interpreted by the <code class="language-plaintext highlighter-rouge">Dockerfile</code>. Escapes are also handled for including variable-like syntax into a statement literally.</p> <p>Environment variables are notated in the <code class="language-plaintext highlighter-rouge">Dockerfile</code> either with <code class="language-plaintext highlighter-rouge">$variable_name</code> or <code class="language-plaintext highlighter-rouge">${variable_name}</code>. They are treated equivalently and the brace syntax is typically used to address issues with variable names with no whitespace, like <code class="language-plaintext highlighter-rouge">${foo}_bar</code>.</p> <p>The <code class="language-plaintext highlighter-rouge">${variable_name}</code> syntax also supports a few of the standard <code class="language-plaintext highlighter-rouge">bash</code> modifiers as specified below:</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">${variable:-word}</code> indicates that if <code class="language-plaintext highlighter-rouge">variable</code> is set then the result will be that value. If <code class="language-plaintext highlighter-rouge">variable</code> is not set then <code class="language-plaintext highlighter-rouge">word</code> will be the result.</li> <li> +<code class="language-plaintext highlighter-rouge">${variable:+word}</code> indicates that if <code class="language-plaintext highlighter-rouge">variable</code> is set then <code class="language-plaintext highlighter-rouge">word</code> will be the result, otherwise the result is the empty string.</li> </ul> <p>In all cases, <code class="language-plaintext highlighter-rouge">word</code> can be any string, including additional environment variables.</p> <p>Escaping is possible by adding a <code class="language-plaintext highlighter-rouge">\</code> before the variable: <code class="language-plaintext highlighter-rouge">\$foo</code> or <code class="language-plaintext highlighter-rouge">\${foo}</code>, for example, will translate to <code class="language-plaintext highlighter-rouge">$foo</code> and <code class="language-plaintext highlighter-rouge">${foo}</code> literals respectively.</p> <p>Example (parsed representation is displayed after the <code class="language-plaintext highlighter-rouge">#</code>):</p> <div class="highlight"><pre class="highlight" data-language="">FROM busybox +ENV FOO=/bar +WORKDIR ${FOO} # WORKDIR /bar +ADD . $FOO # ADD . /bar +COPY \$FOO /quux # COPY $FOO /quux +</pre></div> <p>Environment variables are supported by the following list of instructions in the <code class="language-plaintext highlighter-rouge">Dockerfile</code>:</p> <ul> <li><code class="language-plaintext highlighter-rouge">ADD</code></li> <li><code class="language-plaintext highlighter-rouge">COPY</code></li> <li><code class="language-plaintext highlighter-rouge">ENV</code></li> <li><code class="language-plaintext highlighter-rouge">EXPOSE</code></li> <li><code class="language-plaintext highlighter-rouge">FROM</code></li> <li><code class="language-plaintext highlighter-rouge">LABEL</code></li> <li><code class="language-plaintext highlighter-rouge">STOPSIGNAL</code></li> <li><code class="language-plaintext highlighter-rouge">USER</code></li> <li><code class="language-plaintext highlighter-rouge">VOLUME</code></li> <li><code class="language-plaintext highlighter-rouge">WORKDIR</code></li> <li> +<code class="language-plaintext highlighter-rouge">ONBUILD</code> (when combined with one of the supported instructions above)</li> </ul> <p>Environment variable substitution will use the same value for each variable throughout the entire instruction. In other words, in this example:</p> <div class="highlight"><pre class="highlight" data-language="">ENV abc=hello +ENV abc=bye def=$abc +ENV ghi=$abc +</pre></div> <p>will result in <code class="language-plaintext highlighter-rouge">def</code> having a value of <code class="language-plaintext highlighter-rouge">hello</code>, not <code class="language-plaintext highlighter-rouge">bye</code>. However, <code class="language-plaintext highlighter-rouge">ghi</code> will have a value of <code class="language-plaintext highlighter-rouge">bye</code> because it is not part of the same instruction that set <code class="language-plaintext highlighter-rouge">abc</code> to <code class="language-plaintext highlighter-rouge">bye</code>.</p> <h2 id="dockerignore-file">.dockerignore file</h2> <p>Before the docker CLI sends the context to the docker daemon, it looks for a file named <code class="language-plaintext highlighter-rouge">.dockerignore</code> in the root directory of the context. If this file exists, the CLI modifies the context to exclude files and directories that match patterns in it. This helps to avoid unnecessarily sending large or sensitive files and directories to the daemon and potentially adding them to images using <code class="language-plaintext highlighter-rouge">ADD</code> or <code class="language-plaintext highlighter-rouge">COPY</code>.</p> <p>The CLI interprets the <code class="language-plaintext highlighter-rouge">.dockerignore</code> file as a newline-separated list of patterns similar to the file globs of Unix shells. For the purposes of matching, the root of the context is considered to be both the working and the root directory. For example, the patterns <code class="language-plaintext highlighter-rouge">/foo/bar</code> and <code class="language-plaintext highlighter-rouge">foo/bar</code> both exclude a file or directory named <code class="language-plaintext highlighter-rouge">bar</code> in the <code class="language-plaintext highlighter-rouge">foo</code> subdirectory of <code class="language-plaintext highlighter-rouge">PATH</code> or in the root of the git repository located at <code class="language-plaintext highlighter-rouge">URL</code>. Neither excludes anything else.</p> <p>If a line in <code class="language-plaintext highlighter-rouge">.dockerignore</code> file starts with <code class="language-plaintext highlighter-rouge">#</code> in column 1, then this line is considered as a comment and is ignored before interpreted by the CLI.</p> <p>Here is an example <code class="language-plaintext highlighter-rouge">.dockerignore</code> file:</p> <pre data-language=""># comment +*/temp* +*/*/temp* +temp? +</pre> <p>This file causes the following build behavior:</p> <table> <thead> <tr> <th style="text-align: left">Rule</th> <th style="text-align: left">Behavior</th> </tr> </thead> <tbody> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge"># comment</code></td> <td style="text-align: left">Ignored.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">*/temp*</code></td> <td style="text-align: left">Exclude files and directories whose names start with <code class="language-plaintext highlighter-rouge">temp</code> in any immediate subdirectory of the root. For example, the plain file <code class="language-plaintext highlighter-rouge">/somedir/temporary.txt</code> is excluded, as is the directory <code class="language-plaintext highlighter-rouge">/somedir/temp</code>.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">*/*/temp*</code></td> <td style="text-align: left">Exclude files and directories starting with <code class="language-plaintext highlighter-rouge">temp</code> from any subdirectory that is two levels below the root. For example, <code class="language-plaintext highlighter-rouge">/somedir/subdir/temporary.txt</code> is excluded.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">temp?</code></td> <td style="text-align: left">Exclude files and directories in the root directory whose names are a one-character extension of <code class="language-plaintext highlighter-rouge">temp</code>. For example, <code class="language-plaintext highlighter-rouge">/tempa</code> and <code class="language-plaintext highlighter-rouge">/tempb</code> are excluded.</td> </tr> </tbody> </table> <p>Matching is done using Go’s <a href="https://golang.org/pkg/path/filepath#Match">filepath.Match</a> rules. A preprocessing step removes leading and trailing whitespace and eliminates <code class="language-plaintext highlighter-rouge">.</code> and <code class="language-plaintext highlighter-rouge">..</code> elements using Go’s <a href="https://golang.org/pkg/path/filepath/#Clean">filepath.Clean</a>. Lines that are blank after preprocessing are ignored.</p> <p>Beyond Go’s filepath.Match rules, Docker also supports a special wildcard string <code class="language-plaintext highlighter-rouge">**</code> that matches any number of directories (including zero). For example, <code class="language-plaintext highlighter-rouge">**/*.go</code> will exclude all files that end with <code class="language-plaintext highlighter-rouge">.go</code> that are found in all directories, including the root of the build context.</p> <p>Lines starting with <code class="language-plaintext highlighter-rouge">!</code> (exclamation mark) can be used to make exceptions to exclusions. The following is an example <code class="language-plaintext highlighter-rouge">.dockerignore</code> file that uses this mechanism:</p> <pre data-language="">*.md +!README.md +</pre> <p>All markdown files <em>except</em> <code class="language-plaintext highlighter-rouge">README.md</code> are excluded from the context.</p> <p>The placement of <code class="language-plaintext highlighter-rouge">!</code> exception rules influences the behavior: the last line of the <code class="language-plaintext highlighter-rouge">.dockerignore</code> that matches a particular file determines whether it is included or excluded. Consider the following example:</p> <pre data-language="">*.md +!README*.md +README-secret.md +</pre> <p>No markdown files are included in the context except README files other than <code class="language-plaintext highlighter-rouge">README-secret.md</code>.</p> <p>Now consider this example:</p> <pre data-language="">*.md +README-secret.md +!README*.md +</pre> <p>All of the README files are included. The middle line has no effect because <code class="language-plaintext highlighter-rouge">!README*.md</code> matches <code class="language-plaintext highlighter-rouge">README-secret.md</code> and comes last.</p> <p>You can even use the <code class="language-plaintext highlighter-rouge">.dockerignore</code> file to exclude the <code class="language-plaintext highlighter-rouge">Dockerfile</code> and <code class="language-plaintext highlighter-rouge">.dockerignore</code> files. These files are still sent to the daemon because it needs them to do its job. But the <code class="language-plaintext highlighter-rouge">ADD</code> and <code class="language-plaintext highlighter-rouge">COPY</code> instructions do not copy them to the image.</p> <p>Finally, you may want to specify which files to include in the context, rather than which to exclude. To achieve this, specify <code class="language-plaintext highlighter-rouge">*</code> as the first pattern, followed by one or more <code class="language-plaintext highlighter-rouge">!</code> exception patterns.</p> <blockquote> <p><strong>Note</strong></p> <p>For historical reasons, the pattern <code class="language-plaintext highlighter-rouge">.</code> is ignored.</p> </blockquote> <h2 id="from">FROM</h2> <div class="highlight"><pre class="highlight" data-language="">FROM [--platform=<platform>] <image> [AS <name>] +</pre></div> <p>Or</p> <div class="highlight"><pre class="highlight" data-language="">FROM [--platform=<platform>] <image>[:<tag>] [AS <name>] +</pre></div> <p>Or</p> <div class="highlight"><pre class="highlight" data-language="">FROM [--platform=<platform>] <image>[@<digest>] [AS <name>] +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">FROM</code> instruction initializes a new build stage and sets the <a href="https://docs.docker.com/glossary/#base-image"><em>Base Image</em></a> for subsequent instructions. As such, a valid <code class="language-plaintext highlighter-rouge">Dockerfile</code> must start with a <code class="language-plaintext highlighter-rouge">FROM</code> instruction. The image can be any valid image – it is especially easy to start by <strong>pulling an image</strong> from the <a href="https://docs.docker.com/docker-hub/repos/"><em>Public Repositories</em></a>.</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">ARG</code> is the only instruction that may precede <code class="language-plaintext highlighter-rouge">FROM</code> in the <code class="language-plaintext highlighter-rouge">Dockerfile</code>. See <a href="#understand-how-arg-and-from-interact">Understand how ARG and FROM interact</a>.</li> <li> +<code class="language-plaintext highlighter-rouge">FROM</code> can appear multiple times within a single <code class="language-plaintext highlighter-rouge">Dockerfile</code> to create multiple images or use one build stage as a dependency for another. Simply make a note of the last image ID output by the commit before each new <code class="language-plaintext highlighter-rouge">FROM</code> instruction. Each <code class="language-plaintext highlighter-rouge">FROM</code> instruction clears any state created by previous instructions.</li> <li>Optionally a name can be given to a new build stage by adding <code class="language-plaintext highlighter-rouge">AS name</code> to the <code class="language-plaintext highlighter-rouge">FROM</code> instruction. The name can be used in subsequent <code class="language-plaintext highlighter-rouge">FROM</code> and <code class="language-plaintext highlighter-rouge">COPY --from=<name></code> instructions to refer to the image built in this stage.</li> <li>The <code class="language-plaintext highlighter-rouge">tag</code> or <code class="language-plaintext highlighter-rouge">digest</code> values are optional. If you omit either of them, the builder assumes a <code class="language-plaintext highlighter-rouge">latest</code> tag by default. The builder returns an error if it cannot find the <code class="language-plaintext highlighter-rouge">tag</code> value.</li> </ul> <p>The optional <code class="language-plaintext highlighter-rouge">--platform</code> flag can be used to specify the platform of the image in case <code class="language-plaintext highlighter-rouge">FROM</code> references a multi-platform image. For example, <code class="language-plaintext highlighter-rouge">linux/amd64</code>, <code class="language-plaintext highlighter-rouge">linux/arm64</code>, or <code class="language-plaintext highlighter-rouge">windows/amd64</code>. By default, the target platform of the build request is used. Global build arguments can be used in the value of this flag, for example <a href="#automatic-platform-args-in-the-global-scope">automatic platform ARGs</a> allow you to force a stage to native build platform (<code class="language-plaintext highlighter-rouge">--platform=$BUILDPLATFORM</code>), and use it to cross-compile to the target platform inside the stage.</p> <h3 id="understand-how-arg-and-from-interact">Understand how ARG and FROM interact</h3> <p><code class="language-plaintext highlighter-rouge">FROM</code> instructions support variables that are declared by any <code class="language-plaintext highlighter-rouge">ARG</code> instructions that occur before the first <code class="language-plaintext highlighter-rouge">FROM</code>.</p> <div class="highlight"><pre class="highlight" data-language="">ARG CODE_VERSION=latest +FROM base:${CODE_VERSION} +CMD /code/run-app + +FROM extras:${CODE_VERSION} +CMD /code/run-extras +</pre></div> <p>An <code class="language-plaintext highlighter-rouge">ARG</code> declared before a <code class="language-plaintext highlighter-rouge">FROM</code> is outside of a build stage, so it can’t be used in any instruction after a <code class="language-plaintext highlighter-rouge">FROM</code>. To use the default value of an <code class="language-plaintext highlighter-rouge">ARG</code> declared before the first <code class="language-plaintext highlighter-rouge">FROM</code> use an <code class="language-plaintext highlighter-rouge">ARG</code> instruction without a value inside of a build stage:</p> <div class="highlight"><pre class="highlight" data-language="">ARG VERSION=latest +FROM busybox:$VERSION +ARG VERSION +RUN echo $VERSION > image_version +</pre></div> <h2 id="run">RUN</h2> <p>RUN has 2 forms:</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">RUN <command></code> (<em>shell</em> form, the command is run in a shell, which by default is <code class="language-plaintext highlighter-rouge">/bin/sh -c</code> on Linux or <code class="language-plaintext highlighter-rouge">cmd /S /C</code> on Windows)</li> <li> +<code class="language-plaintext highlighter-rouge">RUN ["executable", "param1", "param2"]</code> (<em>exec</em> form)</li> </ul> <p>The <code class="language-plaintext highlighter-rouge">RUN</code> instruction will execute any commands in a new layer on top of the current image and commit the results. The resulting committed image will be used for the next step in the <code class="language-plaintext highlighter-rouge">Dockerfile</code>.</p> <p>Layering <code class="language-plaintext highlighter-rouge">RUN</code> instructions and generating commits conforms to the core concepts of Docker where commits are cheap and containers can be created from any point in an image’s history, much like source control.</p> <p>The <em>exec</em> form makes it possible to avoid shell string munging, and to <code class="language-plaintext highlighter-rouge">RUN</code> commands using a base image that does not contain the specified shell executable.</p> <p>The default shell for the <em>shell</em> form can be changed using the <code class="language-plaintext highlighter-rouge">SHELL</code> command.</p> <p>In the <em>shell</em> form you can use a <code class="language-plaintext highlighter-rouge">\</code> (backslash) to continue a single RUN instruction onto the next line. For example, consider these two lines:</p> <div class="highlight"><pre class="highlight" data-language="">RUN /bin/bash -c 'source $HOME/.bashrc; \ +echo $HOME' +</pre></div> <p>Together they are equivalent to this single line:</p> <div class="highlight"><pre class="highlight" data-language="">RUN /bin/bash -c 'source $HOME/.bashrc; echo $HOME' +</pre></div> <p>To use a different shell, other than ‘/bin/sh’, use the <em>exec</em> form passing in the desired shell. For example:</p> <div class="highlight"><pre class="highlight" data-language="">RUN ["/bin/bash", "-c", "echo hello"] +</pre></div> <blockquote> <p><strong>Note</strong></p> <p>The <em>exec</em> form is parsed as a JSON array, which means that you must use double-quotes (“) around words not single-quotes (‘).</p> </blockquote> <p>Unlike the <em>shell</em> form, the <em>exec</em> form does not invoke a command shell. This means that normal shell processing does not happen. For example, <code class="language-plaintext highlighter-rouge">RUN [ "echo", "$HOME" ]</code> will not do variable substitution on <code class="language-plaintext highlighter-rouge">$HOME</code>. If you want shell processing then either use the <em>shell</em> form or execute a shell directly, for example: <code class="language-plaintext highlighter-rouge">RUN [ "sh", "-c", "echo $HOME" ]</code>. When using the exec form and executing a shell directly, as in the case for the shell form, it is the shell that is doing the environment variable expansion, not docker.</p> <blockquote> <p><strong>Note</strong></p> <p>In the <em>JSON</em> form, it is necessary to escape backslashes. This is particularly relevant on Windows where the backslash is the path separator. The following line would otherwise be treated as <em>shell</em> form due to not being valid JSON, and fail in an unexpected way:</p> <div class="highlight"><pre class="highlight" data-language="">RUN ["c:\windows\system32\tasklist.exe"] +</pre></div> <p>The correct syntax for this example is:</p> <div class="highlight"><pre class="highlight" data-language="">RUN ["c:\\windows\\system32\\tasklist.exe"] +</pre></div> </blockquote> <p>The cache for <code class="language-plaintext highlighter-rouge">RUN</code> instructions isn’t invalidated automatically during the next build. The cache for an instruction like <code class="language-plaintext highlighter-rouge">RUN apt-get dist-upgrade -y</code> will be reused during the next build. The cache for <code class="language-plaintext highlighter-rouge">RUN</code> instructions can be invalidated by using the <code class="language-plaintext highlighter-rouge">--no-cache</code> flag, for example <code class="language-plaintext highlighter-rouge">docker build --no-cache</code>.</p> <p>See the <a href="https://docs.docker.com/develop/develop-images/dockerfile_best-practices/"><code class="language-plaintext highlighter-rouge">Dockerfile</code> Best Practices guide</a> for more information.</p> <p>The cache for <code class="language-plaintext highlighter-rouge">RUN</code> instructions can be invalidated by <a href="#add"><code class="language-plaintext highlighter-rouge">ADD</code></a> and <a href="#copy"><code class="language-plaintext highlighter-rouge">COPY</code></a> instructions.</p> <h3 id="known-issues-run">Known issues (RUN)</h3> <ul> <li> <p><a href="https://github.com/docker/docker/issues/783">Issue 783</a> is about file permissions problems that can occur when using the AUFS file system. You might notice it during an attempt to <code class="language-plaintext highlighter-rouge">rm</code> a file, for example.</p> <p>For systems that have recent aufs version (i.e., <code class="language-plaintext highlighter-rouge">dirperm1</code> mount option can be set), docker will attempt to fix the issue automatically by mounting the layers with <code class="language-plaintext highlighter-rouge">dirperm1</code> option. More details on <code class="language-plaintext highlighter-rouge">dirperm1</code> option can be found at <a href="https://github.com/sfjro/aufs3-linux/tree/aufs3.18/Documentation/filesystems/aufs"><code class="language-plaintext highlighter-rouge">aufs</code> man page</a></p> <p>If your system doesn’t have support for <code class="language-plaintext highlighter-rouge">dirperm1</code>, the issue describes a workaround.</p> </li> </ul> <h2 id="cmd">CMD</h2> <p>The <code class="language-plaintext highlighter-rouge">CMD</code> instruction has three forms:</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">CMD ["executable","param1","param2"]</code> (<em>exec</em> form, this is the preferred form)</li> <li> +<code class="language-plaintext highlighter-rouge">CMD ["param1","param2"]</code> (as <em>default parameters to ENTRYPOINT</em>)</li> <li> +<code class="language-plaintext highlighter-rouge">CMD command param1 param2</code> (<em>shell</em> form)</li> </ul> <p>There can only be one <code class="language-plaintext highlighter-rouge">CMD</code> instruction in a <code class="language-plaintext highlighter-rouge">Dockerfile</code>. If you list more than one <code class="language-plaintext highlighter-rouge">CMD</code> then only the last <code class="language-plaintext highlighter-rouge">CMD</code> will take effect.</p> <p><strong>The main purpose of a <code class="language-plaintext highlighter-rouge">CMD</code> is to provide defaults for an executing container.</strong> These defaults can include an executable, or they can omit the executable, in which case you must specify an <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> instruction as well.</p> <p>If <code class="language-plaintext highlighter-rouge">CMD</code> is used to provide default arguments for the <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> instruction, both the <code class="language-plaintext highlighter-rouge">CMD</code> and <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> instructions should be specified with the JSON array format.</p> <blockquote> <p><strong>Note</strong></p> <p>The <em>exec</em> form is parsed as a JSON array, which means that you must use double-quotes (“) around words not single-quotes (‘).</p> </blockquote> <p>Unlike the <em>shell</em> form, the <em>exec</em> form does not invoke a command shell. This means that normal shell processing does not happen. For example, <code class="language-plaintext highlighter-rouge">CMD [ "echo", "$HOME" ]</code> will not do variable substitution on <code class="language-plaintext highlighter-rouge">$HOME</code>. If you want shell processing then either use the <em>shell</em> form or execute a shell directly, for example: <code class="language-plaintext highlighter-rouge">CMD [ "sh", "-c", "echo $HOME" ]</code>. When using the exec form and executing a shell directly, as in the case for the shell form, it is the shell that is doing the environment variable expansion, not docker.</p> <p>When used in the shell or exec formats, the <code class="language-plaintext highlighter-rouge">CMD</code> instruction sets the command to be executed when running the image.</p> <p>If you use the <em>shell</em> form of the <code class="language-plaintext highlighter-rouge">CMD</code>, then the <code class="language-plaintext highlighter-rouge"><command></code> will execute in <code class="language-plaintext highlighter-rouge">/bin/sh -c</code>:</p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +CMD echo "This is a test." | wc - +</pre></div> <p>If you want to <strong>run your</strong> <code class="language-plaintext highlighter-rouge"><command></code> <strong>without a shell</strong> then you must express the command as a JSON array and give the full path to the executable. <strong>This array form is the preferred format of <code class="language-plaintext highlighter-rouge">CMD</code>.</strong> Any additional parameters must be individually expressed as strings in the array:</p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +CMD ["/usr/bin/wc","--help"] +</pre></div> <p>If you would like your container to run the same executable every time, then you should consider using <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> in combination with <code class="language-plaintext highlighter-rouge">CMD</code>. See <a href="#entrypoint"><em>ENTRYPOINT</em></a>.</p> <p>If the user specifies arguments to <code class="language-plaintext highlighter-rouge">docker run</code> then they will override the default specified in <code class="language-plaintext highlighter-rouge">CMD</code>.</p> <blockquote> <p><strong>Note</strong></p> <p>Do not confuse <code class="language-plaintext highlighter-rouge">RUN</code> with <code class="language-plaintext highlighter-rouge">CMD</code>. <code class="language-plaintext highlighter-rouge">RUN</code> actually runs a command and commits the result; <code class="language-plaintext highlighter-rouge">CMD</code> does not execute anything at build time, but specifies the intended command for the image.</p> </blockquote> <h2 id="label">LABEL</h2> <div class="highlight"><pre class="highlight" data-language="">LABEL <key>=<value> <key>=<value> <key>=<value> ... +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">LABEL</code> instruction adds metadata to an image. A <code class="language-plaintext highlighter-rouge">LABEL</code> is a key-value pair. To include spaces within a <code class="language-plaintext highlighter-rouge">LABEL</code> value, use quotes and backslashes as you would in command-line parsing. A few usage examples:</p> <div class="highlight"><pre class="highlight" data-language="">LABEL "com.example.vendor"="ACME Incorporated" +LABEL com.example.label-with-value="foo" +LABEL version="1.0" +LABEL description="This text illustrates \ +that label-values can span multiple lines." +</pre></div> <p>An image can have more than one label. You can specify multiple labels on a single line. Prior to Docker 1.10, this decreased the size of the final image, but this is no longer the case. You may still choose to specify multiple labels in a single instruction, in one of the following two ways:</p> <div class="highlight"><pre class="highlight" data-language="">LABEL multi.label1="value1" multi.label2="value2" other="value3" +</pre></div> <div class="highlight"><pre class="highlight" data-language="">LABEL multi.label1="value1" \ + multi.label2="value2" \ + other="value3" +</pre></div> <p>Labels included in base or parent images (images in the <code class="language-plaintext highlighter-rouge">FROM</code> line) are inherited by your image. If a label already exists but with a different value, the most-recently-applied value overrides any previously-set value.</p> <p>To view an image’s labels, use the <code class="language-plaintext highlighter-rouge">docker image inspect</code> command. You can use the <code class="language-plaintext highlighter-rouge">--format</code> option to show just the labels;</p> <div class="highlight"><pre class="highlight" data-language="">$ docker image inspect --format='' myimage +</pre></div> <div class="highlight"><pre class="highlight" data-language="">{ + "com.example.vendor": "ACME Incorporated", + "com.example.label-with-value": "foo", + "version": "1.0", + "description": "This text illustrates that label-values can span multiple lines.", + "multi.label1": "value1", + "multi.label2": "value2", + "other": "value3" +} +</pre></div> <h2 id="maintainer-deprecated">MAINTAINER (deprecated)</h2> <div class="highlight"><pre class="highlight" data-language="">MAINTAINER <name> +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">MAINTAINER</code> instruction sets the <em>Author</em> field of the generated images. The <code class="language-plaintext highlighter-rouge">LABEL</code> instruction is a much more flexible version of this and you should use it instead, as it enables setting any metadata you require, and can be viewed easily, for example with <code class="language-plaintext highlighter-rouge">docker inspect</code>. To set a label corresponding to the <code class="language-plaintext highlighter-rouge">MAINTAINER</code> field you could use:</p> <div class="highlight"><pre class="highlight" data-language="">LABEL org.opencontainers.image.authors="SvenDowideit@home.org.au" +</pre></div> <p>This will then be visible from <code class="language-plaintext highlighter-rouge">docker inspect</code> with the other labels.</p> <h2 id="expose">EXPOSE</h2> <div class="highlight"><pre class="highlight" data-language="">EXPOSE <port> [<port>/<protocol>...] +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">EXPOSE</code> instruction informs Docker that the container listens on the specified network ports at runtime. You can specify whether the port listens on TCP or UDP, and the default is TCP if the protocol is not specified.</p> <p>The <code class="language-plaintext highlighter-rouge">EXPOSE</code> instruction does not actually publish the port. It functions as a type of documentation between the person who builds the image and the person who runs the container, about which ports are intended to be published. To actually publish the port when running the container, use the <code class="language-plaintext highlighter-rouge">-p</code> flag on <code class="language-plaintext highlighter-rouge">docker run</code> to publish and map one or more ports, or the <code class="language-plaintext highlighter-rouge">-P</code> flag to publish all exposed ports and map them to high-order ports.</p> <p>By default, <code class="language-plaintext highlighter-rouge">EXPOSE</code> assumes TCP. You can also specify UDP:</p> <div class="highlight"><pre class="highlight" data-language="">EXPOSE 80/udp +</pre></div> <p>To expose on both TCP and UDP, include two lines:</p> <div class="highlight"><pre class="highlight" data-language="">EXPOSE 80/tcp +EXPOSE 80/udp +</pre></div> <p>In this case, if you use <code class="language-plaintext highlighter-rouge">-P</code> with <code class="language-plaintext highlighter-rouge">docker run</code>, the port will be exposed once for TCP and once for UDP. Remember that <code class="language-plaintext highlighter-rouge">-P</code> uses an ephemeral high-ordered host port on the host, so the port will not be the same for TCP and UDP.</p> <p>Regardless of the <code class="language-plaintext highlighter-rouge">EXPOSE</code> settings, you can override them at runtime by using the <code class="language-plaintext highlighter-rouge">-p</code> flag. For example</p> <div class="highlight"><pre class="highlight" data-language="">$ docker run -p 80:80/tcp -p 80:80/udp ... +</pre></div> <p>To set up port redirection on the host system, see <a href="../run/index#expose-incoming-ports">using the -P flag</a>. The <code class="language-plaintext highlighter-rouge">docker network</code> command supports creating networks for communication among containers without the need to expose or publish specific ports, because the containers connected to the network can communicate with each other over any port. For detailed information, see the <a href="https://docs.docker.com/network/">overview of this feature</a>.</p> <h2 id="env">ENV</h2> <div class="highlight"><pre class="highlight" data-language="">ENV <key>=<value> ... +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">ENV</code> instruction sets the environment variable <code class="language-plaintext highlighter-rouge"><key></code> to the value <code class="language-plaintext highlighter-rouge"><value></code>. This value will be in the environment for all subsequent instructions in the build stage and can be <a href="#environment-replacement">replaced inline</a> in many as well. The value will be interpreted for other environment variables, so quote characters will be removed if they are not escaped. Like command line parsing, quotes and backslashes can be used to include spaces within values.</p> <p>Example:</p> <div class="highlight"><pre class="highlight" data-language="">ENV MY_NAME="John Doe" +ENV MY_DOG=Rex\ The\ Dog +ENV MY_CAT=fluffy +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">ENV</code> instruction allows for multiple <code class="language-plaintext highlighter-rouge"><key>=<value> ...</code> variables to be set at one time, and the example below will yield the same net results in the final image:</p> <div class="highlight"><pre class="highlight" data-language="">ENV MY_NAME="John Doe" MY_DOG=Rex\ The\ Dog \ + MY_CAT=fluffy +</pre></div> <p>The environment variables set using <code class="language-plaintext highlighter-rouge">ENV</code> will persist when a container is run from the resulting image. You can view the values using <code class="language-plaintext highlighter-rouge">docker inspect</code>, and change them using <code class="language-plaintext highlighter-rouge">docker run --env <key>=<value></code>.</p> <p>Environment variable persistence can cause unexpected side effects. For example, setting <code class="language-plaintext highlighter-rouge">ENV DEBIAN_FRONTEND=noninteractive</code> changes the behavior of <code class="language-plaintext highlighter-rouge">apt-get</code>, and may confuse users of your image.</p> <p>If an environment variable is only needed during build, and not in the final image, consider setting a value for a single command instead:</p> <div class="highlight"><pre class="highlight" data-language="">RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y ... +</pre></div> <p>Or using <a href="#arg"><code class="language-plaintext highlighter-rouge">ARG</code></a>, which is not persisted in the final image:</p> <div class="highlight"><pre class="highlight" data-language="">ARG DEBIAN_FRONTEND=noninteractive +RUN apt-get update && apt-get install -y ... +</pre></div> <blockquote> <p><strong>Alternative syntax</strong></p> <p>The <code class="language-plaintext highlighter-rouge">ENV</code> instruction also allows an alternative syntax <code class="language-plaintext highlighter-rouge">ENV <key> <value></code>, omitting the <code class="language-plaintext highlighter-rouge">=</code>. For example:</p> <div class="highlight"><pre class="highlight" data-language="">ENV MY_VAR my-value +</pre></div> <p>This syntax does not allow for multiple environment-variables to be set in a single <code class="language-plaintext highlighter-rouge">ENV</code> instruction, and can be confusing. For example, the following sets a single environment variable (<code class="language-plaintext highlighter-rouge">ONE</code>) with value <code class="language-plaintext highlighter-rouge">"TWO= THREE=world"</code>:</p> <div class="highlight"><pre class="highlight" data-language="">ENV ONE TWO= THREE=world +</pre></div> <p>The alternative syntax is supported for backward compatibility, but discouraged for the reasons outlined above, and may be removed in a future release.</p> </blockquote> <h2 id="add">ADD</h2> <p>ADD has two forms:</p> <div class="highlight"><pre class="highlight" data-language="">ADD [--chown=<user>:<group>] <src>... <dest> +ADD [--chown=<user>:<group>] ["<src>",... "<dest>"] +</pre></div> <p>The latter form is required for paths containing whitespace.</p> <blockquote> <p><strong>Note</strong></p> <p>The <code class="language-plaintext highlighter-rouge">--chown</code> feature is only supported on Dockerfiles used to build Linux containers, and will not work on Windows containers. Since user and group ownership concepts do not translate between Linux and Windows, the use of <code class="language-plaintext highlighter-rouge">/etc/passwd</code> and <code class="language-plaintext highlighter-rouge">/etc/group</code> for translating user and group names to IDs restricts this feature to only be viable for Linux OS-based containers.</p> </blockquote> <p>The <code class="language-plaintext highlighter-rouge">ADD</code> instruction copies new files, directories or remote file URLs from <code class="language-plaintext highlighter-rouge"><src></code> and adds them to the filesystem of the image at the path <code class="language-plaintext highlighter-rouge"><dest></code>.</p> <p>Multiple <code class="language-plaintext highlighter-rouge"><src></code> resources may be specified but if they are files or directories, their paths are interpreted as relative to the source of the context of the build.</p> <p>Each <code class="language-plaintext highlighter-rouge"><src></code> may contain wildcards and matching will be done using Go’s <a href="https://golang.org/pkg/path/filepath#Match">filepath.Match</a> rules. For example:</p> <p>To add all files starting with “hom”:</p> <div class="highlight"><pre class="highlight" data-language="">ADD hom* /mydir/ +</pre></div> <p>In the example below, <code class="language-plaintext highlighter-rouge">?</code> is replaced with any single character, e.g., “home.txt”.</p> <div class="highlight"><pre class="highlight" data-language="">ADD hom?.txt /mydir/ +</pre></div> <p>The <code class="language-plaintext highlighter-rouge"><dest></code> is an absolute path, or a path relative to <code class="language-plaintext highlighter-rouge">WORKDIR</code>, into which the source will be copied inside the destination container.</p> <p>The example below uses a relative path, and adds “test.txt” to <code class="language-plaintext highlighter-rouge"><WORKDIR>/relativeDir/</code>:</p> <div class="highlight"><pre class="highlight" data-language="">ADD test.txt relativeDir/ +</pre></div> <p>Whereas this example uses an absolute path, and adds “test.txt” to <code class="language-plaintext highlighter-rouge">/absoluteDir/</code></p> <div class="highlight"><pre class="highlight" data-language="">ADD test.txt /absoluteDir/ +</pre></div> <p>When adding files or directories that contain special characters (such as <code class="language-plaintext highlighter-rouge">[</code> and <code class="language-plaintext highlighter-rouge">]</code>), you need to escape those paths following the Golang rules to prevent them from being treated as a matching pattern. For example, to add a file named <code class="language-plaintext highlighter-rouge">arr[0].txt</code>, use the following;</p> <div class="highlight"><pre class="highlight" data-language="">ADD arr[[]0].txt /mydir/ +</pre></div> <p>All new files and directories are created with a UID and GID of 0, unless the optional <code class="language-plaintext highlighter-rouge">--chown</code> flag specifies a given username, groupname, or UID/GID combination to request specific ownership of the content added. The format of the <code class="language-plaintext highlighter-rouge">--chown</code> flag allows for either username and groupname strings or direct integer UID and GID in any combination. Providing a username without groupname or a UID without GID will use the same numeric UID as the GID. If a username or groupname is provided, the container’s root filesystem <code class="language-plaintext highlighter-rouge">/etc/passwd</code> and <code class="language-plaintext highlighter-rouge">/etc/group</code> files will be used to perform the translation from name to integer UID or GID respectively. The following examples show valid definitions for the <code class="language-plaintext highlighter-rouge">--chown</code> flag:</p> <div class="highlight"><pre class="highlight" data-language="">ADD --chown=55:mygroup files* /somedir/ +ADD --chown=bin files* /somedir/ +ADD --chown=1 files* /somedir/ +ADD --chown=10:11 files* /somedir/ +</pre></div> <p>If the container root filesystem does not contain either <code class="language-plaintext highlighter-rouge">/etc/passwd</code> or <code class="language-plaintext highlighter-rouge">/etc/group</code> files and either user or group names are used in the <code class="language-plaintext highlighter-rouge">--chown</code> flag, the build will fail on the <code class="language-plaintext highlighter-rouge">ADD</code> operation. Using numeric IDs requires no lookup and will not depend on container root filesystem content.</p> <p>In the case where <code class="language-plaintext highlighter-rouge"><src></code> is a remote file URL, the destination will have permissions of 600. If the remote file being retrieved has an HTTP <code class="language-plaintext highlighter-rouge">Last-Modified</code> header, the timestamp from that header will be used to set the <code class="language-plaintext highlighter-rouge">mtime</code> on the destination file. However, like any other file processed during an <code class="language-plaintext highlighter-rouge">ADD</code>, <code class="language-plaintext highlighter-rouge">mtime</code> will not be included in the determination of whether or not the file has changed and the cache should be updated.</p> <blockquote> <p><strong>Note</strong></p> <p>If you build by passing a <code class="language-plaintext highlighter-rouge">Dockerfile</code> through STDIN (<code class="language-plaintext highlighter-rouge">docker build - < somefile</code>), there is no build context, so the <code class="language-plaintext highlighter-rouge">Dockerfile</code> can only contain a URL based <code class="language-plaintext highlighter-rouge">ADD</code> instruction. You can also pass a compressed archive through STDIN: (<code class="language-plaintext highlighter-rouge">docker build - < archive.tar.gz</code>), the <code class="language-plaintext highlighter-rouge">Dockerfile</code> at the root of the archive and the rest of the archive will be used as the context of the build.</p> </blockquote> <p>If your URL files are protected using authentication, you need to use <code class="language-plaintext highlighter-rouge">RUN wget</code>, <code class="language-plaintext highlighter-rouge">RUN curl</code> or use another tool from within the container as the <code class="language-plaintext highlighter-rouge">ADD</code> instruction does not support authentication.</p> <blockquote> <p><strong>Note</strong></p> <p>The first encountered <code class="language-plaintext highlighter-rouge">ADD</code> instruction will invalidate the cache for all following instructions from the Dockerfile if the contents of <code class="language-plaintext highlighter-rouge"><src></code> have changed. This includes invalidating the cache for <code class="language-plaintext highlighter-rouge">RUN</code> instructions. See the <a href="https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#leverage-build-cache"><code class="language-plaintext highlighter-rouge">Dockerfile</code> Best Practices guide – Leverage build cache</a> for more information.</p> </blockquote> <p><code class="language-plaintext highlighter-rouge">ADD</code> obeys the following rules:</p> <ul> <li> <p>The <code class="language-plaintext highlighter-rouge"><src></code> path must be inside the <em>context</em> of the build; you cannot <code class="language-plaintext highlighter-rouge">ADD ../something /something</code>, because the first step of a <code class="language-plaintext highlighter-rouge">docker build</code> is to send the context directory (and subdirectories) to the docker daemon.</p> </li> <li> <p>If <code class="language-plaintext highlighter-rouge"><src></code> is a URL and <code class="language-plaintext highlighter-rouge"><dest></code> does not end with a trailing slash, then a file is downloaded from the URL and copied to <code class="language-plaintext highlighter-rouge"><dest></code>.</p> </li> <li> <p>If <code class="language-plaintext highlighter-rouge"><src></code> is a URL and <code class="language-plaintext highlighter-rouge"><dest></code> does end with a trailing slash, then the filename is inferred from the URL and the file is downloaded to <code class="language-plaintext highlighter-rouge"><dest>/<filename></code>. For instance, <code class="language-plaintext highlighter-rouge">ADD http://example.com/foobar /</code> would create the file <code class="language-plaintext highlighter-rouge">/foobar</code>. The URL must have a nontrivial path so that an appropriate filename can be discovered in this case (<code class="language-plaintext highlighter-rouge">http://example.com</code> will not work).</p> </li> <li> <p>If <code class="language-plaintext highlighter-rouge"><src></code> is a directory, the entire contents of the directory are copied, including filesystem metadata.</p> </li> </ul> <blockquote> <p><strong>Note</strong></p> <p>The directory itself is not copied, just its contents.</p> </blockquote> <ul> <li> <p>If <code class="language-plaintext highlighter-rouge"><src></code> is a <em>local</em> tar archive in a recognized compression format (identity, gzip, bzip2 or xz) then it is unpacked as a directory. Resources from <em>remote</em> URLs are <strong>not</strong> decompressed. When a directory is copied or unpacked, it has the same behavior as <code class="language-plaintext highlighter-rouge">tar -x</code>, the result is the union of:</p> <ol> <li>Whatever existed at the destination path and</li> <li>The contents of the source tree, with conflicts resolved in favor of “2.” on a file-by-file basis.</li> </ol> <blockquote> <p><strong>Note</strong></p> <p>Whether a file is identified as a recognized compression format or not is done solely based on the contents of the file, not the name of the file. For example, if an empty file happens to end with <code class="language-plaintext highlighter-rouge">.tar.gz</code> this will not be recognized as a compressed file and <strong>will not</strong> generate any kind of decompression error message, rather the file will simply be copied to the destination.</p> </blockquote> </li> <li> <p>If <code class="language-plaintext highlighter-rouge"><src></code> is any other kind of file, it is copied individually along with its metadata. In this case, if <code class="language-plaintext highlighter-rouge"><dest></code> ends with a trailing slash <code class="language-plaintext highlighter-rouge">/</code>, it will be considered a directory and the contents of <code class="language-plaintext highlighter-rouge"><src></code> will be written at <code class="language-plaintext highlighter-rouge"><dest>/base(<src>)</code>.</p> </li> <li> <p>If multiple <code class="language-plaintext highlighter-rouge"><src></code> resources are specified, either directly or due to the use of a wildcard, then <code class="language-plaintext highlighter-rouge"><dest></code> must be a directory, and it must end with a slash <code class="language-plaintext highlighter-rouge">/</code>.</p> </li> <li> <p>If <code class="language-plaintext highlighter-rouge"><dest></code> does not end with a trailing slash, it will be considered a regular file and the contents of <code class="language-plaintext highlighter-rouge"><src></code> will be written at <code class="language-plaintext highlighter-rouge"><dest></code>.</p> </li> <li> <p>If <code class="language-plaintext highlighter-rouge"><dest></code> doesn’t exist, it is created along with all missing directories in its path.</p> </li> </ul> <h2 id="copy">COPY</h2> <p>COPY has two forms:</p> <div class="highlight"><pre class="highlight" data-language="">COPY [--chown=<user>:<group>] <src>... <dest> +COPY [--chown=<user>:<group>] ["<src>",... "<dest>"] +</pre></div> <p>This latter form is required for paths containing whitespace</p> <blockquote> <p><strong>Note</strong></p> <p>The <code class="language-plaintext highlighter-rouge">--chown</code> feature is only supported on Dockerfiles used to build Linux containers, and will not work on Windows containers. Since user and group ownership concepts do not translate between Linux and Windows, the use of <code class="language-plaintext highlighter-rouge">/etc/passwd</code> and <code class="language-plaintext highlighter-rouge">/etc/group</code> for translating user and group names to IDs restricts this feature to only be viable for Linux OS-based containers.</p> </blockquote> <p>The <code class="language-plaintext highlighter-rouge">COPY</code> instruction copies new files or directories from <code class="language-plaintext highlighter-rouge"><src></code> and adds them to the filesystem of the container at the path <code class="language-plaintext highlighter-rouge"><dest></code>.</p> <p>Multiple <code class="language-plaintext highlighter-rouge"><src></code> resources may be specified but the paths of files and directories will be interpreted as relative to the source of the context of the build.</p> <p>Each <code class="language-plaintext highlighter-rouge"><src></code> may contain wildcards and matching will be done using Go’s <a href="https://golang.org/pkg/path/filepath#Match">filepath.Match</a> rules. For example:</p> <p>To add all files starting with “hom”:</p> <div class="highlight"><pre class="highlight" data-language="">COPY hom* /mydir/ +</pre></div> <p>In the example below, <code class="language-plaintext highlighter-rouge">?</code> is replaced with any single character, e.g., “home.txt”.</p> <div class="highlight"><pre class="highlight" data-language="">COPY hom?.txt /mydir/ +</pre></div> <p>The <code class="language-plaintext highlighter-rouge"><dest></code> is an absolute path, or a path relative to <code class="language-plaintext highlighter-rouge">WORKDIR</code>, into which the source will be copied inside the destination container.</p> <p>The example below uses a relative path, and adds “test.txt” to <code class="language-plaintext highlighter-rouge"><WORKDIR>/relativeDir/</code>:</p> <div class="highlight"><pre class="highlight" data-language="">COPY test.txt relativeDir/ +</pre></div> <p>Whereas this example uses an absolute path, and adds “test.txt” to <code class="language-plaintext highlighter-rouge">/absoluteDir/</code></p> <div class="highlight"><pre class="highlight" data-language="">COPY test.txt /absoluteDir/ +</pre></div> <p>When copying files or directories that contain special characters (such as <code class="language-plaintext highlighter-rouge">[</code> and <code class="language-plaintext highlighter-rouge">]</code>), you need to escape those paths following the Golang rules to prevent them from being treated as a matching pattern. For example, to copy a file named <code class="language-plaintext highlighter-rouge">arr[0].txt</code>, use the following;</p> <div class="highlight"><pre class="highlight" data-language="">COPY arr[[]0].txt /mydir/ +</pre></div> <p>All new files and directories are created with a UID and GID of 0, unless the optional <code class="language-plaintext highlighter-rouge">--chown</code> flag specifies a given username, groupname, or UID/GID combination to request specific ownership of the copied content. The format of the <code class="language-plaintext highlighter-rouge">--chown</code> flag allows for either username and groupname strings or direct integer UID and GID in any combination. Providing a username without groupname or a UID without GID will use the same numeric UID as the GID. If a username or groupname is provided, the container’s root filesystem <code class="language-plaintext highlighter-rouge">/etc/passwd</code> and <code class="language-plaintext highlighter-rouge">/etc/group</code> files will be used to perform the translation from name to integer UID or GID respectively. The following examples show valid definitions for the <code class="language-plaintext highlighter-rouge">--chown</code> flag:</p> <div class="highlight"><pre class="highlight" data-language="">COPY --chown=55:mygroup files* /somedir/ +COPY --chown=bin files* /somedir/ +COPY --chown=1 files* /somedir/ +COPY --chown=10:11 files* /somedir/ +</pre></div> <p>If the container root filesystem does not contain either <code class="language-plaintext highlighter-rouge">/etc/passwd</code> or <code class="language-plaintext highlighter-rouge">/etc/group</code> files and either user or group names are used in the <code class="language-plaintext highlighter-rouge">--chown</code> flag, the build will fail on the <code class="language-plaintext highlighter-rouge">COPY</code> operation. Using numeric IDs requires no lookup and does not depend on container root filesystem content.</p> <blockquote> <p><strong>Note</strong></p> <p>If you build using STDIN (<code class="language-plaintext highlighter-rouge">docker build - < somefile</code>), there is no build context, so <code class="language-plaintext highlighter-rouge">COPY</code> can’t be used.</p> </blockquote> <p>Optionally <code class="language-plaintext highlighter-rouge">COPY</code> accepts a flag <code class="language-plaintext highlighter-rouge">--from=<name></code> that can be used to set the source location to a previous build stage (created with <code class="language-plaintext highlighter-rouge">FROM .. AS <name></code>) that will be used instead of a build context sent by the user. In case a build stage with a specified name can’t be found an image with the same name is attempted to be used instead.</p> <p><code class="language-plaintext highlighter-rouge">COPY</code> obeys the following rules:</p> <ul> <li> <p>The <code class="language-plaintext highlighter-rouge"><src></code> path must be inside the <em>context</em> of the build; you cannot <code class="language-plaintext highlighter-rouge">COPY ../something /something</code>, because the first step of a <code class="language-plaintext highlighter-rouge">docker build</code> is to send the context directory (and subdirectories) to the docker daemon.</p> </li> <li> <p>If <code class="language-plaintext highlighter-rouge"><src></code> is a directory, the entire contents of the directory are copied, including filesystem metadata.</p> </li> </ul> <blockquote> <p><strong>Note</strong></p> <p>The directory itself is not copied, just its contents.</p> </blockquote> <ul> <li> <p>If <code class="language-plaintext highlighter-rouge"><src></code> is any other kind of file, it is copied individually along with its metadata. In this case, if <code class="language-plaintext highlighter-rouge"><dest></code> ends with a trailing slash <code class="language-plaintext highlighter-rouge">/</code>, it will be considered a directory and the contents of <code class="language-plaintext highlighter-rouge"><src></code> will be written at <code class="language-plaintext highlighter-rouge"><dest>/base(<src>)</code>.</p> </li> <li> <p>If multiple <code class="language-plaintext highlighter-rouge"><src></code> resources are specified, either directly or due to the use of a wildcard, then <code class="language-plaintext highlighter-rouge"><dest></code> must be a directory, and it must end with a slash <code class="language-plaintext highlighter-rouge">/</code>.</p> </li> <li> <p>If <code class="language-plaintext highlighter-rouge"><dest></code> does not end with a trailing slash, it will be considered a regular file and the contents of <code class="language-plaintext highlighter-rouge"><src></code> will be written at <code class="language-plaintext highlighter-rouge"><dest></code>.</p> </li> <li> <p>If <code class="language-plaintext highlighter-rouge"><dest></code> doesn’t exist, it is created along with all missing directories in its path.</p> </li> </ul> <blockquote> <p><strong>Note</strong></p> <p>The first encountered <code class="language-plaintext highlighter-rouge">COPY</code> instruction will invalidate the cache for all following instructions from the Dockerfile if the contents of <code class="language-plaintext highlighter-rouge"><src></code> have changed. This includes invalidating the cache for <code class="language-plaintext highlighter-rouge">RUN</code> instructions. See the <a href="https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#leverage-build-cache"><code class="language-plaintext highlighter-rouge">Dockerfile</code> Best Practices guide – Leverage build cache</a> for more information.</p> </blockquote> <h2 id="entrypoint">ENTRYPOINT</h2> <p>ENTRYPOINT has two forms:</p> <p>The <em>exec</em> form, which is the preferred form:</p> <div class="highlight"><pre class="highlight" data-language="">ENTRYPOINT ["executable", "param1", "param2"] +</pre></div> <p>The <em>shell</em> form:</p> <div class="highlight"><pre class="highlight" data-language="">ENTRYPOINT command param1 param2 +</pre></div> <p>An <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> allows you to configure a container that will run as an executable.</p> <p>For example, the following starts nginx with its default content, listening on port 80:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker run -i -t --rm -p 80:80 nginx +</pre></div> <p>Command line arguments to <code class="language-plaintext highlighter-rouge">docker run <image></code> will be appended after all elements in an <em>exec</em> form <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code>, and will override all elements specified using <code class="language-plaintext highlighter-rouge">CMD</code>. This allows arguments to be passed to the entry point, i.e., <code class="language-plaintext highlighter-rouge">docker run <image> -d</code> will pass the <code class="language-plaintext highlighter-rouge">-d</code> argument to the entry point. You can override the <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> instruction using the <code class="language-plaintext highlighter-rouge">docker run --entrypoint</code> flag.</p> <p>The <em>shell</em> form prevents any <code class="language-plaintext highlighter-rouge">CMD</code> or <code class="language-plaintext highlighter-rouge">run</code> command line arguments from being used, but has the disadvantage that your <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> will be started as a subcommand of <code class="language-plaintext highlighter-rouge">/bin/sh -c</code>, which does not pass signals. This means that the executable will not be the container’s <code class="language-plaintext highlighter-rouge">PID 1</code> - and will <em>not</em> receive Unix signals - so your executable will not receive a <code class="language-plaintext highlighter-rouge">SIGTERM</code> from <code class="language-plaintext highlighter-rouge">docker stop <container></code>.</p> <p>Only the last <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> instruction in the <code class="language-plaintext highlighter-rouge">Dockerfile</code> will have an effect.</p> <h3 id="exec-form-entrypoint-example">Exec form ENTRYPOINT example</h3> <p>You can use the <em>exec</em> form of <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> to set fairly stable default commands and arguments and then use either form of <code class="language-plaintext highlighter-rouge">CMD</code> to set additional defaults that are more likely to be changed.</p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +ENTRYPOINT ["top", "-b"] +CMD ["-c"] +</pre></div> <p>When you run the container, you can see that <code class="language-plaintext highlighter-rouge">top</code> is the only process:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker run -it --rm --name test top -H + +top - 08:25:00 up 7:27, 0 users, load average: 0.00, 0.01, 0.05 +Threads: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie +%Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.7 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st +KiB Mem: 2056668 total, 1616832 used, 439836 free, 99352 buffers +KiB Swap: 1441840 total, 0 used, 1441840 free. 1324440 cached Mem + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 19744 2336 2080 R 0.0 0.1 0:00.04 top +</pre></div> <p>To examine the result further, you can use <code class="language-plaintext highlighter-rouge">docker exec</code>:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker exec -it test ps aux + +USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND +root 1 2.6 0.1 19752 2352 ? Ss+ 08:24 0:00 top -b -H +root 7 0.0 0.1 15572 2164 ? R+ 08:25 0:00 ps aux +</pre></div> <p>And you can gracefully request <code class="language-plaintext highlighter-rouge">top</code> to shut down using <code class="language-plaintext highlighter-rouge">docker stop test</code>.</p> <p>The following <code class="language-plaintext highlighter-rouge">Dockerfile</code> shows using the <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> to run Apache in the foreground (i.e., as <code class="language-plaintext highlighter-rouge">PID 1</code>):</p> <div class="highlight"><pre class="highlight" data-language="">FROM debian:stable +RUN apt-get update && apt-get install -y --force-yes apache2 +EXPOSE 80 443 +VOLUME ["/var/www", "/var/log/apache2", "/etc/apache2"] +ENTRYPOINT ["/usr/sbin/apache2ctl", "-D", "FOREGROUND"] +</pre></div> <p>If you need to write a starter script for a single executable, you can ensure that the final executable receives the Unix signals by using <code class="language-plaintext highlighter-rouge">exec</code> and <code class="language-plaintext highlighter-rouge">gosu</code> commands:</p> <div class="highlight"><pre class="highlight" data-language="">#!/usr/bin/env bash +set -e + +if [ "$1" = 'postgres' ]; then + chown -R postgres "$PGDATA" + + if [ -z "$(ls -A "$PGDATA")" ]; then + gosu postgres initdb + fi + + exec gosu postgres "$@" +fi + +exec "$@" +</pre></div> <p>Lastly, if you need to do some extra cleanup (or communicate with other containers) on shutdown, or are co-ordinating more than one executable, you may need to ensure that the <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> script receives the Unix signals, passes them on, and then does some more work:</p> <div class="highlight"><pre class="highlight" data-language="">#!/bin/sh +# Note: I've written this using sh so it works in the busybox container too + +# USE the trap if you need to also do manual cleanup after the service is stopped, +# or need to start multiple services in the one container +trap "echo TRAPed signal" HUP INT QUIT TERM + +# start service in background here +/usr/sbin/apachectl start + +echo "[hit enter key to exit] or run 'docker stop <container>'" +read + +# stop service and clean up here +echo "stopping apache" +/usr/sbin/apachectl stop + +echo "exited $0" +</pre></div> <p>If you run this image with <code class="language-plaintext highlighter-rouge">docker run -it --rm -p 80:80 --name test apache</code>, you can then examine the container’s processes with <code class="language-plaintext highlighter-rouge">docker exec</code>, or <code class="language-plaintext highlighter-rouge">docker top</code>, and then ask the script to stop Apache:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker exec -it test ps aux + +USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND +root 1 0.1 0.0 4448 692 ? Ss+ 00:42 0:00 /bin/sh /run.sh 123 cmd cmd2 +root 19 0.0 0.2 71304 4440 ? Ss 00:42 0:00 /usr/sbin/apache2 -k start +www-data 20 0.2 0.2 360468 6004 ? Sl 00:42 0:00 /usr/sbin/apache2 -k start +www-data 21 0.2 0.2 360468 6000 ? Sl 00:42 0:00 /usr/sbin/apache2 -k start +root 81 0.0 0.1 15572 2140 ? R+ 00:44 0:00 ps aux + +$ docker top test + +PID USER COMMAND +10035 root {run.sh} /bin/sh /run.sh 123 cmd cmd2 +10054 root /usr/sbin/apache2 -k start +10055 33 /usr/sbin/apache2 -k start +10056 33 /usr/sbin/apache2 -k start + +$ /usr/bin/time docker stop test + +test +real 0m 0.27s +user 0m 0.03s +sys 0m 0.03s +</pre></div> <blockquote> <p><strong>Note</strong></p> <p>You can override the <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> setting using <code class="language-plaintext highlighter-rouge">--entrypoint</code>, but this can only set the binary to <em>exec</em> (no <code class="language-plaintext highlighter-rouge">sh -c</code> will be used).</p> </blockquote> <blockquote> <p><strong>Note</strong></p> <p>The <em>exec</em> form is parsed as a JSON array, which means that you must use double-quotes (“) around words not single-quotes (‘).</p> </blockquote> <p>Unlike the <em>shell</em> form, the <em>exec</em> form does not invoke a command shell. This means that normal shell processing does not happen. For example, <code class="language-plaintext highlighter-rouge">ENTRYPOINT [ "echo", "$HOME" ]</code> will not do variable substitution on <code class="language-plaintext highlighter-rouge">$HOME</code>. If you want shell processing then either use the <em>shell</em> form or execute a shell directly, for example: <code class="language-plaintext highlighter-rouge">ENTRYPOINT [ "sh", "-c", "echo $HOME" ]</code>. When using the exec form and executing a shell directly, as in the case for the shell form, it is the shell that is doing the environment variable expansion, not docker.</p> <h3 id="shell-form-entrypoint-example">Shell form ENTRYPOINT example</h3> <p>You can specify a plain string for the <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> and it will execute in <code class="language-plaintext highlighter-rouge">/bin/sh -c</code>. This form will use shell processing to substitute shell environment variables, and will ignore any <code class="language-plaintext highlighter-rouge">CMD</code> or <code class="language-plaintext highlighter-rouge">docker run</code> command line arguments. To ensure that <code class="language-plaintext highlighter-rouge">docker stop</code> will signal any long running <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> executable correctly, you need to remember to start it with <code class="language-plaintext highlighter-rouge">exec</code>:</p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +ENTRYPOINT exec top -b +</pre></div> <p>When you run this image, you’ll see the single <code class="language-plaintext highlighter-rouge">PID 1</code> process:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker run -it --rm --name test top + +Mem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cached +CPU: 5% usr 0% sys 0% nic 94% idle 0% io 0% irq 0% sirq +Load average: 0.08 0.03 0.05 2/98 6 + PID PPID USER STAT VSZ %VSZ %CPU COMMAND + 1 0 root R 3164 0% 0% top -b +</pre></div> <p>Which exits cleanly on <code class="language-plaintext highlighter-rouge">docker stop</code>:</p> <div class="highlight"><pre class="highlight" data-language="">$ /usr/bin/time docker stop test + +test +real 0m 0.20s +user 0m 0.02s +sys 0m 0.04s +</pre></div> <p>If you forget to add <code class="language-plaintext highlighter-rouge">exec</code> to the beginning of your <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code>:</p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +ENTRYPOINT top -b +CMD -- --ignored-param1 +</pre></div> <p>You can then run it (giving it a name for the next step):</p> <div class="highlight"><pre class="highlight" data-language="">$ docker run -it --name test top --ignored-param2 + +top - 13:58:24 up 17 min, 0 users, load average: 0.00, 0.00, 0.00 +Tasks: 2 total, 1 running, 1 sleeping, 0 stopped, 0 zombie +%Cpu(s): 16.7 us, 33.3 sy, 0.0 ni, 50.0 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st +MiB Mem : 1990.8 total, 1354.6 free, 231.4 used, 404.7 buff/cache +MiB Swap: 1024.0 total, 1024.0 free, 0.0 used. 1639.8 avail Mem + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 2612 604 536 S 0.0 0.0 0:00.02 sh + 6 root 20 0 5956 3188 2768 R 0.0 0.2 0:00.00 top +</pre></div> <p>You can see from the output of <code class="language-plaintext highlighter-rouge">top</code> that the specified <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> is not <code class="language-plaintext highlighter-rouge">PID 1</code>.</p> <p>If you then run <code class="language-plaintext highlighter-rouge">docker stop test</code>, the container will not exit cleanly - the <code class="language-plaintext highlighter-rouge">stop</code> command will be forced to send a <code class="language-plaintext highlighter-rouge">SIGKILL</code> after the timeout:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker exec -it test ps waux + +USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND +root 1 0.4 0.0 2612 604 pts/0 Ss+ 13:58 0:00 /bin/sh -c top -b --ignored-param2 +root 6 0.0 0.1 5956 3188 pts/0 S+ 13:58 0:00 top -b +root 7 0.0 0.1 5884 2816 pts/1 Rs+ 13:58 0:00 ps waux + +$ /usr/bin/time docker stop test + +test +real 0m 10.19s +user 0m 0.04s +sys 0m 0.03s +</pre></div> <h3 id="understand-how-cmd-and-entrypoint-interact">Understand how CMD and ENTRYPOINT interact</h3> <p>Both <code class="language-plaintext highlighter-rouge">CMD</code> and <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> instructions define what command gets executed when running a container. There are few rules that describe their co-operation.</p> <ol> <li> <p>Dockerfile should specify at least one of <code class="language-plaintext highlighter-rouge">CMD</code> or <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> commands.</p> </li> <li> <p><code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> should be defined when using the container as an executable.</p> </li> <li> <p><code class="language-plaintext highlighter-rouge">CMD</code> should be used as a way of defining default arguments for an <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> command or for executing an ad-hoc command in a container.</p> </li> <li> <p><code class="language-plaintext highlighter-rouge">CMD</code> will be overridden when running the container with alternative arguments.</p> </li> </ol> <p>The table below shows what command is executed for different <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> / <code class="language-plaintext highlighter-rouge">CMD</code> combinations:</p> <table> <thead> <tr> <th style="text-align: left"> </th> <th style="text-align: left">No ENTRYPOINT</th> <th style="text-align: left">ENTRYPOINT exec_entry p1_entry</th> <th style="text-align: left">ENTRYPOINT [“exec_entry”, “p1_entry”]</th> </tr> </thead> <tbody> <tr> <td style="text-align: left"><strong>No CMD</strong></td> <td style="text-align: left"><em>error, not allowed</em></td> <td style="text-align: left">/bin/sh -c exec_entry p1_entry</td> <td style="text-align: left">exec_entry p1_entry</td> </tr> <tr> <td style="text-align: left"><strong>CMD [“exec_cmd”, “p1_cmd”]</strong></td> <td style="text-align: left">exec_cmd p1_cmd</td> <td style="text-align: left">/bin/sh -c exec_entry p1_entry</td> <td style="text-align: left">exec_entry p1_entry exec_cmd p1_cmd</td> </tr> <tr> <td style="text-align: left"><strong>CMD [“p1_cmd”, “p2_cmd”]</strong></td> <td style="text-align: left">p1_cmd p2_cmd</td> <td style="text-align: left">/bin/sh -c exec_entry p1_entry</td> <td style="text-align: left">exec_entry p1_entry p1_cmd p2_cmd</td> </tr> <tr> <td style="text-align: left"><strong>CMD exec_cmd p1_cmd</strong></td> <td style="text-align: left">/bin/sh -c exec_cmd p1_cmd</td> <td style="text-align: left">/bin/sh -c exec_entry p1_entry</td> <td style="text-align: left">exec_entry p1_entry /bin/sh -c exec_cmd p1_cmd</td> </tr> </tbody> </table> <blockquote> <p><strong>Note</strong></p> <p>If <code class="language-plaintext highlighter-rouge">CMD</code> is defined from the base image, setting <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> will reset <code class="language-plaintext highlighter-rouge">CMD</code> to an empty value. In this scenario, <code class="language-plaintext highlighter-rouge">CMD</code> must be defined in the current image to have a value.</p> </blockquote> <h2 id="volume">VOLUME</h2> <div class="highlight"><pre class="highlight" data-language="">VOLUME ["/data"] +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">VOLUME</code> instruction creates a mount point with the specified name and marks it as holding externally mounted volumes from native host or other containers. The value can be a JSON array, <code class="language-plaintext highlighter-rouge">VOLUME ["/var/log/"]</code>, or a plain string with multiple arguments, such as <code class="language-plaintext highlighter-rouge">VOLUME /var/log</code> or <code class="language-plaintext highlighter-rouge">VOLUME /var/log /var/db</code>. For more information/examples and mounting instructions via the Docker client, refer to <a href="https://docs.docker.com/storage/volumes/"><em>Share Directories via Volumes</em></a> documentation.</p> <p>The <code class="language-plaintext highlighter-rouge">docker run</code> command initializes the newly created volume with any data that exists at the specified location within the base image. For example, consider the following Dockerfile snippet:</p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +RUN mkdir /myvol +RUN echo "hello world" > /myvol/greeting +VOLUME /myvol +</pre></div> <p>This Dockerfile results in an image that causes <code class="language-plaintext highlighter-rouge">docker run</code> to create a new mount point at <code class="language-plaintext highlighter-rouge">/myvol</code> and copy the <code class="language-plaintext highlighter-rouge">greeting</code> file into the newly created volume.</p> <h3 id="notes-about-specifying-volumes">Notes about specifying volumes</h3> <p>Keep the following things in mind about volumes in the <code class="language-plaintext highlighter-rouge">Dockerfile</code>.</p> <ul> <li> <p><strong>Volumes on Windows-based containers</strong>: When using Windows-based containers, the destination of a volume inside the container must be one of:</p> <ul> <li>a non-existing or empty directory</li> <li>a drive other than <code class="language-plaintext highlighter-rouge">C:</code> +</li> </ul> </li> <li> <p><strong>Changing the volume from within the Dockerfile</strong>: If any build steps change the data within the volume after it has been declared, those changes will be discarded.</p> </li> <li> <p><strong>JSON formatting</strong>: The list is parsed as a JSON array. You must enclose words with double quotes (<code class="language-plaintext highlighter-rouge">"</code>) rather than single quotes (<code class="language-plaintext highlighter-rouge">'</code>).</p> </li> <li> <p><strong>The host directory is declared at container run-time</strong>: The host directory (the mountpoint) is, by its nature, host-dependent. This is to preserve image portability, since a given host directory can’t be guaranteed to be available on all hosts. For this reason, you can’t mount a host directory from within the Dockerfile. The <code class="language-plaintext highlighter-rouge">VOLUME</code> instruction does not support specifying a <code class="language-plaintext highlighter-rouge">host-dir</code> parameter. You must specify the mountpoint when you create or run the container.</p> </li> </ul> <h2 id="user">USER</h2> <div class="highlight"><pre class="highlight" data-language="">USER <user>[:<group>] +</pre></div> <p>or</p> <div class="highlight"><pre class="highlight" data-language="">USER <UID>[:<GID>] +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">USER</code> instruction sets the user name (or UID) and optionally the user group (or GID) to use when running the image and for any <code class="language-plaintext highlighter-rouge">RUN</code>, <code class="language-plaintext highlighter-rouge">CMD</code> and <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> instructions that follow it in the <code class="language-plaintext highlighter-rouge">Dockerfile</code>.</p> <blockquote> <p>Note that when specifying a group for the user, the user will have <em>only</em> the specified group membership. Any other configured group memberships will be ignored.</p> </blockquote> <blockquote> <p><strong>Warning</strong></p> <p>When the user doesn’t have a primary group then the image (or the next instructions) will be run with the <code class="language-plaintext highlighter-rouge">root</code> group.</p> <p>On Windows, the user must be created first if it’s not a built-in account. This can be done with the <code class="language-plaintext highlighter-rouge">net user</code> command called as part of a Dockerfile.</p> </blockquote> <div class="highlight"><pre class="highlight" data-language="">FROM microsoft/windowsservercore +# Create Windows user in the container +RUN net user /add patrick +# Set it for subsequent commands +USER patrick +</pre></div> <h2 id="workdir">WORKDIR</h2> <div class="highlight"><pre class="highlight" data-language="">WORKDIR /path/to/workdir +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">WORKDIR</code> instruction sets the working directory for any <code class="language-plaintext highlighter-rouge">RUN</code>, <code class="language-plaintext highlighter-rouge">CMD</code>, <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code>, <code class="language-plaintext highlighter-rouge">COPY</code> and <code class="language-plaintext highlighter-rouge">ADD</code> instructions that follow it in the <code class="language-plaintext highlighter-rouge">Dockerfile</code>. If the <code class="language-plaintext highlighter-rouge">WORKDIR</code> doesn’t exist, it will be created even if it’s not used in any subsequent <code class="language-plaintext highlighter-rouge">Dockerfile</code> instruction.</p> <p>The <code class="language-plaintext highlighter-rouge">WORKDIR</code> instruction can be used multiple times in a <code class="language-plaintext highlighter-rouge">Dockerfile</code>. If a relative path is provided, it will be relative to the path of the previous <code class="language-plaintext highlighter-rouge">WORKDIR</code> instruction. For example:</p> <div class="highlight"><pre class="highlight" data-language="">WORKDIR /a +WORKDIR b +WORKDIR c +RUN pwd +</pre></div> <p>The output of the final <code class="language-plaintext highlighter-rouge">pwd</code> command in this <code class="language-plaintext highlighter-rouge">Dockerfile</code> would be <code class="language-plaintext highlighter-rouge">/a/b/c</code>.</p> <p>The <code class="language-plaintext highlighter-rouge">WORKDIR</code> instruction can resolve environment variables previously set using <code class="language-plaintext highlighter-rouge">ENV</code>. You can only use environment variables explicitly set in the <code class="language-plaintext highlighter-rouge">Dockerfile</code>. For example:</p> <div class="highlight"><pre class="highlight" data-language="">ENV DIRPATH=/path +WORKDIR $DIRPATH/$DIRNAME +RUN pwd +</pre></div> <p>The output of the final <code class="language-plaintext highlighter-rouge">pwd</code> command in this <code class="language-plaintext highlighter-rouge">Dockerfile</code> would be <code class="language-plaintext highlighter-rouge">/path/$DIRNAME</code></p> <p>If not specified, the default working directory is <code class="language-plaintext highlighter-rouge">/</code>. In practice, if you aren’t building a Dockerfile from scratch (<code class="language-plaintext highlighter-rouge">FROM scratch</code>), the <code class="language-plaintext highlighter-rouge">WORKDIR</code> may likely be set by the base image you’re using.</p> <p>Therefore, to avoid unintended operations in unknown directories, it is best practice to set your <code class="language-plaintext highlighter-rouge">WORKDIR</code> explicitly.</p> <h2 id="arg">ARG</h2> <div class="highlight"><pre class="highlight" data-language="">ARG <name>[=<default value>] +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">ARG</code> instruction defines a variable that users can pass at build-time to the builder with the <code class="language-plaintext highlighter-rouge">docker build</code> command using the <code class="language-plaintext highlighter-rouge">--build-arg <varname>=<value></code> flag. If a user specifies a build argument that was not defined in the Dockerfile, the build outputs a warning.</p> <div class="highlight"><pre class="highlight" data-language="">[Warning] One or more build-args [foo] were not consumed. +</pre></div> <p>A Dockerfile may include one or more <code class="language-plaintext highlighter-rouge">ARG</code> instructions. For example, the following is a valid Dockerfile:</p> <div class="highlight"><pre class="highlight" data-language="">FROM busybox +ARG user1 +ARG buildno +# ... +</pre></div> <blockquote class="warning"> <p><strong>Warning:</strong></p> <p>It is not recommended to use build-time variables for passing secrets like github keys, user credentials etc. Build-time variable values are visible to any user of the image with the <code class="language-plaintext highlighter-rouge">docker history</code> command.</p> <p>Refer to the <a href="https://docs.docker.com/develop/develop-images/build_enhancements/#new-docker-build-secret-information">“build images with BuildKit”</a> section to learn about secure ways to use secrets when building images.</p> </blockquote> <h3 id="default-values">Default values</h3> <p>An <code class="language-plaintext highlighter-rouge">ARG</code> instruction can optionally include a default value:</p> <div class="highlight"><pre class="highlight" data-language="">FROM busybox +ARG user1=someuser +ARG buildno=1 +# ... +</pre></div> <p>If an <code class="language-plaintext highlighter-rouge">ARG</code> instruction has a default value and if there is no value passed at build-time, the builder uses the default.</p> <h3 id="scope">Scope</h3> <p>An <code class="language-plaintext highlighter-rouge">ARG</code> variable definition comes into effect from the line on which it is defined in the <code class="language-plaintext highlighter-rouge">Dockerfile</code> not from the argument’s use on the command-line or elsewhere. For example, consider this Dockerfile:</p> <div class="highlight"><pre class="highlight" data-language="">FROM busybox +USER ${user:-some_user} +ARG user +USER $user +# ... +</pre></div> <p>A user builds this file by calling:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build --build-arg user=what_user . +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">USER</code> at line 2 evaluates to <code class="language-plaintext highlighter-rouge">some_user</code> as the <code class="language-plaintext highlighter-rouge">user</code> variable is defined on the subsequent line 3. The <code class="language-plaintext highlighter-rouge">USER</code> at line 4 evaluates to <code class="language-plaintext highlighter-rouge">what_user</code> as <code class="language-plaintext highlighter-rouge">user</code> is defined and the <code class="language-plaintext highlighter-rouge">what_user</code> value was passed on the command line. Prior to its definition by an <code class="language-plaintext highlighter-rouge">ARG</code> instruction, any use of a variable results in an empty string.</p> <p>An <code class="language-plaintext highlighter-rouge">ARG</code> instruction goes out of scope at the end of the build stage where it was defined. To use an arg in multiple stages, each stage must include the <code class="language-plaintext highlighter-rouge">ARG</code> instruction.</p> <div class="highlight"><pre class="highlight" data-language="">FROM busybox +ARG SETTINGS +RUN ./run/setup $SETTINGS + +FROM busybox +ARG SETTINGS +RUN ./run/other $SETTINGS +</pre></div> <h3 id="using-arg-variables">Using ARG variables</h3> <p>You can use an <code class="language-plaintext highlighter-rouge">ARG</code> or an <code class="language-plaintext highlighter-rouge">ENV</code> instruction to specify variables that are available to the <code class="language-plaintext highlighter-rouge">RUN</code> instruction. Environment variables defined using the <code class="language-plaintext highlighter-rouge">ENV</code> instruction always override an <code class="language-plaintext highlighter-rouge">ARG</code> instruction of the same name. Consider this Dockerfile with an <code class="language-plaintext highlighter-rouge">ENV</code> and <code class="language-plaintext highlighter-rouge">ARG</code> instruction.</p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +ARG CONT_IMG_VER +ENV CONT_IMG_VER=v1.0.0 +RUN echo $CONT_IMG_VER +</pre></div> <p>Then, assume this image is built with this command:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build --build-arg CONT_IMG_VER=v2.0.1 . +</pre></div> <p>In this case, the <code class="language-plaintext highlighter-rouge">RUN</code> instruction uses <code class="language-plaintext highlighter-rouge">v1.0.0</code> instead of the <code class="language-plaintext highlighter-rouge">ARG</code> setting passed by the user:<code class="language-plaintext highlighter-rouge">v2.0.1</code> This behavior is similar to a shell script where a locally scoped variable overrides the variables passed as arguments or inherited from environment, from its point of definition.</p> <p>Using the example above but a different <code class="language-plaintext highlighter-rouge">ENV</code> specification you can create more useful interactions between <code class="language-plaintext highlighter-rouge">ARG</code> and <code class="language-plaintext highlighter-rouge">ENV</code> instructions:</p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +ARG CONT_IMG_VER +ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0} +RUN echo $CONT_IMG_VER +</pre></div> <p>Unlike an <code class="language-plaintext highlighter-rouge">ARG</code> instruction, <code class="language-plaintext highlighter-rouge">ENV</code> values are always persisted in the built image. Consider a docker build without the <code class="language-plaintext highlighter-rouge">--build-arg</code> flag:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build . +</pre></div> <p>Using this Dockerfile example, <code class="language-plaintext highlighter-rouge">CONT_IMG_VER</code> is still persisted in the image but its value would be <code class="language-plaintext highlighter-rouge">v1.0.0</code> as it is the default set in line 3 by the <code class="language-plaintext highlighter-rouge">ENV</code> instruction.</p> <p>The variable expansion technique in this example allows you to pass arguments from the command line and persist them in the final image by leveraging the <code class="language-plaintext highlighter-rouge">ENV</code> instruction. Variable expansion is only supported for <a href="#environment-replacement">a limited set of Dockerfile instructions.</a></p> <h3 id="predefined-args">Predefined ARGs</h3> <p>Docker has a set of predefined <code class="language-plaintext highlighter-rouge">ARG</code> variables that you can use without a corresponding <code class="language-plaintext highlighter-rouge">ARG</code> instruction in the Dockerfile.</p> <ul> <li><code class="language-plaintext highlighter-rouge">HTTP_PROXY</code></li> <li><code class="language-plaintext highlighter-rouge">http_proxy</code></li> <li><code class="language-plaintext highlighter-rouge">HTTPS_PROXY</code></li> <li><code class="language-plaintext highlighter-rouge">https_proxy</code></li> <li><code class="language-plaintext highlighter-rouge">FTP_PROXY</code></li> <li><code class="language-plaintext highlighter-rouge">ftp_proxy</code></li> <li><code class="language-plaintext highlighter-rouge">NO_PROXY</code></li> <li><code class="language-plaintext highlighter-rouge">no_proxy</code></li> </ul> <p>To use these, pass them on the command line using the <code class="language-plaintext highlighter-rouge">--build-arg</code> flag, for example:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build --build-arg HTTPS_PROXY=https://my-proxy.example.com . +</pre></div> <p>By default, these pre-defined variables are excluded from the output of <code class="language-plaintext highlighter-rouge">docker history</code>. Excluding them reduces the risk of accidentally leaking sensitive authentication information in an <code class="language-plaintext highlighter-rouge">HTTP_PROXY</code> variable.</p> <p>For example, consider building the following Dockerfile using <code class="language-plaintext highlighter-rouge">--build-arg HTTP_PROXY=http://user:pass@proxy.lon.example.com</code></p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +RUN echo "Hello World" +</pre></div> <p>In this case, the value of the <code class="language-plaintext highlighter-rouge">HTTP_PROXY</code> variable is not available in the <code class="language-plaintext highlighter-rouge">docker history</code> and is not cached. If you were to change location, and your proxy server changed to <code class="language-plaintext highlighter-rouge">http://user:pass@proxy.sfo.example.com</code>, a subsequent build does not result in a cache miss.</p> <p>If you need to override this behaviour then you may do so by adding an <code class="language-plaintext highlighter-rouge">ARG</code> statement in the Dockerfile as follows:</p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +ARG HTTP_PROXY +RUN echo "Hello World" +</pre></div> <p>When building this Dockerfile, the <code class="language-plaintext highlighter-rouge">HTTP_PROXY</code> is preserved in the <code class="language-plaintext highlighter-rouge">docker history</code>, and changing its value invalidates the build cache.</p> <h3 id="automatic-platform-args-in-the-global-scope">Automatic platform ARGs in the global scope</h3> <p>This feature is only available when using the <a href="#buildkit">BuildKit</a> backend.</p> <p>Docker predefines a set of <code class="language-plaintext highlighter-rouge">ARG</code> variables with information on the platform of the node performing the build (build platform) and on the platform of the resulting image (target platform). The target platform can be specified with the <code class="language-plaintext highlighter-rouge">--platform</code> flag on <code class="language-plaintext highlighter-rouge">docker build</code>.</p> <p>The following <code class="language-plaintext highlighter-rouge">ARG</code> variables are set automatically:</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">TARGETPLATFORM</code> - platform of the build result. Eg <code class="language-plaintext highlighter-rouge">linux/amd64</code>, <code class="language-plaintext highlighter-rouge">linux/arm/v7</code>, <code class="language-plaintext highlighter-rouge">windows/amd64</code>.</li> <li> +<code class="language-plaintext highlighter-rouge">TARGETOS</code> - OS component of TARGETPLATFORM</li> <li> +<code class="language-plaintext highlighter-rouge">TARGETARCH</code> - architecture component of TARGETPLATFORM</li> <li> +<code class="language-plaintext highlighter-rouge">TARGETVARIANT</code> - variant component of TARGETPLATFORM</li> <li> +<code class="language-plaintext highlighter-rouge">BUILDPLATFORM</code> - platform of the node performing the build.</li> <li> +<code class="language-plaintext highlighter-rouge">BUILDOS</code> - OS component of BUILDPLATFORM</li> <li> +<code class="language-plaintext highlighter-rouge">BUILDARCH</code> - architecture component of BUILDPLATFORM</li> <li> +<code class="language-plaintext highlighter-rouge">BUILDVARIANT</code> - variant component of BUILDPLATFORM</li> </ul> <p>These arguments are defined in the global scope so are not automatically available inside build stages or for your <code class="language-plaintext highlighter-rouge">RUN</code> commands. To expose one of these arguments inside the build stage redefine it without value.</p> <p>For example:</p> <div class="highlight"><pre class="highlight" data-language="">FROM alpine +ARG TARGETPLATFORM +RUN echo "I'm building for $TARGETPLATFORM" +</pre></div> <h3 id="impact-on-build-caching">Impact on build caching</h3> <p><code class="language-plaintext highlighter-rouge">ARG</code> variables are not persisted into the built image as <code class="language-plaintext highlighter-rouge">ENV</code> variables are. However, <code class="language-plaintext highlighter-rouge">ARG</code> variables do impact the build cache in similar ways. If a Dockerfile defines an <code class="language-plaintext highlighter-rouge">ARG</code> variable whose value is different from a previous build, then a “cache miss” occurs upon its first usage, not its definition. In particular, all <code class="language-plaintext highlighter-rouge">RUN</code> instructions following an <code class="language-plaintext highlighter-rouge">ARG</code> instruction use the <code class="language-plaintext highlighter-rouge">ARG</code> variable implicitly (as an environment variable), thus can cause a cache miss. All predefined <code class="language-plaintext highlighter-rouge">ARG</code> variables are exempt from caching unless there is a matching <code class="language-plaintext highlighter-rouge">ARG</code> statement in the <code class="language-plaintext highlighter-rouge">Dockerfile</code>.</p> <p>For example, consider these two Dockerfile:</p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +ARG CONT_IMG_VER +RUN echo $CONT_IMG_VER +</pre></div> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +ARG CONT_IMG_VER +RUN echo hello +</pre></div> <p>If you specify <code class="language-plaintext highlighter-rouge">--build-arg CONT_IMG_VER=<value></code> on the command line, in both cases, the specification on line 2 does not cause a cache miss; line 3 does cause a cache miss.<code class="language-plaintext highlighter-rouge">ARG CONT_IMG_VER</code> causes the RUN line to be identified as the same as running <code class="language-plaintext highlighter-rouge">CONT_IMG_VER=<value> echo hello</code>, so if the <code class="language-plaintext highlighter-rouge"><value></code> changes, we get a cache miss.</p> <p>Consider another example under the same command line:</p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +ARG CONT_IMG_VER +ENV CONT_IMG_VER=$CONT_IMG_VER +RUN echo $CONT_IMG_VER +</pre></div> <p>In this example, the cache miss occurs on line 3. The miss happens because the variable’s value in the <code class="language-plaintext highlighter-rouge">ENV</code> references the <code class="language-plaintext highlighter-rouge">ARG</code> variable and that variable is changed through the command line. In this example, the <code class="language-plaintext highlighter-rouge">ENV</code> command causes the image to include the value.</p> <p>If an <code class="language-plaintext highlighter-rouge">ENV</code> instruction overrides an <code class="language-plaintext highlighter-rouge">ARG</code> instruction of the same name, like this Dockerfile:</p> <div class="highlight"><pre class="highlight" data-language="">FROM ubuntu +ARG CONT_IMG_VER +ENV CONT_IMG_VER=hello +RUN echo $CONT_IMG_VER +</pre></div> <p>Line 3 does not cause a cache miss because the value of <code class="language-plaintext highlighter-rouge">CONT_IMG_VER</code> is a constant (<code class="language-plaintext highlighter-rouge">hello</code>). As a result, the environment variables and values used on the <code class="language-plaintext highlighter-rouge">RUN</code> (line 4) doesn’t change between builds.</p> <h2 id="onbuild">ONBUILD</h2> <div class="highlight"><pre class="highlight" data-language="">ONBUILD <INSTRUCTION> +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">ONBUILD</code> instruction adds to the image a <em>trigger</em> instruction to be executed at a later time, when the image is used as the base for another build. The trigger will be executed in the context of the downstream build, as if it had been inserted immediately after the <code class="language-plaintext highlighter-rouge">FROM</code> instruction in the downstream <code class="language-plaintext highlighter-rouge">Dockerfile</code>.</p> <p>Any build instruction can be registered as a trigger.</p> <p>This is useful if you are building an image which will be used as a base to build other images, for example an application build environment or a daemon which may be customized with user-specific configuration.</p> <p>For example, if your image is a reusable Python application builder, it will require application source code to be added in a particular directory, and it might require a build script to be called <em>after</em> that. You can’t just call <code class="language-plaintext highlighter-rouge">ADD</code> and <code class="language-plaintext highlighter-rouge">RUN</code> now, because you don’t yet have access to the application source code, and it will be different for each application build. You could simply provide application developers with a boilerplate <code class="language-plaintext highlighter-rouge">Dockerfile</code> to copy-paste into their application, but that is inefficient, error-prone and difficult to update because it mixes with application-specific code.</p> <p>The solution is to use <code class="language-plaintext highlighter-rouge">ONBUILD</code> to register advance instructions to run later, during the next build stage.</p> <p>Here’s how it works:</p> <ol> <li>When it encounters an <code class="language-plaintext highlighter-rouge">ONBUILD</code> instruction, the builder adds a trigger to the metadata of the image being built. The instruction does not otherwise affect the current build.</li> <li>At the end of the build, a list of all triggers is stored in the image manifest, under the key <code class="language-plaintext highlighter-rouge">OnBuild</code>. They can be inspected with the <code class="language-plaintext highlighter-rouge">docker inspect</code> command.</li> <li>Later the image may be used as a base for a new build, using the <code class="language-plaintext highlighter-rouge">FROM</code> instruction. As part of processing the <code class="language-plaintext highlighter-rouge">FROM</code> instruction, the downstream builder looks for <code class="language-plaintext highlighter-rouge">ONBUILD</code> triggers, and executes them in the same order they were registered. If any of the triggers fail, the <code class="language-plaintext highlighter-rouge">FROM</code> instruction is aborted which in turn causes the build to fail. If all triggers succeed, the <code class="language-plaintext highlighter-rouge">FROM</code> instruction completes and the build continues as usual.</li> <li>Triggers are cleared from the final image after being executed. In other words they are not inherited by “grand-children” builds.</li> </ol> <p>For example you might add something like this:</p> <div class="highlight"><pre class="highlight" data-language="">ONBUILD ADD . /app/src +ONBUILD RUN /usr/local/bin/python-build --dir /app/src +</pre></div> <blockquote> <p><strong>Warning</strong></p> <p>Chaining <code class="language-plaintext highlighter-rouge">ONBUILD</code> instructions using <code class="language-plaintext highlighter-rouge">ONBUILD ONBUILD</code> isn’t allowed.</p> </blockquote> <blockquote> <p><strong>Warning</strong></p> <p>The <code class="language-plaintext highlighter-rouge">ONBUILD</code> instruction may not trigger <code class="language-plaintext highlighter-rouge">FROM</code> or <code class="language-plaintext highlighter-rouge">MAINTAINER</code> instructions.</p> </blockquote> <h2 id="stopsignal">STOPSIGNAL</h2> <div class="highlight"><pre class="highlight" data-language="">STOPSIGNAL signal +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">STOPSIGNAL</code> instruction sets the system call signal that will be sent to the container to exit. This signal can be a signal name in the format <code class="language-plaintext highlighter-rouge">SIG<NAME></code>, for instance <code class="language-plaintext highlighter-rouge">SIGKILL</code>, or an unsigned number that matches a position in the kernel’s syscall table, for instance <code class="language-plaintext highlighter-rouge">9</code>. The default is <code class="language-plaintext highlighter-rouge">SIGTERM</code> if not defined.</p> <p>The image’s default stopsignal can be overridden per container, using the <code class="language-plaintext highlighter-rouge">--stop-signal</code> flag on <code class="language-plaintext highlighter-rouge">docker run</code> and <code class="language-plaintext highlighter-rouge">docker create</code>.</p> <h2 id="healthcheck">HEALTHCHECK</h2> <p>The <code class="language-plaintext highlighter-rouge">HEALTHCHECK</code> instruction has two forms:</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">HEALTHCHECK [OPTIONS] CMD command</code> (check container health by running a command inside the container)</li> <li> +<code class="language-plaintext highlighter-rouge">HEALTHCHECK NONE</code> (disable any healthcheck inherited from the base image)</li> </ul> <p>The <code class="language-plaintext highlighter-rouge">HEALTHCHECK</code> instruction tells Docker how to test a container to check that it is still working. This can detect cases such as a web server that is stuck in an infinite loop and unable to handle new connections, even though the server process is still running.</p> <p>When a container has a healthcheck specified, it has a <em>health status</em> in addition to its normal status. This status is initially <code class="language-plaintext highlighter-rouge">starting</code>. Whenever a health check passes, it becomes <code class="language-plaintext highlighter-rouge">healthy</code> (whatever state it was previously in). After a certain number of consecutive failures, it becomes <code class="language-plaintext highlighter-rouge">unhealthy</code>.</p> <p>The options that can appear before <code class="language-plaintext highlighter-rouge">CMD</code> are:</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">--interval=DURATION</code> (default: <code class="language-plaintext highlighter-rouge">30s</code>)</li> <li> +<code class="language-plaintext highlighter-rouge">--timeout=DURATION</code> (default: <code class="language-plaintext highlighter-rouge">30s</code>)</li> <li> +<code class="language-plaintext highlighter-rouge">--start-period=DURATION</code> (default: <code class="language-plaintext highlighter-rouge">0s</code>)</li> <li> +<code class="language-plaintext highlighter-rouge">--retries=N</code> (default: <code class="language-plaintext highlighter-rouge">3</code>)</li> </ul> <p>The health check will first run <strong>interval</strong> seconds after the container is started, and then again <strong>interval</strong> seconds after each previous check completes.</p> <p>If a single run of the check takes longer than <strong>timeout</strong> seconds then the check is considered to have failed.</p> <p>It takes <strong>retries</strong> consecutive failures of the health check for the container to be considered <code class="language-plaintext highlighter-rouge">unhealthy</code>.</p> <p><strong>start period</strong> provides initialization time for containers that need time to bootstrap. Probe failure during that period will not be counted towards the maximum number of retries. However, if a health check succeeds during the start period, the container is considered started and all consecutive failures will be counted towards the maximum number of retries.</p> <p>There can only be one <code class="language-plaintext highlighter-rouge">HEALTHCHECK</code> instruction in a Dockerfile. If you list more than one then only the last <code class="language-plaintext highlighter-rouge">HEALTHCHECK</code> will take effect.</p> <p>The command after the <code class="language-plaintext highlighter-rouge">CMD</code> keyword can be either a shell command (e.g. <code class="language-plaintext highlighter-rouge">HEALTHCHECK CMD /bin/check-running</code>) or an <em>exec</em> array (as with other Dockerfile commands; see e.g. <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code> for details).</p> <p>The command’s exit status indicates the health status of the container. The possible values are:</p> <ul> <li>0: success - the container is healthy and ready for use</li> <li>1: unhealthy - the container is not working correctly</li> <li>2: reserved - do not use this exit code</li> </ul> <p>For example, to check every five minutes or so that a web-server is able to serve the site’s main page within three seconds:</p> <div class="highlight"><pre class="highlight" data-language="">HEALTHCHECK --interval=5m --timeout=3s \ + CMD curl -f http://localhost/ || exit 1 +</pre></div> <p>To help debug failing probes, any output text (UTF-8 encoded) that the command writes on stdout or stderr will be stored in the health status and can be queried with <code class="language-plaintext highlighter-rouge">docker inspect</code>. Such output should be kept short (only the first 4096 bytes are stored currently).</p> <p>When the health status of a container changes, a <code class="language-plaintext highlighter-rouge">health_status</code> event is generated with the new status.</p> <h2 id="shell">SHELL</h2> <div class="highlight"><pre class="highlight" data-language="">SHELL ["executable", "parameters"] +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">SHELL</code> instruction allows the default shell used for the <em>shell</em> form of commands to be overridden. The default shell on Linux is <code class="language-plaintext highlighter-rouge">["/bin/sh", "-c"]</code>, and on Windows is <code class="language-plaintext highlighter-rouge">["cmd", "/S", "/C"]</code>. The <code class="language-plaintext highlighter-rouge">SHELL</code> instruction <em>must</em> be written in JSON form in a Dockerfile.</p> <p>The <code class="language-plaintext highlighter-rouge">SHELL</code> instruction is particularly useful on Windows where there are two commonly used and quite different native shells: <code class="language-plaintext highlighter-rouge">cmd</code> and <code class="language-plaintext highlighter-rouge">powershell</code>, as well as alternate shells available including <code class="language-plaintext highlighter-rouge">sh</code>.</p> <p>The <code class="language-plaintext highlighter-rouge">SHELL</code> instruction can appear multiple times. Each <code class="language-plaintext highlighter-rouge">SHELL</code> instruction overrides all previous <code class="language-plaintext highlighter-rouge">SHELL</code> instructions, and affects all subsequent instructions. For example:</p> <div class="highlight"><pre class="highlight" data-language="">FROM microsoft/windowsservercore + +# Executed as cmd /S /C echo default +RUN echo default + +# Executed as cmd /S /C powershell -command Write-Host default +RUN powershell -command Write-Host default + +# Executed as powershell -command Write-Host hello +SHELL ["powershell", "-command"] +RUN Write-Host hello + +# Executed as cmd /S /C echo hello +SHELL ["cmd", "/S", "/C"] +RUN echo hello +</pre></div> <p>The following instructions can be affected by the <code class="language-plaintext highlighter-rouge">SHELL</code> instruction when the <em>shell</em> form of them is used in a Dockerfile: <code class="language-plaintext highlighter-rouge">RUN</code>, <code class="language-plaintext highlighter-rouge">CMD</code> and <code class="language-plaintext highlighter-rouge">ENTRYPOINT</code>.</p> <p>The following example is a common pattern found on Windows which can be streamlined by using the <code class="language-plaintext highlighter-rouge">SHELL</code> instruction:</p> <div class="highlight"><pre class="highlight" data-language="">RUN powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" +</pre></div> <p>The command invoked by docker will be:</p> <div class="highlight"><pre class="highlight" data-language="">cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" +</pre></div> <p>This is inefficient for two reasons. First, there is an un-necessary cmd.exe command processor (aka shell) being invoked. Second, each <code class="language-plaintext highlighter-rouge">RUN</code> instruction in the <em>shell</em> form requires an extra <code class="language-plaintext highlighter-rouge">powershell -command</code> prefixing the command.</p> <p>To make this more efficient, one of two mechanisms can be employed. One is to use the JSON form of the RUN command such as:</p> <div class="highlight"><pre class="highlight" data-language="">RUN ["powershell", "-command", "Execute-MyCmdlet", "-param1 \"c:\\foo.txt\""] +</pre></div> <p>While the JSON form is unambiguous and does not use the un-necessary cmd.exe, it does require more verbosity through double-quoting and escaping. The alternate mechanism is to use the <code class="language-plaintext highlighter-rouge">SHELL</code> instruction and the <em>shell</em> form, making a more natural syntax for Windows users, especially when combined with the <code class="language-plaintext highlighter-rouge">escape</code> parser directive:</p> <div class="highlight"><pre class="highlight" data-language=""># escape=` + +FROM microsoft/nanoserver +SHELL ["powershell","-command"] +RUN New-Item -ItemType Directory C:\Example +ADD Execute-MyCmdlet.ps1 c:\example\ +RUN c:\example\Execute-MyCmdlet -sample 'hello world' +</pre></div> <p>Resulting in:</p> <div class="highlight"><pre class="highlight" data-language="">PS E:\myproject> docker build -t shell . + +Sending build context to Docker daemon 4.096 kB +Step 1/5 : FROM microsoft/nanoserver + ---> 22738ff49c6d +Step 2/5 : SHELL powershell -command + ---> Running in 6fcdb6855ae2 + ---> 6331462d4300 +Removing intermediate container 6fcdb6855ae2 +Step 3/5 : RUN New-Item -ItemType Directory C:\Example + ---> Running in d0eef8386e97 + + + Directory: C:\ + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +d----- 10/28/2016 11:26 AM Example + + + ---> 3f2fbf1395d9 +Removing intermediate container d0eef8386e97 +Step 4/5 : ADD Execute-MyCmdlet.ps1 c:\example\ + ---> a955b2621c31 +Removing intermediate container b825593d39fc +Step 5/5 : RUN c:\example\Execute-MyCmdlet 'hello world' + ---> Running in be6d8e63fe75 +hello world + ---> 8e559e9bf424 +Removing intermediate container be6d8e63fe75 +Successfully built 8e559e9bf424 +PS E:\myproject> +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">SHELL</code> instruction could also be used to modify the way in which a shell operates. For example, using <code class="language-plaintext highlighter-rouge">SHELL cmd /S /C /V:ON|OFF</code> on Windows, delayed environment variable expansion semantics could be modified.</p> <p>The <code class="language-plaintext highlighter-rouge">SHELL</code> instruction can also be used on Linux should an alternate shell be required such as <code class="language-plaintext highlighter-rouge">zsh</code>, <code class="language-plaintext highlighter-rouge">csh</code>, <code class="language-plaintext highlighter-rouge">tcsh</code> and others.</p> <h2 id="dockerfile-examples">Dockerfile examples</h2> <p>For examples of Dockerfiles, refer to:</p> <ul> <li>The <a href="https://docs.docker.com/develop/develop-images/dockerfile_best-practices/">“build images” section</a> +</li> <li>The <a href="../../../get-started/index">“get started</a> +</li> <li>The <a href="https://docs.docker.com/language/">language-specific getting started guides</a> +</li> </ul> +<p><a href="https://docs.docker.com/search/?q=builder">builder</a>, <a href="https://docs.docker.com/search/?q=docker">docker</a>, <a href="https://docs.docker.com/search/?q=Dockerfile">Dockerfile</a>, <a href="https://docs.docker.com/search/?q=automation">automation</a>, <a href="https://docs.docker.com/search/?q=image%20creation">image creation</a></p> +<div class="_attribution"> + <p class="_attribution-p"> + © 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br> + <a href="https://docs.docker.com/engine/reference/builder/" class="_attribution-link">https://docs.docker.com/engine/reference/builder/</a> + </p> +</div> |