docs: add code-hints to builder page
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn
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
|
||||
`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
|
||||
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`
|
||||
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
|
||||
```bash
|
||||
$ docker build - < Dockerfile
|
||||
```
|
||||
|
||||
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
|
||||
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
|
||||
`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
|
||||
```bash
|
||||
$ 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:
|
||||
|
||||
|
|
@ -140,31 +149,34 @@ See also:
|
|||
|
||||
### Build with PATH
|
||||
|
||||
$ 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
|
||||
```bash
|
||||
$ 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
|
||||
|
|
@ -182,7 +194,9 @@ you must use `--rm=false`. This does not affect the build cache.
|
|||
|
||||
### 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.
|
||||
The Dockerfile at the root of the repository is used as Dockerfile. Note that
|
||||
|
|
@ -191,39 +205,46 @@ scheme.
|
|||
|
||||
### Build with -
|
||||
|
||||
$ docker build - < Dockerfile
|
||||
```bash
|
||||
$ 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
|
||||
```bash
|
||||
$ docker build - < context.tar.gz
|
||||
```
|
||||
|
||||
This will build an image for a compressed context read from `STDIN`. Supported
|
||||
formats are: bzip2, gzip and xz.
|
||||
|
||||
### Usage of .dockerignore
|
||||
|
||||
$ 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
|
||||
```bash
|
||||
$ 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
|
||||
|
|
@ -232,7 +253,9 @@ uploaded context. The builder reference contains detailed information on
|
|||
|
||||
### 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
|
||||
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
|
||||
`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)
|
||||
|
||||
$ docker build -f Dockerfile.debug .
|
||||
```bash
|
||||
$ 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 .
|
||||
```bash
|
||||
$ 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
|
||||
```bash
|
||||
$ 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
|
||||
|
|
@ -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
|
||||
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
|
||||
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. |
|
||||
| `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"`.
|
||||
|
|
|
|||
Loading…
Reference in a new issue