Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: add code-hints to builder page 

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2016-07-20 16:18:44 +02:00 committed by Tibor Vass
parent c8dd8fe523
commit 7a206d8667
1 changed files with 114 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
docs/reference/commandline/build.md
View File

@ -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"`.