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

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

@ -65,13 +65,15 @@ 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` | `/`
@ -85,11 +87,15 @@ Build Syntax Suffix | Commit Used | Build Context Used
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
Sending build context to Docker daemon
Step 1 : FROM busybox
---> 4986bf8c1536 ---> 4986bf8c1536
Step 2 : RUN exit 13 Step 2 : RUN exit 13
---> Running in e26670ec7a0a ---> Running in e26670ec7a0a
INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13 INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13
$ echo $? $ echo $?
1 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
Step 1 : FROM busybox
Pulling repository busybox
---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/ ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/
Step 2 : RUN ls -lh / Step 2 : RUN ls -lh /
---> Running in 9c9e81692ae9 ---> Running in 9c9e81692ae9
total 24 total 24
drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin 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 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 Oct 19 00:19 etc
drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib
lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib
dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc
lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin
dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys 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 Mar 12 2013 tmp
drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr
---> b35f4035db3f ---> b35f4035db3f
Step 3 : CMD echo Hello world Step 3 : CMD echo Hello world
---> Running in 02071fceb21b ---> Running in 02071fceb21b
---> f52f38b7823e ---> f52f38b7823e
Successfully built f52f38b7823e Successfully built f52f38b7823e
Removing intermediate container 9c9e81692ae9 Removing intermediate container 9c9e81692ae9
Removing intermediate container 02071fceb21b 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
Uploading context
Step 1 : FROM busybox
---> 769b9341d937 ---> 769b9341d937
Step 2 : CMD echo Hello world Step 2 : CMD echo Hello world
---> Using cache ---> Using cache
---> 99cc1ad10469 ---> 99cc1ad10469
Successfully built 99cc1ad10469 Successfully built 99cc1ad10469
$ echo ".git" > .dockerignore $ echo ".git" > .dockerignore
$ docker build . $ docker build .
Uploading context 6.76 MB Uploading context 6.76 MB
Uploading context Uploading context
Step 1 : FROM busybox Step 1 : FROM busybox
---> 769b9341d937 ---> 769b9341d937
Step 2 : CMD echo Hello world Step 2 : CMD echo Hello world
---> Using cache ---> Using cache
---> 99cc1ad10469 ---> 99cc1ad10469
Successfully built 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