mirror of https://github.com/docker/docs.git
359 lines
22 KiB
YAML
359 lines
22 KiB
YAML
command: docker build
|
|
short: Build an image from a Dockerfile
|
|
long: |-
|
|
The `docker build` command builds Docker images from a Dockerfile and a
|
|
"context". A build's context is the set of 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 a [*COPY*](../builder.md#copy)
|
|
instruction to reference a file in the context.
|
|
|
|
The `URL` parameter can refer to three kinds of resources: Git repositories,
|
|
pre-packaged tarball contexts and plain text files.
|
|
|
|
### Git repositories
|
|
|
|
When the `URL` 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
|
|
the 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.
|
|
|
|
> **Note:**
|
|
> If the `URL` parameter contains a fragment the system will recursively clone
|
|
> the repository and its submodules using a `git clone --recursive` command.
|
|
|
|
Git URLs accept context configuration in their fragment section, separated by a
|
|
colon `:`. 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.
|
|
|
|
For example, run this command to use a directory called `docker` in the branch
|
|
`container`:
|
|
|
|
```bash
|
|
$ 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#pull/42/head` | `refs/pull/42/head` | `/`
|
|
`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`
|
|
|
|
|
|
### Tarball contexts
|
|
|
|
If you pass an URL to a remote tarball, the URL itself is sent to the daemon:
|
|
|
|
```bash
|
|
$ docker build http://server/context.tar.gz
|
|
```
|
|
|
|
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 `context.tar.gz` and use it as the
|
|
build context. Tarball contexts must be tar archives conforming to the standard
|
|
`tar` UNIX format and can be compressed with any one of the 'xz', 'bzip2',
|
|
'gzip' or 'identity' (no compression) formats.
|
|
|
|
### Text files
|
|
|
|
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`:
|
|
|
|
```bash
|
|
$ docker build - < Dockerfile
|
|
```
|
|
|
|
With Powershell on Windows, you can run:
|
|
|
|
```powershell
|
|
Get-Content Dockerfile | docker build -
|
|
```
|
|
|
|
If you use `STDIN` or specify a `URL` pointing to a plain text file, 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 is interpreted as
|
|
relative to the root of the context.
|
|
|
|
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](../builder.md#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. If the build initiated a pull which is still
|
|
running at the time the build is cancelled, the pull is cancelled as well.
|
|
usage: docker build [OPTIONS] PATH | URL | -
|
|
pname: docker
|
|
plink: docker.yaml
|
|
options:
|
|
- option: add-host
|
|
description: Add a custom host-to-IP mapping (host:ip)
|
|
- option: build-arg
|
|
description: Set build-time variables
|
|
- option: cache-from
|
|
default_value: '[]'
|
|
description: Images to consider as cache sources
|
|
- option: cgroup-parent
|
|
description: Optional parent cgroup for the container
|
|
- option: compress
|
|
default_value: "false"
|
|
description: Compress the build context using gzip
|
|
- option: cpu-period
|
|
default_value: "0"
|
|
description: Limit the CPU CFS (Completely Fair Scheduler) period
|
|
- option: cpu-quota
|
|
default_value: "0"
|
|
description: Limit the CPU CFS (Completely Fair Scheduler) quota
|
|
- option: cpu-shares
|
|
shorthand: c
|
|
default_value: "0"
|
|
description: CPU shares (relative weight)
|
|
- option: cpuset-cpus
|
|
description: CPUs in which to allow execution (0-3, 0,1)
|
|
- option: cpuset-mems
|
|
description: MEMs in which to allow execution (0-3, 0,1)
|
|
- option: disable-content-trust
|
|
default_value: "true"
|
|
description: Skip image verification
|
|
- option: file
|
|
shorthand: f
|
|
description: Name of the Dockerfile (Default is 'PATH/Dockerfile')
|
|
- option: force-rm
|
|
default_value: "false"
|
|
description: Always remove intermediate containers
|
|
- option: iidfile
|
|
description: Write the image ID to the file
|
|
- option: isolation
|
|
description: Container isolation technology
|
|
- option: label
|
|
description: Set metadata for an image
|
|
- option: memory
|
|
shorthand: m
|
|
default_value: "0"
|
|
description: Memory limit
|
|
- option: memory-swap
|
|
default_value: "0"
|
|
description: |
|
|
Swap limit equal to memory plus swap: '-1' to enable unlimited swap
|
|
- option: network
|
|
default_value: default
|
|
description: |
|
|
Set the networking mode for the RUN instructions during build
|
|
- option: no-cache
|
|
default_value: "false"
|
|
description: Do not use cache when building the image
|
|
- option: pull
|
|
default_value: "false"
|
|
description: Always attempt to pull a newer version of the image
|
|
- option: quiet
|
|
shorthand: q
|
|
default_value: "false"
|
|
description: Suppress the build output and print image ID on success
|
|
- option: rm
|
|
default_value: "true"
|
|
description: Remove intermediate containers after a successful build
|
|
- option: security-opt
|
|
default_value: '[]'
|
|
description: Security options
|
|
- option: shm-size
|
|
default_value: "0"
|
|
description: Size of /dev/shm
|
|
- option: squash
|
|
default_value: "false"
|
|
description: Squash newly built layers into a single new layer
|
|
- option: tag
|
|
shorthand: t
|
|
description: Name and optionally a tag in the 'name:tag' format
|
|
- option: target
|
|
description: Set the target build stage to build.
|
|
- option: ulimit
|
|
default_value: '[]'
|
|
description: Ulimit options
|
|
examples: "### Build with PATH\n\n```bash\n$ docker build .\n\nUploading context 10240
|
|
bytes\nStep 1/3 : FROM busybox\nPulling repository busybox\n ---> e9aa60c60128MB/2.284
|
|
MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/\nStep 2/3 : RUN ls -lh
|
|
/\n ---> Running in 9c9e81692ae9\ntotal 24\ndrwxr-xr-x 2 root root 4.0K
|
|
Mar 12 2013 bin\ndrwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev\ndrwxr-xr-x
|
|
\ 2 root root 4.0K Oct 19 00:19 etc\ndrwxr-xr-x 2 root root
|
|
\ 4.0K Nov 15 23:34 lib\nlrwxrwxrwx 1 root root 3 Mar 12
|
|
\ 2013 lib64 -> lib\ndr-xr-xr-x 116 root root 0 Nov 15 23:34 proc\nlrwxrwxrwx
|
|
\ 1 root root 3 Mar 12 2013 sbin -> bin\ndr-xr-xr-x 13 root root
|
|
\ 0 Nov 15 23:34 sys\ndrwxr-xr-x 2 root root 4.0K Mar 12
|
|
\ 2013 tmp\ndrwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr\n ---> b35f4035db3f\nStep
|
|
3/3 : CMD echo Hello world\n ---> Running in 02071fceb21b\n ---> f52f38b7823e\nSuccessfully
|
|
built f52f38b7823e\nRemoving intermediate container 9c9e81692ae9\nRemoving intermediate
|
|
container 02071fceb21b\n```\n\nThis example specifies that the `PATH` is `.`, and
|
|
so all the files in the\nlocal directory get `tar`d and sent to the Docker daemon.
|
|
The `PATH` specifies\nwhere to find the files for the \"context\" of the build on
|
|
the Docker daemon.\nRemember that the daemon could be running on a remote machine
|
|
and that no\nparsing of the Dockerfile happens at the client side (where you're
|
|
running\n`docker build`). That means that *all* the files at `PATH` get sent, not
|
|
just\nthe ones listed to [*ADD*](../builder.md#add) in the Dockerfile.\n\nThe transfer
|
|
of context from the local machine to the Docker daemon is what the\n`docker` client
|
|
means when you see the \"Sending build context\" message.\n\nIf you wish to keep
|
|
the intermediate containers after the build is complete,\nyou must use `--rm=false`.
|
|
This does not affect the build cache.\n\n### Build with URL\n\n```bash\n$ docker
|
|
build github.com/creack/docker-firefox\n```\n\nThis will clone the GitHub repository
|
|
and use the cloned repository as context.\nThe Dockerfile at the root of the repository
|
|
is used as Dockerfile. You can\nspecify an arbitrary Git repository by using the
|
|
`git://` or `git@` scheme.\n\n```bash\n$ docker build -f ctx/Dockerfile http://server/ctx.tar.gz\n\nDownloading
|
|
context: http://server/ctx.tar.gz [===================>] 240 B/240 B\nStep 1/3
|
|
: FROM busybox\n ---> 8c2e06607696\nStep 2/3 : ADD ctx/container.cfg /\n ---> e7829950cee3\nRemoving
|
|
intermediate container b35224abf821\nStep 3/3 : CMD /bin/ls\n ---> Running in fbc63d321d73\n
|
|
---> 3286931702ad\nRemoving intermediate container fbc63d321d73\nSuccessfully built
|
|
377c409b35e4\n```\n\nThis sends the URL `http://server/ctx.tar.gz` to the Docker
|
|
daemon, which\ndownloads and extracts the referenced tarball. The `-f ctx/Dockerfile`\nparameter
|
|
specifies a path inside `ctx.tar.gz` to the `Dockerfile` that is used\nto build
|
|
the image. Any `ADD` commands in that `Dockerfile` that refers to local\npaths must
|
|
be relative to the root of the contents inside `ctx.tar.gz`. In the\nexample above,
|
|
the tarball contains a directory `ctx/`, so the `ADD\nctx/container.cfg /` operation
|
|
works as expected.\n\n### Build with -\n\n```bash\n$ docker build - < Dockerfile\n```\n\nThis
|
|
will read a Dockerfile from `STDIN` without context. Due to the lack of a\ncontext,
|
|
no contents of any local directory will be sent to the Docker daemon.\nSince there
|
|
is no context, a Dockerfile `ADD` only works if it refers to a\nremote URL.\n\n```bash\n$
|
|
docker build - < context.tar.gz\n```\n\nThis will build an image for a compressed
|
|
context read from `STDIN`. Supported\nformats are: bzip2, gzip and xz.\n\n### Use
|
|
a .dockerignore file\n\n```bash\n$ docker build .\n\nUploading context 18.829 MB\nUploading
|
|
context\nStep 1/2 : FROM busybox\n ---> 769b9341d937\nStep 2/2 : CMD echo Hello
|
|
world\n ---> Using cache\n ---> 99cc1ad10469\nSuccessfully built 99cc1ad10469\n$
|
|
echo \".git\" > .dockerignore\n$ docker build .\nUploading context 6.76 MB\nUploading
|
|
context\nStep 1/2 : FROM busybox\n ---> 769b9341d937\nStep 2/2 : CMD echo Hello
|
|
world\n ---> Using cache\n ---> 99cc1ad10469\nSuccessfully built 99cc1ad10469\n```\n\nThis
|
|
example shows the use of the `.dockerignore` file to exclude the `.git`\ndirectory
|
|
from the context. Its effect can be seen in the changed size of the\nuploaded context.
|
|
The builder reference contains detailed information on\n[creating a .dockerignore
|
|
file](../builder.md#dockerignore-file)\n\n### Tag an image (-t)\n\n```bash\n$ docker
|
|
build -t vieux/apache:2.0 .\n```\n\nThis will build like the previous example, but
|
|
it will then tag the resulting\nimage. The repository name will be `vieux/apache`
|
|
and the tag will be `2.0`.\n[Read more about valid tags](tag.md).\n\nYou can apply
|
|
multiple tags to an image. For example, you can apply the `latest`\ntag to a newly
|
|
built image and add another tag that references a specific\nversion.\nFor example,
|
|
to tag an image both as `whenry/fedora-jboss:latest` and\n`whenry/fedora-jboss:v2.1`,
|
|
use the following:\n\n```bash\n$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1
|
|
.\n```\n\n### Specify a Dockerfile (-f)\n\n```bash\n$ docker build -f Dockerfile.debug
|
|
.\n```\n\nThis will use a file called `Dockerfile.debug` for the build instructions\ninstead
|
|
of `Dockerfile`.\n\n```bash\n$ curl example.com/remote/Dockerfile | docker build
|
|
-f - .\n```\n\nThe above command will use the current directory as the build context
|
|
and read\na Dockerfile from stdin.\n\n```bash\n$ docker build -f dockerfiles/Dockerfile.debug
|
|
-t myapp_debug .\n$ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod .\n```\n\nThe
|
|
above commands will build the current build context (as specified by the\n`.`) twice,
|
|
once using a debug version of a `Dockerfile` and once using a\nproduction version.\n\n```bash\n$
|
|
cd /home/me/myapp/some/dir/really/deep\n$ docker build -f /home/me/myapp/dockerfiles/debug
|
|
/home/me/myapp\n$ docker build -f ../../../../dockerfiles/debug /home/me/myapp\n```\n\nThese
|
|
two `docker build` commands do the exact same thing. They both use the\ncontents
|
|
of the `debug` file instead of looking for a `Dockerfile` and will use\n`/home/me/myapp`
|
|
as the root of the build context. Note that `debug` is in the\ndirectory structure
|
|
of the build context, regardless of how you refer to it on\nthe command line.\n\n>
|
|
**Note:**\n> `docker build` will return a `no such file or directory` error if the\n>
|
|
file or directory does not exist in the uploaded context. This may\n> happen if
|
|
there is no context, or if you specify a file that is\n> elsewhere on the Host system.
|
|
The context is limited to the current\n> directory (and its children) for security
|
|
reasons, and to ensure\n> repeatable builds on remote Docker hosts. This is also
|
|
the reason why\n> `ADD ../file` will not work.\n\n### Use a custom parent cgroup
|
|
(--cgroup-parent)\n\nWhen `docker build` is run with the `--cgroup-parent` option
|
|
the containers\nused in the build will be run with the [corresponding `docker run`\nflag](../run.md#specifying-custom-cgroups).\n\n###
|
|
Set ulimits in container (--ulimit)\n\nUsing the `--ulimit` option with `docker
|
|
build` will cause each build step's\ncontainer to be started using those [`--ulimit`\nflag
|
|
values](./run.md#set-ulimits-in-container-ulimit).\n\n### Set build-time variables
|
|
(--build-arg)\n\nYou can use `ENV` instructions in a Dockerfile to define variable\nvalues.
|
|
These values persist in the built image. However, often\npersistence is not what
|
|
you want. Users want to specify variables differently\ndepending on which host they
|
|
build an image on.\n\nA good example is `http_proxy` or source versions for pulling
|
|
intermediate\nfiles. The `ARG` instruction lets Dockerfile authors define values
|
|
that users\ncan set at build-time using the `--build-arg` flag:\n\n```bash\n$ docker
|
|
build --build-arg HTTP_PROXY=http://10.20.30.2:1234 .\n```\n\nThis flag allows you
|
|
to pass the build-time variables that are\naccessed like regular environment variables
|
|
in the `RUN` instruction of the\nDockerfile. Also, these values don't persist in
|
|
the intermediate or final images\nlike `ENV` values do.\n\nUsing this flag will
|
|
not alter the output you see when the `ARG` lines from the\nDockerfile are echoed
|
|
during the build process.\n\nFor detailed information on using `ARG` and `ENV` instructions,
|
|
see the\n[Dockerfile reference](../builder.md).\n\n### Optional security options
|
|
(--security-opt)\n\nThis flag is only supported on a daemon running on Windows,
|
|
and only supports\nthe `credentialspec` option. The `credentialspec` must be in
|
|
the format\n`file://spec.txt` or `registry://keyname`.\n\n### Specify isolation
|
|
technology for container (--isolation)\n\nThis option is useful in situations where
|
|
you are running Docker containers on\nWindows. The `--isolation=<value>` option
|
|
sets a container's isolation\ntechnology. On Linux, the only supported is the `default`
|
|
option which uses\nLinux namespaces. On Microsoft Windows, you can specify these
|
|
values:\n\n\n| Value | Description |\n|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|\n|
|
|
`default` | Use the value specified by the Docker daemon's `--exec-opt` . If the
|
|
`daemon` does not specify an isolation technology, Microsoft Windows uses `process`
|
|
as its default value. |\n| `process` | Namespace isolation only. |\n|
|
|
`hyperv` | Hyper-V hypervisor partition-based isolation. |\n\nSpecifying
|
|
the `--isolation` flag without a value is the same as setting `--isolation=\"default\"`.\n\n###
|
|
Add entries to container hosts file (--add-host)\n\nYou can add other hosts into
|
|
a container's `/etc/hosts` file by using one or\nmore `--add-host` flags. This example
|
|
adds a static address for a host named\n`docker`:\n\n $ docker build --add-host=docker:10.180.0.1
|
|
.\n\n### Specifying target build stage (--target)\n\nWhen building a Dockerfile
|
|
with multiple build stages, `--target` can be used to\nspecify an intermediate build
|
|
stage by name as a final stage for the resulting\nimage. Commands after the target
|
|
stage will be skipped.\n\n```Dockerfile\nFROM debian AS build-env\n...\n\nFROM alpine
|
|
AS production-env\n...\n```\n\n```bash\n$ docker build -t mybuildimage --target
|
|
build-env .\n```\n\n### Squash an image's layers (--squash) **Experimental Only**\n\n####
|
|
Overview\n\nOnce the image is built, squash the new layers into a new image with
|
|
a single\nnew layer. Squashing does not destroy any existing image, rather it creates
|
|
a new\nimage with the content of the squashed layers. This effectively makes it
|
|
look\nlike all `Dockerfile` commands were created with a single layer. The build\ncache
|
|
is preserved with this method.\n\n**Note**: using this option means the new image
|
|
will not be able to take\nadvantage of layer sharing with other images and may use
|
|
significantly more\nspace.\n\n**Note**: using this option you may see significantly
|
|
more space used due to\nstoring two copies of the image, one for the build cache
|
|
with all the cache\nlayers in tact, and one for the squashed version.\n\n#### Prerequisites\n\nThe
|
|
example on this page is using experimental mode in Docker 1.13.\n\nExperimental
|
|
mode can be enabled by using the `--experimental` flag when starting the Docker
|
|
daemon or setting `experimental: true` in the `daemon.json` configuration file.\n\nBy
|
|
default, experimental mode is disabled. To see the current configuration, use the
|
|
`docker version` command.\n\n```none\n\nServer:\n Version: 1.13.1\n API version:
|
|
\ 1.26 (minimum version 1.12)\n Go version: go1.7.5\n Git commit: 092cba3\n
|
|
Built: Wed Feb 8 06:35:24 2017\n OS/Arch: linux/amd64\n Experimental:
|
|
false\n\n [...]\n\n```\n\nTo enable experimental mode, users need to restart the
|
|
docker daemon with the experimental flag enabled.\n\n#### Enable Docker experimental\n\nExperimental
|
|
features are now included in the standard Docker binaries as of version 1.13.0.
|
|
For enabling experimental features, you need to start the Docker daemon with `--experimental`
|
|
flag. You can also enable the daemon flag via /etc/docker/daemon.json. e.g.\n\n```\n\n{\n
|
|
\ \"experimental\": true\n}\n\n```\nThen make sure the experimental flag is enabled:\n\n```bash\n\n$
|
|
docker version -f '{{.Server.Experimental}}'\ntrue\n\n```\n\n#### Build an image
|
|
with `--squash` argument\n\nThe following is an example of docker build with `--squash`
|
|
argument\n\n```Dockerfile\n\nFROM busybox\nRUN echo hello > /hello\nRUN echo world
|
|
>> /hello\nRUN touch remove_me /remove_me\nENV HELLO world\nRUN rm /remove_me\n\n```\nAn
|
|
image named `test` is built with `--squash` argument.\n\n```bash\n\n$ docker build
|
|
--squash -t test .\n\n[...]\n\n```\n\nIf everything is right, the history will look
|
|
like this:\n\n```bash\n$ docker history test \n\nIMAGE CREATED CREATED
|
|
BY SIZE COMMENT\n4e10cb5b4cac
|
|
\ 3 seconds ago 12 B
|
|
\ merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702
|
|
to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb\n<missing>
|
|
\ 5 minutes ago /bin/sh -c rm /remove_me 0
|
|
B\n<missing> 5 minutes ago /bin/sh -c #(nop) ENV HELLO=world 0
|
|
B\n<missing> 5 minutes ago /bin/sh -c touch remove_me /remove_me
|
|
\ 0 B\n<missing> 5 minutes ago /bin/sh -c echo world >>
|
|
/hello 0 B\n<missing> 6 minutes ago /bin/sh -c echo
|
|
hello > /hello 0 B\n<missing> 7 weeks ago /bin/sh
|
|
-c #(nop) CMD [\"sh\"] 0 B\n<missing> 7 weeks ago /bin/sh
|
|
-c #(nop) ADD file:47ca6e777c36a4cfff 1.113 MB\n\n```\nWe could find that all
|
|
layer's name is `<missing>`, and there is a new layer with COMMENT `merge`.\n\nTest
|
|
the image, check for `/remove_me` being gone, make sure `hello\\nworld` is in `/hello`,
|
|
make sure the `HELLO` envvar's value is `world`."
|
|
|