mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
54240f8da9
- The build-time variables are passed as environment-context for command(s) run as part of the RUN primitve. These variables are not persisted in environment of intermediate and final images when passed as context for RUN. The build environment is prepended to the intermediate continer's command string for aiding cache lookups. It also helps with build traceability. But this also makes the feature less secure from point of view of passing build time secrets. - The build-time variables also get used to expand the symbols used in certain Dockerfile primitves like ADD, COPY, USER etc, without an explicit prior definiton using a ENV primitive. These variables get persisted in the intermediate and final images whenever they are expanded. - The build-time variables are only expanded or passed to the RUN primtive if they are defined in Dockerfile using the ARG primitive or belong to list of built-in variables. HTTP_PROXY, HTTPS_PROXY, http_proxy, https_proxy, FTP_PROXY and NO_PROXY are built-in variables that needn't be explicitly defined in Dockerfile to use this feature. Signed-off-by: Madhav Puri <madhav.puri@gmail.com>
273 lines
12 KiB
Markdown
273 lines
12 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
|
|
--build-arg=[] Set build-time variables
|
|
--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 1 : FROM busybox
|
|
---> 4986bf8c1536
|
|
Step 2 : 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 1 : FROM busybox
|
|
---> 769b9341d937
|
|
Step 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 : FROM busybox
|
|
---> 769b9341d937
|
|
Step 2 : 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).
|
|
|
|
You can use `ENV` 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.
|
|
|
|
A good example is `http_proxy` or source versions for pulling intermediate
|
|
files. The `ARG` instruction lets Dockerfile authors define values that users
|
|
can set at build-time using the `---build-arg` flag:
|
|
|
|
$ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 .
|
|
|
|
This flag allows you to pass the build-time variables that are
|
|
accessed like regular environment variables in the `RUN` instruction of the
|
|
Dockerfile. Also, these values don't persist in the intermediate or final images
|
|
like `ENV` values do.
|
|
|
|
For detailed information on using `ARG` and `ENV` instructions, see the
|
|
[Dockerfile reference](/reference/builder).
|