diff options
| author | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
| commit | 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 (patch) | |
| tree | f1190704f78f04a2b0b4c977d20fe96a828377f1 /devdocs/docker/engine%2Freference%2Fcommandline%2Fbuild%2Findex.html | |
new repository
Diffstat (limited to 'devdocs/docker/engine%2Freference%2Fcommandline%2Fbuild%2Findex.html')
| -rw-r--r-- | devdocs/docker/engine%2Freference%2Fcommandline%2Fbuild%2Findex.html | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/devdocs/docker/engine%2Freference%2Fcommandline%2Fbuild%2Findex.html b/devdocs/docker/engine%2Freference%2Fcommandline%2Fbuild%2Findex.html new file mode 100644 index 00000000..ad2eb257 --- /dev/null +++ b/devdocs/docker/engine%2Freference%2Fcommandline%2Fbuild%2Findex.html @@ -0,0 +1,180 @@ +<h1>docker build</h1> <p><br></p> <p>Build an image from a Dockerfile</p> <h2 id="usage">Usage</h2> <div class="highlight"><pre class="highlight" data-language="">$ docker build [OPTIONS] PATH | URL | - +</pre></div> <p>Refer to the <a href="#options">options section</a> for an overview of available <a href="#options"><code class="language-plaintext highlighter-rouge">OPTIONS</code></a> for this command.</p> <h2 id="description">Description</h2> <p name="extended-description">The <code class="language-plaintext highlighter-rouge">docker build</code> command builds Docker images from a Dockerfile and a “context”. A build’s context is the set of files located in the specified <code class="language-plaintext highlighter-rouge">PATH</code> or <code class="language-plaintext highlighter-rouge">URL</code>. The build process can refer to any of the files in the context. For example, your build can use a <a href="../../builder/index#copy"><em>COPY</em></a> instruction to reference a file in the context.</p> <p>The <code class="language-plaintext highlighter-rouge">URL</code> parameter can refer to three kinds of resources: Git repositories, pre-packaged tarball contexts and plain text files.</p> <h3 id="git-repositories">Git repositories</h3> <p>When the <code class="language-plaintext highlighter-rouge">URL</code> parameter points to the location of a Git repository, the repository acts as the build context. The system recursively fetches the repository and its submodules. The commit history is not preserved. A repository is first pulled into a temporary directory on your local host. After that succeeds, the directory is sent to the Docker daemon as the context. Local copy gives you the ability to access private repositories using local user credentials, VPN’s, and so forth.</p> <blockquote> <p><strong>Note</strong></p> <p>If the <code class="language-plaintext highlighter-rouge">URL</code> parameter contains a fragment the system will recursively clone the repository and its submodules using a <code class="language-plaintext highlighter-rouge">git clone --recursive</code> command.</p> </blockquote> <p>Git URLs accept context configuration in their fragment section, separated by a colon (<code class="language-plaintext highlighter-rouge">:</code>). The first part represents the reference that Git will check out, and can be either a branch, a tag, or a remote reference. The second part represents a subdirectory inside the repository that will be used as a build context.</p> <p>For example, run this command to use a directory called <code class="language-plaintext highlighter-rouge">docker</code> in the branch <code class="language-plaintext highlighter-rouge">container</code>:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build https://github.com/docker/rootfs.git#container:docker +</pre></div> <p>The following table represents all the valid suffixes with their build contexts:</p> <table> <thead> <tr> <th>Build Syntax Suffix</th> <th>Commit Used</th> <th>Build Context Used</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">myrepo.git</code></td> <td><code class="language-plaintext highlighter-rouge">refs/heads/master</code></td> <td><code class="language-plaintext highlighter-rouge">/</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">myrepo.git#mytag</code></td> <td><code class="language-plaintext highlighter-rouge">refs/tags/mytag</code></td> <td><code class="language-plaintext highlighter-rouge">/</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">myrepo.git#mybranch</code></td> <td><code class="language-plaintext highlighter-rouge">refs/heads/mybranch</code></td> <td><code class="language-plaintext highlighter-rouge">/</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">myrepo.git#pull/42/head</code></td> <td><code class="language-plaintext highlighter-rouge">refs/pull/42/head</code></td> <td><code class="language-plaintext highlighter-rouge">/</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">myrepo.git#:myfolder</code></td> <td><code class="language-plaintext highlighter-rouge">refs/heads/master</code></td> <td><code class="language-plaintext highlighter-rouge">/myfolder</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">myrepo.git#master:myfolder</code></td> <td><code class="language-plaintext highlighter-rouge">refs/heads/master</code></td> <td><code class="language-plaintext highlighter-rouge">/myfolder</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">myrepo.git#mytag:myfolder</code></td> <td><code class="language-plaintext highlighter-rouge">refs/tags/mytag</code></td> <td><code class="language-plaintext highlighter-rouge">/myfolder</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">myrepo.git#mybranch:myfolder</code></td> <td><code class="language-plaintext highlighter-rouge">refs/heads/mybranch</code></td> <td><code class="language-plaintext highlighter-rouge">/myfolder</code></td> </tr> </tbody> </table> <blockquote> <p><strong>Note</strong></p> <p>You cannot specify the build-context directory (<code class="language-plaintext highlighter-rouge">myfolder</code> in the examples above) when using BuildKit as builder (<code class="language-plaintext highlighter-rouge">DOCKER_BUILDKIT=1</code>). Support for this feature is tracked in <a href="https://github.com/moby/buildkit/issues/1684">buildkit#1684</a>.</p> </blockquote> <h3 id="tarball-contexts">Tarball contexts</h3> <p>If you pass an URL to a remote tarball, the URL itself is sent to the daemon:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build http://server/context.tar.gz +</pre></div> <p>The download operation will be performed on the host the Docker daemon is running on, which is not necessarily the same host from which the build command is being issued. The Docker daemon will fetch <code class="language-plaintext highlighter-rouge">context.tar.gz</code> and use it as the build context. Tarball contexts must be tar archives conforming to the standard <code class="language-plaintext highlighter-rouge">tar</code> UNIX format and can be compressed with any one of the ‘xz’, ‘bzip2’, ‘gzip’ or ‘identity’ (no compression) formats.</p> <h3 id="text-files">Text files</h3> <p>Instead of specifying a context, you can pass a single <code class="language-plaintext highlighter-rouge">Dockerfile</code> in the <code class="language-plaintext highlighter-rouge">URL</code> or pipe the file in via <code class="language-plaintext highlighter-rouge">STDIN</code>. To pipe a <code class="language-plaintext highlighter-rouge">Dockerfile</code> from <code class="language-plaintext highlighter-rouge">STDIN</code>:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build - < Dockerfile +</pre></div> <p>With Powershell on Windows, you can run:</p> <div class="highlight"><pre class="highlight" data-language="">Get-Content Dockerfile | docker build - +</pre></div> <p>If you use <code class="language-plaintext highlighter-rouge">STDIN</code> or specify a <code class="language-plaintext highlighter-rouge">URL</code> pointing to a plain text file, the system places the contents into a file called <code class="language-plaintext highlighter-rouge">Dockerfile</code>, and any <code class="language-plaintext highlighter-rouge">-f</code>, <code class="language-plaintext highlighter-rouge">--file</code> option is ignored. In this scenario, there is no context.</p> <p>By default the <code class="language-plaintext highlighter-rouge">docker build</code> command will look for a <code class="language-plaintext highlighter-rouge">Dockerfile</code> at the root of the build context. The <code class="language-plaintext highlighter-rouge">-f</code>, <code class="language-plaintext highlighter-rouge">--file</code>, option lets you specify the path to an alternative file to use instead. This is useful in cases where the same set of files are used for multiple builds. The path must be to a file within the build context. If a relative path is specified then it is interpreted as relative to the root of the context.</p> <p>In most cases, it’s best to put each Dockerfile in an empty directory. Then, add to that directory only the files needed for building the Dockerfile. To increase the build’s performance, you can exclude files and directories by adding a <code class="language-plaintext highlighter-rouge">.dockerignore</code> file to that directory as well. For information on creating one, see the <a href="../../builder/index#dockerignore-file">.dockerignore file</a>.</p> <p>If the Docker client loses connection to the daemon, the build is canceled. This happens if you interrupt the Docker client with <code class="language-plaintext highlighter-rouge">CTRL-c</code> or if the Docker client is killed for any reason. If the build initiated a pull which is still running at the time the build is cancelled, the pull is cancelled as well.</p> <p>For example uses of this command, refer to the <a href="#examples">examples section</a> below.</p> <h2 id="options">Options</h2> <table> <thead> <tr> <td>Name, shorthand</td> <td>Default</td> <td>Description</td> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">--add-host</code></td> <td></td> <td>Add a custom host-to-IP mapping (host:ip)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--build-arg</code></td> <td></td> <td>Set build-time variables</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--cache-from</code></td> <td></td> <td>Images to consider as cache sources</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--cgroup-parent</code></td> <td></td> <td>Optional parent cgroup for the container</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--compress</code></td> <td></td> <td>Compress the build context using gzip</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--cpu-period</code></td> <td></td> <td>Limit the CPU CFS (Completely Fair Scheduler) period</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--cpu-quota</code></td> <td></td> <td>Limit the CPU CFS (Completely Fair Scheduler) quota</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--cpu-shares</code> , <code class="language-plaintext highlighter-rouge">-c</code> +</td> <td></td> <td>CPU shares (relative weight)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--cpuset-cpus</code></td> <td></td> <td>CPUs in which to allow execution (0-3, 0,1)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--cpuset-mems</code></td> <td></td> <td>MEMs in which to allow execution (0-3, 0,1)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--disable-content-trust</code></td> <td><code class="language-plaintext highlighter-rouge">true</code></td> <td>Skip image verification</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--file</code> , <code class="language-plaintext highlighter-rouge">-f</code> +</td> <td></td> <td>Name of the Dockerfile (Default is 'PATH/Dockerfile')</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--force-rm</code></td> <td></td> <td>Always remove intermediate containers</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--iidfile</code></td> <td></td> <td>Write the image ID to the file</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--isolation</code></td> <td></td> <td>Container isolation technology</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--label</code></td> <td></td> <td>Set metadata for an image</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--memory</code> , <code class="language-plaintext highlighter-rouge">-m</code> +</td> <td></td> <td>Memory limit</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--memory-swap</code></td> <td></td> <td>Swap limit equal to memory plus swap: '-1' to enable unlimited swap</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--network</code></td> <td></td> <td>Set the networking mode for the RUN instructions during build</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--no-cache</code></td> <td></td> <td>Do not use cache when building the image</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--output</code> , <code class="language-plaintext highlighter-rouge">-o</code> +</td> <td></td> <td> +<a href="https://docs.docker.com/engine/api/v1.40/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the API reference (in a new window)">API 1.40+</span></a><br>Output destination (format: type=local,dest=path)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--platform</code></td> <td></td> <td> +<a href="https://docs.docker.com/engine/api/v1.40/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the API reference (in a new window)">API 1.40+</span></a><br>Set platform if server is multi-platform capable</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--progress</code></td> <td><code class="language-plaintext highlighter-rouge">auto</code></td> <td>Set type of progress output (auto, plain, tty). Use plain to show container output</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--pull</code></td> <td></td> <td>Always attempt to pull a newer version of the image</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--quiet</code> , <code class="language-plaintext highlighter-rouge">-q</code> +</td> <td></td> <td>Suppress the build output and print image ID on success</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--rm</code></td> <td><code class="language-plaintext highlighter-rouge">true</code></td> <td>Remove intermediate containers after a successful build</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--secret</code></td> <td></td> <td>Secret file to expose to the build (only if BuildKit enabled): id=mysecret,src=/local/secret</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--security-opt</code></td> <td></td> <td>Security options</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--shm-size</code></td> <td></td> <td>Size of /dev/shm</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--squash</code></td> <td></td> <td> +<a href="../dockerd/index#daemon-configuration-file" target="_blank" rel="noopener" class="_"><span class="badge badge-warning" data-toggle="tooltip" title="Read about experimental daemon options (in a new window).">experimental (daemon)</span></a><br>Squash newly built layers into a single new layer</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--ssh</code></td> <td></td> <td>SSH agent socket or keys to expose to the build (only if BuildKit enabled) (format: default|<id>[=<socket>|<key>[,<key>]])</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--stream</code></td> <td></td> <td>Stream attaches to server to negotiate build context</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--tag</code> , <code class="language-plaintext highlighter-rouge">-t</code> +</td> <td></td> <td>Name and optionally a tag in the 'name:tag' format</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--target</code></td> <td></td> <td>Set the target build stage to build.</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--ulimit</code></td> <td></td> <td>Ulimit options</td> </tr> </tbody> </table> <h2 id="examples">Examples</h2> <h3 id="build-with-path">Build with PATH</h3> <div class="highlight"><pre class="highlight" data-language="">$ docker build . + +Uploading context 10240 bytes +Step 1/3 : FROM busybox +Pulling repository busybox + ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/ +Step 2/3 : RUN ls -lh / + ---> Running in 9c9e81692ae9 +total 24 +drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin +drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev +drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc +drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib +lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib +dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc +lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin +dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys +drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp +drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr + ---> b35f4035db3f +Step 3/3 : CMD echo Hello world + ---> Running in 02071fceb21b + ---> f52f38b7823e +Successfully built f52f38b7823e +Removing intermediate container 9c9e81692ae9 +Removing intermediate container 02071fceb21b +</pre></div> <p>This example specifies that the <code class="language-plaintext highlighter-rouge">PATH</code> is <code class="language-plaintext highlighter-rouge">.</code>, and so all the files in the local directory get <code class="language-plaintext highlighter-rouge">tar</code>d and sent to the Docker daemon. The <code class="language-plaintext highlighter-rouge">PATH</code> specifies where to find the files for the “context” of the build on the Docker daemon. Remember that the daemon could be running on a remote machine and that no parsing of the Dockerfile happens at the client side (where you’re running <code class="language-plaintext highlighter-rouge">docker build</code>). That means that <em>all</em> the files at <code class="language-plaintext highlighter-rouge">PATH</code> get sent, not just the ones listed to <a href="../../builder/index#add"><em>ADD</em></a> in the Dockerfile.</p> <p>The transfer of context from the local machine to the Docker daemon is what the <code class="language-plaintext highlighter-rouge">docker</code> client means when you see the “Sending build context” message.</p> <p>If you wish to keep the intermediate containers after the build is complete, you must use <code class="language-plaintext highlighter-rouge">--rm=false</code>. This does not affect the build cache.</p> <h3 id="build-with-url">Build with URL</h3> <div class="highlight"><pre class="highlight" data-language="">$ docker build github.com/creack/docker-firefox +</pre></div> <p>This will clone the GitHub repository and use the cloned repository as context. The Dockerfile at the root of the repository is used as Dockerfile. You can specify an arbitrary Git repository by using the <code class="language-plaintext highlighter-rouge">git://</code> or <code class="language-plaintext highlighter-rouge">git@</code> scheme.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build -f ctx/Dockerfile http://server/ctx.tar.gz + +Downloading context: http://server/ctx.tar.gz [===================>] 240 B/240 B +Step 1/3 : FROM busybox + ---> 8c2e06607696 +Step 2/3 : ADD ctx/container.cfg / + ---> e7829950cee3 +Removing intermediate container b35224abf821 +Step 3/3 : CMD /bin/ls + ---> Running in fbc63d321d73 + ---> 3286931702ad +Removing intermediate container fbc63d321d73 +Successfully built 377c409b35e4 +</pre></div> <p>This sends the URL <code class="language-plaintext highlighter-rouge">http://server/ctx.tar.gz</code> to the Docker daemon, which downloads and extracts the referenced tarball. The <code class="language-plaintext highlighter-rouge">-f ctx/Dockerfile</code> parameter specifies a path inside <code class="language-plaintext highlighter-rouge">ctx.tar.gz</code> to the <code class="language-plaintext highlighter-rouge">Dockerfile</code> that is used to build the image. Any <code class="language-plaintext highlighter-rouge">ADD</code> commands in that <code class="language-plaintext highlighter-rouge">Dockerfile</code> that refers to local paths must be relative to the root of the contents inside <code class="language-plaintext highlighter-rouge">ctx.tar.gz</code>. In the example above, the tarball contains a directory <code class="language-plaintext highlighter-rouge">ctx/</code>, so the <code class="language-plaintext highlighter-rouge">ADD ctx/container.cfg /</code> operation works as expected.</p> <h3 id="build-with--">Build with -</h3> <div class="highlight"><pre class="highlight" data-language="">$ docker build - < Dockerfile +</pre></div> <p>This will read a Dockerfile from <code class="language-plaintext highlighter-rouge">STDIN</code> without context. Due to the lack of a context, no contents of any local directory will be sent to the Docker daemon. Since there is no context, a Dockerfile <code class="language-plaintext highlighter-rouge">ADD</code> only works if it refers to a remote URL.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build - < context.tar.gz +</pre></div> <p>This will build an image for a compressed context read from <code class="language-plaintext highlighter-rouge">STDIN</code>. Supported formats are: bzip2, gzip and xz.</p> <h3 id="use-a-dockerignore-file">Use a .dockerignore file</h3> <div class="highlight"><pre class="highlight" data-language="">$ docker build . + +Uploading context 18.829 MB +Uploading context +Step 1/2 : FROM busybox + ---> 769b9341d937 +Step 2/2 : CMD echo Hello world + ---> Using cache + ---> 99cc1ad10469 +Successfully built 99cc1ad10469 +$ echo ".git" > .dockerignore +$ docker build . +Uploading context 6.76 MB +Uploading context +Step 1/2 : FROM busybox + ---> 769b9341d937 +Step 2/2 : CMD echo Hello world + ---> Using cache + ---> 99cc1ad10469 +Successfully built 99cc1ad10469 +</pre></div> <p>This example shows the use of the <code class="language-plaintext highlighter-rouge">.dockerignore</code> file to exclude the <code class="language-plaintext highlighter-rouge">.git</code> directory from the context. Its effect can be seen in the changed size of the uploaded context. The builder reference contains detailed information on <a href="../../builder/index#dockerignore-file">creating a .dockerignore file</a>.</p> <p>When using the <a href="../../builder/index#buildkit">BuildKit backend</a>, <code class="language-plaintext highlighter-rouge">docker build</code> searches for a <code class="language-plaintext highlighter-rouge">.dockerignore</code> file relative to the Dockerfile name. For example, running <code class="language-plaintext highlighter-rouge">docker build -f myapp.Dockerfile .</code> will first look for an ignore file named <code class="language-plaintext highlighter-rouge">myapp.Dockerfile.dockerignore</code>. If such a file is not found, the <code class="language-plaintext highlighter-rouge">.dockerignore</code> file is used if present. Using a Dockerfile based <code class="language-plaintext highlighter-rouge">.dockerignore</code> is useful if a project contains multiple Dockerfiles that expect to ignore different sets of files.</p> <h3 id="tag-an-image--t">Tag an image (-t)</h3> <div class="highlight"><pre class="highlight" data-language="">$ docker build -t vieux/apache:2.0 . +</pre></div> <p>This will build like the previous example, but it will then tag the resulting image. The repository name will be <code class="language-plaintext highlighter-rouge">vieux/apache</code> and the tag will be <code class="language-plaintext highlighter-rouge">2.0</code>. <a href="../tag/index">Read more about valid tags</a>.</p> <p>You can apply multiple tags to an image. For example, you can apply the <code class="language-plaintext highlighter-rouge">latest</code> tag to a newly built image and add another tag that references a specific version. For example, to tag an image both as <code class="language-plaintext highlighter-rouge">whenry/fedora-jboss:latest</code> and <code class="language-plaintext highlighter-rouge">whenry/fedora-jboss:v2.1</code>, use the following:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 . +</pre></div> <h3 id="specify-a-dockerfile--f">Specify a Dockerfile (-f)</h3> <div class="highlight"><pre class="highlight" data-language="">$ docker build -f Dockerfile.debug . +</pre></div> <p>This will use a file called <code class="language-plaintext highlighter-rouge">Dockerfile.debug</code> for the build instructions instead of <code class="language-plaintext highlighter-rouge">Dockerfile</code>.</p> <div class="highlight"><pre class="highlight" data-language="">$ curl example.com/remote/Dockerfile | docker build -f - . +</pre></div> <p>The above command will use the current directory as the build context and read a Dockerfile from stdin.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug . +$ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod . +</pre></div> <p>The above commands will build the current build context (as specified by the <code class="language-plaintext highlighter-rouge">.</code>) twice, once using a debug version of a <code class="language-plaintext highlighter-rouge">Dockerfile</code> and once using a production version.</p> <div class="highlight"><pre class="highlight" data-language="">$ cd /home/me/myapp/some/dir/really/deep +$ docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp +$ docker build -f ../../../../dockerfiles/debug /home/me/myapp +</pre></div> <p>These two <code class="language-plaintext highlighter-rouge">docker build</code> commands do the exact same thing. They both use the contents of the <code class="language-plaintext highlighter-rouge">debug</code> file instead of looking for a <code class="language-plaintext highlighter-rouge">Dockerfile</code> and will use <code class="language-plaintext highlighter-rouge">/home/me/myapp</code> as the root of the build context. Note that <code class="language-plaintext highlighter-rouge">debug</code> is in the directory structure of the build context, regardless of how you refer to it on the command line.</p> <blockquote> <p><strong>Note</strong></p> <p><code class="language-plaintext highlighter-rouge">docker build</code> returns a <code class="language-plaintext highlighter-rouge">no such file or directory</code> error if the file or directory does not exist in the uploaded context. This may happen if there is no context, or if you specify a file that is elsewhere on the Host system. The context is limited to the current directory (and its children) for security reasons, and to ensure repeatable builds on remote Docker hosts. This is also the reason why <code class="language-plaintext highlighter-rouge">ADD ../file</code> does not work.</p> </blockquote> <h3 id="use-a-custom-parent-cgroup---cgroup-parent">Use a custom parent cgroup (--cgroup-parent)</h3> <p>When <code class="language-plaintext highlighter-rouge">docker build</code> is run with the <code class="language-plaintext highlighter-rouge">--cgroup-parent</code> option the containers used in the build will be run with the <a href="../../run/index#specify-custom-cgroups">corresponding <code class="language-plaintext highlighter-rouge">docker run</code> flag</a>.</p> <h3 id="set-ulimits-in-container---ulimit">Set ulimits in container (--ulimit)</h3> <p>Using the <code class="language-plaintext highlighter-rouge">--ulimit</code> option with <code class="language-plaintext highlighter-rouge">docker build</code> will cause each build step’s container to be started using those <a href="../run/index#set-ulimits-in-container---ulimit"><code class="language-plaintext highlighter-rouge">--ulimit</code> flag values</a>.</p> <h3 id="set-build-time-variables---build-arg">Set build-time variables (--build-arg)</h3> <p>You can use <code class="language-plaintext highlighter-rouge">ENV</code> instructions in a Dockerfile to define variable values. These values persist in the built image. However, often persistence is not what you want. Users want to specify variables differently depending on which host they build an image on.</p> <p>A good example is <code class="language-plaintext highlighter-rouge">http_proxy</code> or source versions for pulling intermediate files. The <code class="language-plaintext highlighter-rouge">ARG</code> instruction lets Dockerfile authors define values that users can set at build-time using the <code class="language-plaintext highlighter-rouge">--build-arg</code> flag:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 . +</pre></div> <p>This flag allows you to pass the build-time variables that are accessed like regular environment variables in the <code class="language-plaintext highlighter-rouge">RUN</code> instruction of the Dockerfile. Also, these values don’t persist in the intermediate or final images like <code class="language-plaintext highlighter-rouge">ENV</code> values do. You must add <code class="language-plaintext highlighter-rouge">--build-arg</code> for each build argument.</p> <p>Using this flag will not alter the output you see when the <code class="language-plaintext highlighter-rouge">ARG</code> lines from the Dockerfile are echoed during the build process.</p> <p>For detailed information on using <code class="language-plaintext highlighter-rouge">ARG</code> and <code class="language-plaintext highlighter-rouge">ENV</code> instructions, see the <a href="../../builder/index">Dockerfile reference</a>.</p> <p>You may also use the <code class="language-plaintext highlighter-rouge">--build-arg</code> flag without a value, in which case the value from the local environment will be propagated into the Docker container being built:</p> <div class="highlight"><pre class="highlight" data-language="">$ export HTTP_PROXY=http://10.20.30.2:1234 +$ docker build --build-arg HTTP_PROXY . +</pre></div> <p>This is similar to how <code class="language-plaintext highlighter-rouge">docker run -e</code> works. Refer to the <a href="../run/index#set-environment-variables--e---env---env-file"><code class="language-plaintext highlighter-rouge">docker run</code> documentation</a> for more information.</p> <h3 id="optional-security-options---security-opt">Optional security options (--security-opt)</h3> <p>This flag is only supported on a daemon running on Windows, and only supports the <code class="language-plaintext highlighter-rouge">credentialspec</code> option. The <code class="language-plaintext highlighter-rouge">credentialspec</code> must be in the format <code class="language-plaintext highlighter-rouge">file://spec.txt</code> or <code class="language-plaintext highlighter-rouge">registry://keyname</code>.</p> <h3 id="specify-isolation-technology-for-container---isolation">Specify isolation technology for container (--isolation)</h3> <p>This option is useful in situations where you are running Docker containers on Windows. The <code class="language-plaintext highlighter-rouge">--isolation=<value></code> option sets a container’s isolation technology. On Linux, the only supported is the <code class="language-plaintext highlighter-rouge">default</code> option which uses Linux namespaces. On Microsoft Windows, you can specify these values:</p> <table> <thead> <tr> <th>Value</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">default</code></td> <td>Use the value specified by the Docker daemon’s <code class="language-plaintext highlighter-rouge">--exec-opt</code> . If the <code class="language-plaintext highlighter-rouge">daemon</code> does not specify an isolation technology, Microsoft Windows uses <code class="language-plaintext highlighter-rouge">process</code> as its default value.</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">process</code></td> <td>Namespace isolation only.</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">hyperv</code></td> <td>Hyper-V hypervisor partition-based isolation.</td> </tr> </tbody> </table> <p>Specifying the <code class="language-plaintext highlighter-rouge">--isolation</code> flag without a value is the same as setting <code class="language-plaintext highlighter-rouge">--isolation="default"</code>.</p> <h3 id="add-entries-to-container-hosts-file---add-host">Add entries to container hosts file (--add-host)</h3> <p>You can add other hosts into a container’s <code class="language-plaintext highlighter-rouge">/etc/hosts</code> file by using one or more <code class="language-plaintext highlighter-rouge">--add-host</code> flags. This example adds a static address for a host named <code class="language-plaintext highlighter-rouge">docker</code>:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build --add-host=docker:10.180.0.1 . +</pre></div> <h3 id="specifying-target-build-stage---target">Specifying target build stage (--target)</h3> <p>When building a Dockerfile with multiple build stages, <code class="language-plaintext highlighter-rouge">--target</code> can be used to specify an intermediate build stage by name as a final stage for the resulting image. Commands after the target stage will be skipped.</p> <div class="highlight"><pre class="highlight" data-language="">FROM debian AS build-env +# ... + +FROM alpine AS production-env +# ... +</pre></div> <div class="highlight"><pre class="highlight" data-language="">$ docker build -t mybuildimage --target build-env . +</pre></div> <h3 id="custom-build-outputs">Custom build outputs</h3> <p>By default, a local container image is created from the build result. The <code class="language-plaintext highlighter-rouge">--output</code> (or <code class="language-plaintext highlighter-rouge">-o</code>) flag allows you to override this behavior, and a specify a custom exporter. For example, custom exporters allow you to export the build artifacts as files on the local filesystem instead of a Docker image, which can be useful for generating local binaries, code generation etc.</p> <p>The value for <code class="language-plaintext highlighter-rouge">--output</code> is a CSV-formatted string defining the exporter type and options. Currently, <code class="language-plaintext highlighter-rouge">local</code> and <code class="language-plaintext highlighter-rouge">tar</code> exporters are supported. The <code class="language-plaintext highlighter-rouge">local</code> exporter writes the resulting build files to a directory on the client side. The <code class="language-plaintext highlighter-rouge">tar</code> exporter is similar but writes the files as a single tarball (<code class="language-plaintext highlighter-rouge">.tar</code>).</p> <p>If no type is specified, the value defaults to the output directory of the local exporter. Use a hyphen (<code class="language-plaintext highlighter-rouge">-</code>) to write the output tarball to standard output (<code class="language-plaintext highlighter-rouge">STDOUT</code>).</p> <p>The following example builds an image using the current directory (<code class="language-plaintext highlighter-rouge">.</code>) as build context, and exports the files to a directory named <code class="language-plaintext highlighter-rouge">out</code> in the current directory. If the directory does not exist, Docker creates the directory automatically:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build -o out . +</pre></div> <p>The example above uses the short-hand syntax, omitting the <code class="language-plaintext highlighter-rouge">type</code> options, and thus uses the default (<code class="language-plaintext highlighter-rouge">local</code>) exporter. The example below shows the equivalent using the long-hand CSV syntax, specifying both <code class="language-plaintext highlighter-rouge">type</code> and <code class="language-plaintext highlighter-rouge">dest</code> (destination path):</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build --output type=local,dest=out . +</pre></div> <p>Use the <code class="language-plaintext highlighter-rouge">tar</code> type to export the files as a <code class="language-plaintext highlighter-rouge">.tar</code> archive:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build --output type=tar,dest=out.tar . +</pre></div> <p>The example below shows the equivalent when using the short-hand syntax. In this case, <code class="language-plaintext highlighter-rouge">-</code> is specified as destination, which automatically selects the <code class="language-plaintext highlighter-rouge">tar</code> type, and writes the output tarball to standard output, which is then redirected to the <code class="language-plaintext highlighter-rouge">out.tar</code> file:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build -o - . > out.tar +</pre></div> <p>The <code class="language-plaintext highlighter-rouge">--output</code> option exports all files from the target stage. A common pattern for exporting only specific files is to do multi-stage builds and to copy the desired files to a new scratch stage with <a href="../../builder/index#copy"><code class="language-plaintext highlighter-rouge">COPY --from</code></a>.</p> <p>The example <code class="language-plaintext highlighter-rouge">Dockerfile</code> below uses a separate stage to collect the build-artifacts for exporting:</p> <div class="highlight"><pre class="highlight" data-language="">FROM golang AS build-stage +RUN go get -u github.com/LK4D4/vndr + +FROM scratch AS export-stage +COPY --from=build-stage /go/bin/vndr / +</pre></div> <p>When building the Dockerfile with the <code class="language-plaintext highlighter-rouge">-o</code> option, only the files from the final stage are exported to the <code class="language-plaintext highlighter-rouge">out</code> directory, in this case, the <code class="language-plaintext highlighter-rouge">vndr</code> binary:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build -o out . + +[+] Building 2.3s (7/7) FINISHED + => [internal] load build definition from Dockerfile 0.1s + => => transferring dockerfile: 176B 0.0s + => [internal] load .dockerignore 0.0s + => => transferring context: 2B 0.0s + => [internal] load metadata for docker.io/library/golang:latest 1.6s + => [build-stage 1/2] FROM docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s + => => resolve docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s + => CACHED [build-stage 2/2] RUN go get -u github.com/LK4D4/vndr 0.0s + => [export-stage 1/1] COPY --from=build-stage /go/bin/vndr / 0.2s + => exporting to client 0.4s + => => copying files 10.30MB 0.3s + +$ ls ./out +vndr +</pre></div> <blockquote> <p><strong>Note</strong></p> <p>This feature requires the BuildKit backend. You can either <a href="../../builder/index#buildkit">enable BuildKit</a> or use the <a href="https://github.com/docker/buildx">buildx</a> plugin which provides more output type options.</p> </blockquote> <h3 id="specifying-external-cache-sources">Specifying external cache sources</h3> <p>In addition to local build cache, the builder can reuse the cache generated from previous builds with the <code class="language-plaintext highlighter-rouge">--cache-from</code> flag pointing to an image in the registry.</p> <p>To use an image as a cache source, cache metadata needs to be written into the image on creation. This can be done by setting <code class="language-plaintext highlighter-rouge">--build-arg BUILDKIT_INLINE_CACHE=1</code> when building the image. After that, the built image can be used as a cache source for subsequent builds.</p> <p>Upon importing the cache, the builder will only pull the JSON metadata from the registry and determine possible cache hits based on that information. If there is a cache hit, the matched layers are pulled into the local environment.</p> <p>In addition to images, the cache can also be pulled from special cache manifests generated by <a href="https://github.com/docker/buildx"><code class="language-plaintext highlighter-rouge">buildx</code></a> or the BuildKit CLI (<code class="language-plaintext highlighter-rouge">buildctl</code>). These manifests (when built with the <code class="language-plaintext highlighter-rouge">type=registry</code> and <code class="language-plaintext highlighter-rouge">mode=max</code> options) allow pulling layer data for intermediate stages in multi-stage builds.</p> <p>The following example builds an image with inline-cache metadata and pushes it to a registry, then uses the image as a cache source on another machine:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build -t myname/myapp --build-arg BUILDKIT_INLINE_CACHE=1 . +$ docker push myname/myapp +</pre></div> <p>After pushing the image, the image is used as cache source on another machine. BuildKit automatically pulls the image from the registry if needed.</p> <p>On another machine:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build --cache-from myname/myapp . +</pre></div> <blockquote> <p><strong>Note</strong></p> <p>This feature requires the BuildKit backend. You can either <a href="../../builder/index#buildkit">enable BuildKit</a> or use the <a href="https://github.com/docker/buildx">buildx</a> plugin. The previous builder has limited support for reusing cache from pre-pulled images.</p> </blockquote> <h3 id="squash-an-images-layers---squash-experimental">Squash an image’s layers (--squash) (experimental)</h3> <h4 id="overview">Overview</h4> <p>Once the image is built, squash the new layers into a new image with a single new layer. Squashing does not destroy any existing image, rather it creates a new image with the content of the squashed layers. This effectively makes it look like all <code class="language-plaintext highlighter-rouge">Dockerfile</code> commands were created with a single layer. The build cache is preserved with this method.</p> <p>The <code class="language-plaintext highlighter-rouge">--squash</code> option is an experimental feature, and should not be considered stable.</p> <p>Squashing layers can be beneficial if your Dockerfile produces multiple layers modifying the same files, for example, files that are created in one step, and removed in another step. For other use-cases, squashing images may actually have a negative impact on performance; when pulling an image consisting of multiple layers, layers can be pulled in parallel, and allows sharing layers between images (saving space).</p> <p>For most use cases, multi-stage builds are a better alternative, as they give more fine-grained control over your build, and can take advantage of future optimizations in the builder. Refer to the <a href="https://docs.docker.com/develop/develop-images/multistage-build/">use multi-stage builds</a> section in the userguide for more information.</p> <h4 id="known-limitations">Known limitations</h4> <p>The <code class="language-plaintext highlighter-rouge">--squash</code> option has a number of known limitations:</p> <ul> <li>When squashing layers, the resulting image cannot take advantage of layer sharing with other images, and may use significantly more space. Sharing the base image is still supported.</li> <li>When using this option you may see significantly more space used due to storing two copies of the image, one for the build cache with all the cache layers intact, and one for the squashed version.</li> <li>While squashing layers may produce smaller images, it may have a negative impact on performance, as a single layer takes longer to extract, and downloading a single layer cannot be parallelized.</li> <li>When attempting to squash an image that does not make changes to the filesystem (for example, the Dockerfile only contains <code class="language-plaintext highlighter-rouge">ENV</code> instructions), the squash step will fail (see <a href="https://github.com/moby/moby/issues/33823">issue #33823</a>).</li> </ul> <h4 id="prerequisites">Prerequisites</h4> <p>The example on this page is using experimental mode in Docker 19.03.</p> <p>Experimental mode can be enabled by using the <code class="language-plaintext highlighter-rouge">--experimental</code> flag when starting the Docker daemon or setting <code class="language-plaintext highlighter-rouge">experimental: true</code> in the <code class="language-plaintext highlighter-rouge">daemon.json</code> configuration file.</p> <p>By default, experimental mode is disabled. To see the current configuration of the docker daemon, use the <code class="language-plaintext highlighter-rouge">docker version</code> command and check the <code class="language-plaintext highlighter-rouge">Experimental</code> line in the <code class="language-plaintext highlighter-rouge">Engine</code> section:</p> <div class="highlight"><pre class="highlight" data-language="">Client: Docker Engine - Community + Version: 19.03.8 + API version: 1.40 + Go version: go1.12.17 + Git commit: afacb8b + Built: Wed Mar 11 01:21:11 2020 + OS/Arch: darwin/amd64 + Experimental: false + +Server: Docker Engine - Community + Engine: + Version: 19.03.8 + API version: 1.40 (minimum version 1.12) + Go version: go1.12.17 + Git commit: afacb8b + Built: Wed Mar 11 01:29:16 2020 + OS/Arch: linux/amd64 + Experimental: true + [...] +</pre></div> <p>To enable experimental mode, users need to restart the docker daemon with the experimental flag enabled.</p> <h4 id="enable-docker-experimental">Enable Docker experimental</h4> <p>To enable experimental features, you need to start the Docker daemon with <code class="language-plaintext highlighter-rouge">--experimental</code> flag. You can also enable the daemon flag via <code class="language-plaintext highlighter-rouge">/etc/docker/daemon.json</code>, for example:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "experimental": true +} +</pre></div> <p>Then make sure the experimental flag is enabled:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker version -f '{{.Server.Experimental}}' +true +</pre></div> <h4 id="build-an-image-with---squash-argument">Build an image with <code class="language-plaintext highlighter-rouge">--squash</code> argument</h4> <p>The following is an example of docker build with <code class="language-plaintext highlighter-rouge">--squash</code> argument</p> <div class="highlight"><pre class="highlight" data-language="">FROM busybox +RUN echo hello > /hello +RUN echo world >> /hello +RUN touch remove_me /remove_me +ENV HELLO=world +RUN rm /remove_me +</pre></div> <p>An image named <code class="language-plaintext highlighter-rouge">test</code> is built with <code class="language-plaintext highlighter-rouge">--squash</code> argument.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker build --squash -t test . + +<...> +</pre></div> <p>If everything is right, the history looks like this:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker history test + +IMAGE CREATED CREATED BY SIZE COMMENT +4e10cb5b4cac 3 seconds ago 12 B merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb +<missing> 5 minutes ago /bin/sh -c rm /remove_me 0 B +<missing> 5 minutes ago /bin/sh -c #(nop) ENV HELLO=world 0 B +<missing> 5 minutes ago /bin/sh -c touch remove_me /remove_me 0 B +<missing> 5 minutes ago /bin/sh -c echo world >> /hello 0 B +<missing> 6 minutes ago /bin/sh -c echo hello > /hello 0 B +<missing> 7 weeks ago /bin/sh -c #(nop) CMD ["sh"] 0 B +<missing> 7 weeks ago /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff 1.113 MB +</pre></div> <p>We could find that a layer’s name is <code class="language-plaintext highlighter-rouge"><missing></code>, and there is a new layer with COMMENT <code class="language-plaintext highlighter-rouge">merge</code>.</p> <p>Test the image, check for <code class="language-plaintext highlighter-rouge">/remove_me</code> being gone, make sure <code class="language-plaintext highlighter-rouge">hello\nworld</code> is in <code class="language-plaintext highlighter-rouge">/hello</code>, make sure the <code class="language-plaintext highlighter-rouge">HELLO</code> environment variable’s value is <code class="language-plaintext highlighter-rouge">world</code>.</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/commandline/build/" class="_attribution-link">https://docs.docker.com/engine/reference/commandline/build/</a> + </p> +</div> |