From b5503ef0a511f5be11d9dcfa1359976f159d8a67 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 20 Jul 2016 16:18:44 +0200 Subject: [PATCH] docs: add code-hints to builder page Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/build.md | 196 ++++++++++++++++------------ 1 file changed, 114 insertions(+), 82 deletions(-) diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md index 00fd85d61f..e1e007dcf1 100644 --- a/docs/reference/commandline/build.md +++ b/docs/reference/commandline/build.md @@ -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"`.