mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
docs: add code-hints to builder page
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
parent
eb897f490e
commit
b5503ef0a5
1 changed files with 114 additions and 82 deletions
|
@ -65,31 +65,37 @@ 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
|
For example, run this command to use a directory called `docker` in the branch
|
||||||
`container`:
|
`container`:
|
||||||
|
|
||||||
$ docker build https://github.com/docker/rootfs.git#container:docker
|
```bash
|
||||||
|
$ docker build https://github.com/docker/rootfs.git#container:docker
|
||||||
|
```
|
||||||
|
|
||||||
The following table represents all the valid suffixes with their build
|
The following table represents all the valid suffixes with their build
|
||||||
contexts:
|
contexts:
|
||||||
|
|
||||||
Build Syntax Suffix | Commit Used | Build Context Used
|
Build Syntax Suffix | Commit Used | Build Context Used
|
||||||
--------------------|-------------|-------------------
|
--------------------------------|-----------------------|-------------------
|
||||||
`myrepo.git` | `refs/heads/master` | `/`
|
`myrepo.git` | `refs/heads/master` | `/`
|
||||||
`myrepo.git#mytag` | `refs/tags/mytag` | `/`
|
`myrepo.git#mytag` | `refs/tags/mytag` | `/`
|
||||||
`myrepo.git#mybranch` | `refs/heads/mybranch` | `/`
|
`myrepo.git#mybranch` | `refs/heads/mybranch` | `/`
|
||||||
`myrepo.git#abcdef` | `sha1 = abcdef` | `/`
|
`myrepo.git#abcdef` | `sha1 = abcdef` | `/`
|
||||||
`myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder`
|
`myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder`
|
||||||
`myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder`
|
`myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder`
|
||||||
`myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder`
|
`myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder`
|
||||||
`myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder`
|
`myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder`
|
||||||
`myrepo.git#abcdef:myfolder` | `sha1 = abcdef` | `/myfolder`
|
`myrepo.git#abcdef:myfolder` | `sha1 = abcdef` | `/myfolder`
|
||||||
|
|
||||||
Instead of specifying a context, you can pass a single Dockerfile in the `URL`
|
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`:
|
or pipe the file in via `STDIN`. To pipe a Dockerfile from `STDIN`:
|
||||||
|
|
||||||
$ docker build - < Dockerfile
|
```bash
|
||||||
|
$ docker build - < Dockerfile
|
||||||
|
```
|
||||||
|
|
||||||
With Powershell on Windows, you can run:
|
With Powershell on Windows, you can run:
|
||||||
|
|
||||||
Get-Content Dockerfile | docker build -
|
```powershell
|
||||||
|
Get-Content Dockerfile | docker build -
|
||||||
|
```
|
||||||
|
|
||||||
If you use STDIN or specify a `URL`, the system places the contents into a file
|
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
|
called `Dockerfile`, and any `-f`, `--file` option is ignored. In this
|
||||||
|
@ -121,16 +127,19 @@ build fails, a non-zero failure code will be returned.
|
||||||
There should be informational output of the reason for failure output to
|
There should be informational output of the reason for failure output to
|
||||||
`STDERR`:
|
`STDERR`:
|
||||||
|
|
||||||
$ docker build -t fail .
|
```bash
|
||||||
Sending build context to Docker daemon 2.048 kB
|
$ docker build -t fail .
|
||||||
Sending build context to Docker daemon
|
|
||||||
Step 1 : FROM busybox
|
Sending build context to Docker daemon 2.048 kB
|
||||||
---> 4986bf8c1536
|
Sending build context to Docker daemon
|
||||||
Step 2 : RUN exit 13
|
Step 1 : FROM busybox
|
||||||
---> Running in e26670ec7a0a
|
---> 4986bf8c1536
|
||||||
INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13
|
Step 2 : RUN exit 13
|
||||||
$ echo $?
|
---> Running in e26670ec7a0a
|
||||||
1
|
INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13
|
||||||
|
$ echo $?
|
||||||
|
1
|
||||||
|
```
|
||||||
|
|
||||||
See also:
|
See also:
|
||||||
|
|
||||||
|
@ -140,31 +149,34 @@ See also:
|
||||||
|
|
||||||
### Build with PATH
|
### Build with PATH
|
||||||
|
|
||||||
$ docker build .
|
```bash
|
||||||
Uploading context 10240 bytes
|
$ docker build .
|
||||||
Step 1 : FROM busybox
|
|
||||||
Pulling repository busybox
|
Uploading context 10240 bytes
|
||||||
---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/
|
Step 1 : FROM busybox
|
||||||
Step 2 : RUN ls -lh /
|
Pulling repository busybox
|
||||||
---> Running in 9c9e81692ae9
|
---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/
|
||||||
total 24
|
Step 2 : RUN ls -lh /
|
||||||
drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin
|
---> Running in 9c9e81692ae9
|
||||||
drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev
|
total 24
|
||||||
drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc
|
drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin
|
||||||
drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib
|
drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev
|
||||||
lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib
|
drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc
|
||||||
dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc
|
drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib
|
||||||
lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin
|
lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib
|
||||||
dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys
|
dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc
|
||||||
drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp
|
lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin
|
||||||
drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr
|
dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys
|
||||||
---> b35f4035db3f
|
drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp
|
||||||
Step 3 : CMD echo Hello world
|
drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr
|
||||||
---> Running in 02071fceb21b
|
---> b35f4035db3f
|
||||||
---> f52f38b7823e
|
Step 3 : CMD echo Hello world
|
||||||
Successfully built f52f38b7823e
|
---> Running in 02071fceb21b
|
||||||
Removing intermediate container 9c9e81692ae9
|
---> f52f38b7823e
|
||||||
Removing intermediate container 02071fceb21b
|
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
|
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
|
local directory get `tar`d and sent to the Docker daemon. The `PATH` specifies
|
||||||
|
@ -182,7 +194,9 @@ you must use `--rm=false`. This does not affect the build cache.
|
||||||
|
|
||||||
### Build with URL
|
### Build with URL
|
||||||
|
|
||||||
$ docker build github.com/creack/docker-firefox
|
```bash
|
||||||
|
$ docker build github.com/creack/docker-firefox
|
||||||
|
```
|
||||||
|
|
||||||
This will clone the GitHub repository and use the cloned repository as context.
|
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
|
The Dockerfile at the root of the repository is used as Dockerfile. Note that
|
||||||
|
@ -191,39 +205,46 @@ scheme.
|
||||||
|
|
||||||
### Build with -
|
### Build with -
|
||||||
|
|
||||||
$ docker build - < Dockerfile
|
```bash
|
||||||
|
$ docker build - < Dockerfile
|
||||||
|
```
|
||||||
|
|
||||||
This will read a Dockerfile from `STDIN` without context. Due to the lack of a
|
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.
|
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
|
Since there is no context, a Dockerfile `ADD` only works if it refers to a
|
||||||
remote URL.
|
remote URL.
|
||||||
|
|
||||||
$ docker build - < context.tar.gz
|
```bash
|
||||||
|
$ docker build - < context.tar.gz
|
||||||
|
```
|
||||||
|
|
||||||
This will build an image for a compressed context read from `STDIN`. Supported
|
This will build an image for a compressed context read from `STDIN`. Supported
|
||||||
formats are: bzip2, gzip and xz.
|
formats are: bzip2, gzip and xz.
|
||||||
|
|
||||||
### Usage of .dockerignore
|
### Usage of .dockerignore
|
||||||
|
|
||||||
$ docker build .
|
```bash
|
||||||
Uploading context 18.829 MB
|
$ docker build .
|
||||||
Uploading context
|
|
||||||
Step 1 : FROM busybox
|
Uploading context 18.829 MB
|
||||||
---> 769b9341d937
|
Uploading context
|
||||||
Step 2 : CMD echo Hello world
|
Step 1 : FROM busybox
|
||||||
---> Using cache
|
---> 769b9341d937
|
||||||
---> 99cc1ad10469
|
Step 2 : CMD echo Hello world
|
||||||
Successfully built 99cc1ad10469
|
---> Using cache
|
||||||
$ echo ".git" > .dockerignore
|
---> 99cc1ad10469
|
||||||
$ docker build .
|
Successfully built 99cc1ad10469
|
||||||
Uploading context 6.76 MB
|
$ echo ".git" > .dockerignore
|
||||||
Uploading context
|
$ docker build .
|
||||||
Step 1 : FROM busybox
|
Uploading context 6.76 MB
|
||||||
---> 769b9341d937
|
Uploading context
|
||||||
Step 2 : CMD echo Hello world
|
Step 1 : FROM busybox
|
||||||
---> Using cache
|
---> 769b9341d937
|
||||||
---> 99cc1ad10469
|
Step 2 : CMD echo Hello world
|
||||||
Successfully built 99cc1ad10469
|
---> Using cache
|
||||||
|
---> 99cc1ad10469
|
||||||
|
Successfully built 99cc1ad10469
|
||||||
|
```
|
||||||
|
|
||||||
This example shows the use of the `.dockerignore` file to exclude the `.git`
|
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
|
directory from the context. Its effect can be seen in the changed size of the
|
||||||
|
@ -232,7 +253,9 @@ uploaded context. The builder reference contains detailed information on
|
||||||
|
|
||||||
### Tag image (-t)
|
### Tag image (-t)
|
||||||
|
|
||||||
$ docker build -t vieux/apache:2.0 .
|
```bash
|
||||||
|
$ docker build -t vieux/apache:2.0 .
|
||||||
|
```
|
||||||
|
|
||||||
This will build like the previous example, but it will then tag the resulting
|
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`.
|
image. The repository name will be `vieux/apache` and the tag will be `2.0`.
|
||||||
|
@ -244,25 +267,32 @@ version.
|
||||||
For example, to tag an image both as `whenry/fedora-jboss:latest` and
|
For example, to tag an image both as `whenry/fedora-jboss:latest` and
|
||||||
`whenry/fedora-jboss:v2.1`, use the following:
|
`whenry/fedora-jboss:v2.1`, use the following:
|
||||||
|
|
||||||
$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .
|
```bash
|
||||||
|
$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .
|
||||||
|
```
|
||||||
### Specify Dockerfile (-f)
|
### Specify Dockerfile (-f)
|
||||||
|
|
||||||
$ docker build -f Dockerfile.debug .
|
```bash
|
||||||
|
$ docker build -f Dockerfile.debug .
|
||||||
|
```
|
||||||
|
|
||||||
This will use a file called `Dockerfile.debug` for the build instructions
|
This will use a file called `Dockerfile.debug` for the build instructions
|
||||||
instead of `Dockerfile`.
|
instead of `Dockerfile`.
|
||||||
|
|
||||||
$ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug .
|
```bash
|
||||||
$ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod .
|
$ 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
|
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
|
`.`) twice, once using a debug version of a `Dockerfile` and once using a
|
||||||
production version.
|
production version.
|
||||||
|
|
||||||
$ cd /home/me/myapp/some/dir/really/deep
|
```bash
|
||||||
$ docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp
|
$ cd /home/me/myapp/some/dir/really/deep
|
||||||
$ docker build -f ../../../../dockerfiles/debug /home/me/myapp
|
$ 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
|
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
|
contents of the `debug` file instead of looking for a `Dockerfile` and will use
|
||||||
|
@ -302,7 +332,9 @@ A good example is `http_proxy` or source versions for pulling intermediate
|
||||||
files. The `ARG` instruction lets Dockerfile authors define values that users
|
files. The `ARG` instruction lets Dockerfile authors define values that users
|
||||||
can set at build-time using the `--build-arg` flag:
|
can set at build-time using the `--build-arg` flag:
|
||||||
|
|
||||||
$ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 .
|
```bash
|
||||||
|
$ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 .
|
||||||
|
```
|
||||||
|
|
||||||
This flag allows you to pass the build-time variables that are
|
This flag allows you to pass the build-time variables that are
|
||||||
accessed like regular environment variables in the `RUN` instruction of the
|
accessed like regular environment variables in the `RUN` instruction of the
|
||||||
|
@ -327,6 +359,6 @@ Linux namespaces. On Microsoft Windows, you can specify these values:
|
||||||
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
| `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. |
|
| `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. |
|
||||||
| `process` | Namespace isolation only. |
|
| `process` | Namespace isolation only. |
|
||||||
| `hyperv` | Hyper-V hypervisor partition-based isolation. |
|
| `hyperv` | Hyper-V hypervisor partition-based isolation. |
|
||||||
|
|
||||||
Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
|
Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
|
||||||
|
|
Loading…
Reference in a new issue