mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
253 lines
11 KiB
Markdown
253 lines
11 KiB
Markdown
<!--[metadata]>
|
|
+++
|
|
title = "build"
|
|
description = "The build command description and usage"
|
|
keywords = ["build, docker, image"]
|
|
[menu.main]
|
|
parent = "smn_cli"
|
|
weight=1
|
|
+++
|
|
<![end-metadata]-->
|
|
|
|
# build
|
|
|
|
Usage: docker build [OPTIONS] PATH | URL | -
|
|
|
|
Build a new image from the source code at PATH
|
|
|
|
-f, --file="" Name of the Dockerfile (Default is 'PATH/Dockerfile')
|
|
--force-rm=false Always remove intermediate containers
|
|
--no-cache=false Do not use cache when building the image
|
|
--pull=false Always attempt to pull a newer version of the image
|
|
-q, --quiet=false Suppress the verbose output generated by the containers
|
|
--rm=true Remove intermediate containers after a successful build
|
|
-t, --tag="" Repository name (and optionally a tag) for the image
|
|
-m, --memory="" Memory limit for all build containers
|
|
--memory-swap="" Total memory (memory + swap), `-1` to disable swap
|
|
-c, --cpu-shares CPU Shares (relative weight)
|
|
--cpuset-mems="" MEMs in which to allow execution, e.g. `0-3`, `0,1`
|
|
--cpuset-cpus="" CPUs in which to allow execution, e.g. `0-3`, `0,1`
|
|
--cgroup-parent="" Optional parent cgroup for the container
|
|
--ulimit=[] Ulimit options
|
|
|
|
Builds Docker images from a Dockerfile and a "context". A build's context is
|
|
the files located in the specified `PATH` or `URL`. The build process can refer
|
|
to any of the files in the context. For example, your build can use an
|
|
[*ADD*](/reference/builder/#add) instruction to reference a file in the
|
|
context.
|
|
|
|
The `URL` parameter can specify the location of a Git repository; the repository
|
|
acts as the build context. The system recursively clones the repository and its
|
|
submodules using a `git clone --depth 1 --recursive` command. This command runs
|
|
in a temporary directory on your local host. After the command succeeds, the
|
|
directory is sent to the Docker daemon as the context. Local clones give you the
|
|
ability to access private repositories using local user credentials, VPNs, and
|
|
so forth.
|
|
|
|
Git URLs accept context configuration in their fragment section, separated by a
|
|
colon `:`. The first part represents the reference that Git will check out,
|
|
this can be either a branch, a tag, or a commit SHA. The second part represents
|
|
a subdirectory inside the repository that will be used as a build context.
|
|
|
|
For example, run this command to use a directory called `docker` in the branch
|
|
`container`:
|
|
|
|
$ docker build https://github.com/docker/rootfs.git#container:docker
|
|
|
|
The following table represents all the valid suffixes with their build
|
|
contexts:
|
|
|
|
Build Syntax Suffix | Commit Used | Build Context Used
|
|
--------------------|-------------|-------------------
|
|
`myrepo.git` | `refs/heads/master` | `/`
|
|
`myrepo.git#mytag` | `refs/tags/mytag` | `/`
|
|
`myrepo.git#mybranch` | `refs/heads/mybranch` | `/`
|
|
`myrepo.git#abcdef` | `sha1 = abcdef` | `/`
|
|
`myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder`
|
|
`myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder`
|
|
`myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder`
|
|
`myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder`
|
|
`myrepo.git#abcdef:myfolder` | `sha1 = abcdef` | `/myfolder`
|
|
|
|
Instead of specifying a context, you can pass a single Dockerfile in the `URL`
|
|
or pipe the file in via `STDIN`. To pipe a Dockerfile from `STDIN`:
|
|
|
|
docker build - < Dockerfile
|
|
|
|
If you use STDIN or specify a `URL`, the system places the contents into a file
|
|
called `Dockerfile`, and any `-f`, `--file` option is ignored. In this
|
|
scenario, there is no context.
|
|
|
|
By default the `docker build` command will look for a `Dockerfile` at the root
|
|
of the build context. The `-f`, `--file`, 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 must to be relative to
|
|
the current directory.
|
|
|
|
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 `.dockerignore` file to that directory as well. For information on
|
|
creating one, see the [.dockerignore file](/reference/builder#dockerignore-file).
|
|
|
|
If the Docker client loses connection to the daemon, the build is canceled.
|
|
This happens if you interrupt the Docker client with `ctrl-c` or if the Docker
|
|
client is killed for any reason.
|
|
|
|
> **Note:**
|
|
> Currently only the "run" phase of the build can be canceled until pull
|
|
> cancellation is implemented).
|
|
|
|
## Return code
|
|
|
|
On a successful build, a return code of success `0` will be returned. When the
|
|
build fails, a non-zero failure code will be returned.
|
|
|
|
There should be informational output of the reason for failure output to
|
|
`STDERR`:
|
|
|
|
$ docker build -t fail .
|
|
Sending build context to Docker daemon 2.048 kB
|
|
Sending build context to Docker daemon
|
|
Step 0 : FROM busybox
|
|
---> 4986bf8c1536
|
|
Step 1 : RUN exit 13
|
|
---> Running in e26670ec7a0a
|
|
INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13
|
|
$ echo $?
|
|
1
|
|
|
|
See also:
|
|
|
|
[*Dockerfile Reference*](/reference/builder).
|
|
|
|
## Examples
|
|
|
|
$ docker build .
|
|
Uploading context 10240 bytes
|
|
Step 1 : FROM busybox
|
|
Pulling repository busybox
|
|
---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/
|
|
Step 2 : 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 : CMD echo Hello world
|
|
---> Running in 02071fceb21b
|
|
---> f52f38b7823e
|
|
Successfully built f52f38b7823e
|
|
Removing intermediate container 9c9e81692ae9
|
|
Removing intermediate container 02071fceb21b
|
|
|
|
This example specifies that the `PATH` is `.`, and so all the files in the
|
|
local directory get `tar`d and sent to the Docker daemon. The `PATH` 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
|
|
`docker build`). That means that *all* the files at `PATH` get sent, not just
|
|
the ones listed to [*ADD*](/reference/builder/#add) in the Dockerfile.
|
|
|
|
The transfer of context from the local machine to the Docker daemon is what the
|
|
`docker` client means when you see the "Sending build context" message.
|
|
|
|
If you wish to keep the intermediate containers after the build is complete,
|
|
you must use `--rm=false`. This does not affect the build cache.
|
|
|
|
$ docker build .
|
|
Uploading context 18.829 MB
|
|
Uploading context
|
|
Step 0 : FROM busybox
|
|
---> 769b9341d937
|
|
Step 1 : CMD echo Hello world
|
|
---> Using cache
|
|
---> 99cc1ad10469
|
|
Successfully built 99cc1ad10469
|
|
$ echo ".git" > .dockerignore
|
|
$ docker build .
|
|
Uploading context 6.76 MB
|
|
Uploading context
|
|
Step 0 : FROM busybox
|
|
---> 769b9341d937
|
|
Step 1 : CMD echo Hello world
|
|
---> Using cache
|
|
---> 99cc1ad10469
|
|
Successfully built 99cc1ad10469
|
|
|
|
This example shows the use of the `.dockerignore` file to exclude the `.git`
|
|
directory from the context. Its effect can be seen in the changed size of the
|
|
uploaded context. The builder reference contains detailed information on
|
|
[creating a .dockerignore file](../../builder/#dockerignore-file)
|
|
|
|
$ docker build -t vieux/apache:2.0 .
|
|
|
|
This will build like the previous example, but it will then tag the resulting
|
|
image. The repository name will be `vieux/apache` and the tag will be `2.0`
|
|
|
|
$ docker build - < Dockerfile
|
|
|
|
This will read a Dockerfile from `STDIN` 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 `ADD` only works if it refers to a
|
|
remote URL.
|
|
|
|
$ docker build - < context.tar.gz
|
|
|
|
This will build an image for a compressed context read from `STDIN`. Supported
|
|
formats are: bzip2, gzip and xz.
|
|
|
|
$ docker build github.com/creack/docker-firefox
|
|
|
|
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. Note that
|
|
you can specify an arbitrary Git repository by using the `git://` or `git@`
|
|
schema.
|
|
|
|
$ docker build -f Dockerfile.debug .
|
|
|
|
This will use a file called `Dockerfile.debug` for the build instructions
|
|
instead of `Dockerfile`.
|
|
|
|
$ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug .
|
|
$ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod .
|
|
|
|
The above commands will build the current build context (as specified by the
|
|
`.`) twice, once using a debug version of a `Dockerfile` and once using a
|
|
production version.
|
|
|
|
$ 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
|
|
|
|
These two `docker build` commands do the exact same thing. They both use the
|
|
contents of the `debug` file instead of looking for a `Dockerfile` and will use
|
|
`/home/me/myapp` as the root of the build context. Note that `debug` is in the
|
|
directory structure of the build context, regardless of how you refer to it on
|
|
the command line.
|
|
|
|
> **Note:**
|
|
> `docker build` will return a `no such file or directory` 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
|
|
> `ADD ../file` will not work.
|
|
|
|
When `docker build` is run with the `--cgroup-parent` option the containers
|
|
used in the build will be run with the [corresponding `docker run`
|
|
flag](/reference/run/#specifying-custom-cgroups).
|
|
|
|
Using the `--ulimit` option with `docker build` will cause each build step's
|
|
container to be started using those [`--ulimit`
|
|
flag values](/reference/run/#setting-ulimits-in-a-container).
|