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

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
`container`:
```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` | `/`
@ -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`
or pipe the file in via `STDIN`. To pipe a Dockerfile from `STDIN`:
```bash
$ docker build - < Dockerfile
```
With Powershell on Windows, you can run:
```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,7 +127,9 @@ build fails, a non-zero failure code will be returned.
There should be informational output of the reason for failure output to
`STDERR`:
```bash
$ docker build -t fail .
Sending build context to Docker daemon 2.048 kB
Sending build context to Docker daemon
Step 1 : FROM busybox
@ -131,6 +139,7 @@ There should be informational output of the reason for failure output to
INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13
$ echo $?
1
```
See also:
@ -140,7 +149,9 @@ See also:
### Build with PATH
```bash
$ docker build .
Uploading context 10240 bytes
Step 1 : FROM busybox
Pulling repository busybox
@ -165,6 +176,7 @@ See also:
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
```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,21 +205,27 @@ scheme.
### Build with -
```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.
```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
```bash
$ docker build .
Uploading context 18.829 MB
Uploading context
Step 1 : FROM busybox
@ -224,6 +244,7 @@ formats are: bzip2, gzip and xz.
---> 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)
```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:
```bash
$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .
```
### Specify Dockerfile (-f)
```bash
$ docker build -f Dockerfile.debug .
```
This will use a file called `Dockerfile.debug` for the build instructions
instead of `Dockerfile`.
```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.
```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:
```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