From 1302228707d71d1d7674e582aee04c2292d283ec Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Mon, 17 Apr 2017 17:34:02 -0400 Subject: [PATCH 001/152] init Signed-off-by: Daniel Nephin From e593e948f11728b7ae2fc439a0abb8eb4bfdc9c5 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Sun, 7 Jun 2015 20:07:20 -0700 Subject: [PATCH 002/152] retooling for hugo Tweaking for Hugo Updating the Dockerfile with new sed; fix broken link on Kitematic Fixing image pull for Dockerfile Removing docs targets Signed-off-by: Mary Anthony --- frontend/dockerfile/docs/reference.md | 1050 +++++++++++++++++++++++++ 1 file changed, 1050 insertions(+) create mode 100644 frontend/dockerfile/docs/reference.md diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md new file mode 100644 index 000000000..89b760265 --- /dev/null +++ b/frontend/dockerfile/docs/reference.md @@ -0,0 +1,1050 @@ + + +# Dockerfile reference + +**Docker can build images automatically** by reading the instructions +from a `Dockerfile`. A `Dockerfile` is a text document that contains all +the commands you would normally execute manually in order to build a +Docker image. By calling `docker build` from your terminal, you can have +Docker build your image step by step, executing the instructions +successively. + +This page discusses the specifics of all the instructions you can use in your +`Dockerfile`. To further help you write a clear, readable, maintainable +`Dockerfile`, we've also written a [`Dockerfile` Best Practices +guide](/articles/dockerfile_best-practices). Lastly, you can test your +Dockerfile knowledge with the [Dockerfile tutorial](/userguide/level1). + +## Usage + +To [*build*](/reference/commandline/cli/#build) an image from a source repository, +create a description file called `Dockerfile` at the root of your repository. +This file will describe the steps to assemble the image. + +Then call `docker build` with the path of your source repository as the argument +(for example, `.`): + + $ docker build . + +The path to the source repository defines where to find the *context* of +the build. The build is run by the Docker daemon, not by the CLI, so the +whole context must be transferred to the daemon. The Docker CLI reports +"Sending build context to Docker daemon" when the context is sent to the daemon. + +> **Warning** +> Avoid using your root directory, `/`, as the root of the source repository. The +> `docker build` command will use whatever directory contains the Dockerfile as the build +> context (including all of its subdirectories). The build context will be sent to the +> Docker daemon before building the image, which means if you use `/` as the source +> repository, the entire contents of your hard drive will get sent to the daemon (and +> thus to the machine running the daemon). You probably don't want that. + +In most cases, it's best to put each Dockerfile in an empty directory. Then, +only add the files needed for building the Dockerfile to the directory. To +increase the build's performance, you can exclude files and directories by +adding a `.dockerignore` file to the directory. For information about how to +[create a `.dockerignore` file](#the-dockerignore-file) on this page. + +You can specify a repository and tag at which to save the new image if +the build succeeds: + + $ docker build -t shykes/myapp . + +The Docker daemon will run your steps one-by-one, committing the result +to a new image if necessary, before finally outputting the ID of your +new image. The Docker daemon will automatically clean up the context you +sent. + +Note that each instruction is run independently, and causes a new image +to be created - so `RUN cd /tmp` will not have any effect on the next +instructions. + +Whenever possible, Docker will re-use the intermediate images, +accelerating `docker build` significantly (indicated by `Using cache` - +see the [`Dockerfile` Best Practices +guide](/articles/dockerfile_best-practices/#build-cache) for more information): + + $ docker build -t SvenDowideit/ambassador . + Uploading context 10.24 kB + Uploading context + Step 1 : FROM docker-ut + ---> cbba202fe96b + Step 2 : MAINTAINER SvenDowideit@home.org.au + ---> Using cache + ---> 51182097be13 + Step 3 : CMD env | grep _TCP= | sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' | sh && top + ---> Using cache + ---> 1a5ffc17324d + Successfully built 1a5ffc17324d + +When you're done with your build, you're ready to look into [*Pushing a +repository to its registry*]( /userguide/dockerrepos/#contributing-to-docker-hub). + +## Format + +Here is the format of the `Dockerfile`: + + # Comment + INSTRUCTION arguments + +The Instruction is not case-sensitive, however convention is for them to +be UPPERCASE in order to distinguish them from arguments more easily. + +Docker runs the instructions in a `Dockerfile` in order. **The +first instruction must be \`FROM\`** in order to specify the [*Base +Image*](/terms/image/#base-image) from which you are building. + +Docker will treat lines that *begin* with `#` as a +comment. A `#` marker anywhere else in the line will +be treated as an argument. This allows statements like: + + # Comment + RUN echo 'we are running some # of cool things' + +Here is the set of instructions you can use in a `Dockerfile` for building +images. + +### Environment replacement + +> **Note**: prior to 1.3, `Dockerfile` environment variables were handled +> similarly, in that they would be replaced as described below. However, there +> was no formal definition on as to which instructions handled environment +> replacement at the time. After 1.3 this behavior will be preserved and +> canonical. + +Environment variables (declared with [the `ENV` statement](#env)) can also be +used in certain instructions as variables to be interpreted by the +`Dockerfile`. Escapes are also handled for including variable-like syntax +into a statement literally. + +Environment variables are notated in the `Dockerfile` either with +`$variable_name` or `${variable_name}`. They are treated equivalently and the +brace syntax is typically used to address issues with variable names with no +whitespace, like `${foo}_bar`. + +The `${variable_name}` syntax also supports a few of the standard `bash` +modifiers as specified below: + +* `${variable:-word}` indicates that if `variable` is set then the result + will be that value. If `variable` is not set then `word` will be the result. +* `${variable:+word}` indicates that if `variable` is set then `word` will be + the result, otherwise the result is the empty string. + +In all cases, `word` can be any string, including additional environment +variables. + +Escaping is possible by adding a `\` before the variable: `\$foo` or `\${foo}`, +for example, will translate to `$foo` and `${foo}` literals respectively. + +Example (parsed representation is displayed after the `#`): + + FROM busybox + ENV foo /bar + WORKDIR ${foo} # WORKDIR /bar + ADD . $foo # ADD . /bar + COPY \$foo /quux # COPY $foo /quux + +The instructions that handle environment variables in the `Dockerfile` are: + +* `ENV` +* `ADD` +* `COPY` +* `WORKDIR` +* `EXPOSE` +* `VOLUME` +* `USER` + +`ONBUILD` instructions are **NOT** supported for environment replacement, even +the instructions above. + +Environment variable substitution will use the same value for each variable +throughout the entire command. In other words, in this example: + + ENV abc=hello + ENV abc=bye def=$abc + ENV ghi=$abc + +will result in `def` having a value of `hello`, not `bye`. However, +`ghi` will have a value of `bye` because it is not part of the same command +that set `abc` to `bye`. + +### .dockerignore file + +If a file named `.dockerignore` exists in the root of `PATH`, then Docker +interprets it as a newline-separated list of exclusion patterns. Docker excludes +files or directories relative to `PATH` that match these exclusion patterns. If +there are any `.dockerignore` files in `PATH` subdirectories, Docker treats +them as normal files. + +Filepaths in `.dockerignore` are absolute with the current directory as the +root. Wildcards are allowed but the search is not recursive. Globbing (file name +expansion) is done using Go's +[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. + +You can specify exceptions to exclusion rules. To do this, simply prefix a +pattern with an `!` (exclamation mark) in the same way you would in a +`.gitignore` file. Currently there is no support for regular expressions. +Formats like `[^temp*]` are ignored. + +The following is an example `.dockerignore` file: + +``` + */temp* + */*/temp* + temp? + *.md + !LICENCSE.md +``` + +This file causes the following build behavior: + +| Rule | Behavior | +|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `*/temp*` | Exclude all files with names starting with`temp` in any subdirectory below the root directory. For example, a file named`/somedir/temporary.txt` is ignored. | +| `*/*/temp*` | Exclude files starting with name `temp` from any subdirectory that is two levels below the root directory. For example, the file `/somedir/subdir/temporary.txt` is ignored. | +| `temp?` | Exclude the files that match the pattern in the root directory. For example, the files `tempa`, `tempb` in the root directory are ignored. | +| `*.md ` | Exclude all markdown files. | +| `!LICENSE.md` | Exception to the exclude all Markdown files is this file, `LICENSE.md`, include this file in the build. | + +The placement of `!` exception rules influences the matching algorithm; the +last line of the `.dockerignore` that matches a particular file determines +whether it is included or excluded. In the above example, the `LICENSE.md` file +matches both the `*.md` and `!LICENSE.md` rule. If you reverse the lines in the +example: + +``` + */temp* + */*/temp* + temp? + !LICENCSE.md + *.md +``` + +The build would exclude `LICENSE.md` because the last `*.md` rule adds all +Markdown files back onto the ignore list. The `!LICENSE.md` rule has no effect +because the subsequent `*.md` rule overrides it. + +You can even use the `.dockerignore` file to ignore the `Dockerfile` and +`.dockerignore` files. This is useful if you are copying files from the root of +the build context into your new container but do not want to include the +`Dockerfile` or `.dockerignore` files (e.g. `ADD . /someDir/`). + + +## FROM + + FROM + +Or + + FROM : + +Or + + FROM @ + +The `FROM` instruction sets the [*Base Image*](/terms/image/#base-image) +for subsequent instructions. As such, a valid `Dockerfile` must have `FROM` as +its first instruction. The image can be any valid image – it is especially easy +to start by **pulling an image** from the [*Public Repositories*]( +/userguide/dockerrepos). + +`FROM` must be the first non-comment instruction in the `Dockerfile`. + +`FROM` can appear multiple times within a single `Dockerfile` in order to create +multiple images. Simply make a note of the last image ID output by the commit +before each new `FROM` command. + +The `tag` or `digest` values are optional. If you omit either of them, the builder +assumes a `latest` by default. The builder returns an error if it cannot match +the `tag` value. + +## MAINTAINER + + MAINTAINER + +The `MAINTAINER` instruction allows you to set the *Author* field of the +generated images. + +## RUN + +RUN has 2 forms: + +- `RUN ` (the command is run in a shell - `/bin/sh -c` - *shell* form) +- `RUN ["executable", "param1", "param2"]` (*exec* form) + +The `RUN` instruction will execute any commands in a new layer on top of the +current image and commit the results. The resulting committed image will be +used for the next step in the `Dockerfile`. + +Layering `RUN` instructions and generating commits conforms to the core +concepts of Docker where commits are cheap and containers can be created from +any point in an image's history, much like source control. + +The *exec* form makes it possible to avoid shell string munging, and to `RUN` +commands using a base image that does not contain `/bin/sh`. + +> **Note**: +> To use a different shell, other than '/bin/sh', use the *exec* form +> passing in the desired shell. For example, +> `RUN ["/bin/bash", "-c", "echo hello"]` + +> **Note**: +> The *exec* form is parsed as a JSON array, which means that +> you must use double-quotes (") around words not single-quotes ('). + +> **Note**: +> Unlike the *shell* form, the *exec* form does not invoke a command shell. +> This means that normal shell processing does not happen. For example, +> `RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. +> If you want shell processing then either use the *shell* form or execute +> a shell directly, for example: `RUN [ "sh", "-c", "echo", "$HOME" ]`. + +The cache for `RUN` instructions isn't invalidated automatically during +the next build. The cache for an instruction like +`RUN apt-get dist-upgrade -y` will be reused during the next build. The +cache for `RUN` instructions can be invalidated by using the `--no-cache` +flag, for example `docker build --no-cache`. + +See the [`Dockerfile` Best Practices +guide](/articles/dockerfile_best-practices/#build-cache) for more information. + +The cache for `RUN` instructions can be invalidated by `ADD` instructions. See +[below](#add) for details. + +### Known issues (RUN) + +- [Issue 783](https://github.com/docker/docker/issues/783) is about file + permissions problems that can occur when using the AUFS file system. You + might notice it during an attempt to `rm` a file, for example. + + For systems that have recent aufs version (i.e., `dirperm1` mount option can + be set), docker will attempt to fix the issue automatically by mounting + the layers with `dirperm1` option. More details on `dirperm1` option can be + found at [`aufs` man page](http://aufs.sourceforge.net/aufs3/man.html) + + If your system doesn't have support for `dirperm1`, the issue describes a workaround. + +## CMD + +The `CMD` instruction has three forms: + +- `CMD ["executable","param1","param2"]` (*exec* form, this is the preferred form) +- `CMD ["param1","param2"]` (as *default parameters to ENTRYPOINT*) +- `CMD command param1 param2` (*shell* form) + +There can only be one `CMD` instruction in a `Dockerfile`. If you list more than one `CMD` +then only the last `CMD` will take effect. + +**The main purpose of a `CMD` is to provide defaults for an executing +container.** These defaults can include an executable, or they can omit +the executable, in which case you must specify an `ENTRYPOINT` +instruction as well. + +> **Note**: +> If `CMD` is used to provide default arguments for the `ENTRYPOINT` +> instruction, both the `CMD` and `ENTRYPOINT` instructions should be specified +> with the JSON array format. + +> **Note**: +> The *exec* form is parsed as a JSON array, which means that +> you must use double-quotes (") around words not single-quotes ('). + +> **Note**: +> Unlike the *shell* form, the *exec* form does not invoke a command shell. +> This means that normal shell processing does not happen. For example, +> `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. +> If you want shell processing then either use the *shell* form or execute +> a shell directly, for example: `CMD [ "sh", "-c", "echo", "$HOME" ]`. + +When used in the shell or exec formats, the `CMD` instruction sets the command +to be executed when running the image. + +If you use the *shell* form of the `CMD`, then the `` will execute in +`/bin/sh -c`: + + FROM ubuntu + CMD echo "This is a test." | wc - + +If you want to **run your** `` **without a shell** then you must +express the command as a JSON array and give the full path to the executable. +**This array form is the preferred format of `CMD`.** Any additional parameters +must be individually expressed as strings in the array: + + FROM ubuntu + CMD ["/usr/bin/wc","--help"] + +If you would like your container to run the same executable every time, then +you should consider using `ENTRYPOINT` in combination with `CMD`. See +[*ENTRYPOINT*](#entrypoint). + +If the user specifies arguments to `docker run` then they will override the +default specified in `CMD`. + +> **Note**: +> don't confuse `RUN` with `CMD`. `RUN` actually runs a command and commits +> the result; `CMD` does not execute anything at build time, but specifies +> the intended command for the image. + +## LABEL + + LABEL = = = ... + +The `LABEL` instruction adds metadata to an image. A `LABEL` is a +key-value pair. To include spaces within a `LABEL` value, use quotes and +backslashes as you would in command-line parsing. + + LABEL "com.example.vendor"="ACME Incorporated" + +An image can have more than one label. To specify multiple labels, separate each +key-value pair with whitespace. + + LABEL com.example.label-with-value="foo" + LABEL version="1.0" + LABEL description="This text illustrates \ + that label-values can span multiple lines." + +Docker recommends combining labels in a single `LABEL` instruction where +possible. Each `LABEL` instruction produces a new layer which can result in an +inefficient image if you use many labels. This example results in four image +layers. + + LABEL multi.label1="value1" multi.label2="value2" other="value3" + +Labels are additive including `LABEL`s in `FROM` images. As the system +encounters and then applies a new label, new `key`s override any previous labels +with identical keys. + +To view an image's labels, use the `docker inspect` command. + + "Labels": { + "com.example.vendor": "ACME Incorporated" + "com.example.label-with-value": "foo", + "version": "1.0", + "description": "This text illustrates that label-values can span multiple lines.", + "multi.label1": "value1", + "multi.label2": "value2", + "other": "value3" + }, + +## EXPOSE + + EXPOSE [...] + +The `EXPOSE` instructions informs Docker that the container will listen on the +specified network ports at runtime. Docker uses this information to interconnect +containers using links (see the [Docker User +Guide](/userguide/dockerlinks)) and to determine which ports to expose to the +host when [using the -P flag](/reference/run/#expose-incoming-ports). + +> **Note**: +> `EXPOSE` doesn't define which ports can be exposed to the host or make ports +> accessible from the host by default. To expose ports to the host, at runtime, +> [use the `-p` flag](/userguide/dockerlinks) or +> [the -P flag](/reference/run/#expose-incoming-ports). + +## ENV + + ENV + ENV = ... + +The `ENV` instruction sets the environment variable `` to the value +``. This value will be in the environment of all "descendent" `Dockerfile` +commands and can be [replaced inline](#environment-replacement) in many as well. + +The `ENV` instruction has two forms. The first form, `ENV `, +will set a single variable to a value. The entire string after the first +space will be treated as the `` - including characters such as +spaces and quotes. + +The second form, `ENV = ...`, allows for multiple variables to +be set at one time. Notice that the second form uses the equals sign (=) +in the syntax, while the first form does not. Like command line parsing, +quotes and backslashes can be used to include spaces within values. + +For example: + + ENV myName="John Doe" myDog=Rex\ The\ Dog \ + myCat=fluffy + +and + + ENV myName John Doe + ENV myDog Rex The Dog + ENV myCat fluffy + +will yield the same net results in the final container, but the first form +does it all in one layer. + +The environment variables set using `ENV` will persist when a container is run +from the resulting image. You can view the values using `docker inspect`, and +change them using `docker run --env =`. + +> **Note**: +> Environment persistence can cause unexpected effects. For example, +> setting `ENV DEBIAN_FRONTEND noninteractive` may confuse apt-get +> users on a Debian-based image. To set a value for a single command, use +> `RUN = `. + +## ADD + +ADD has two forms: + +- `ADD ... ` +- `ADD ["",... ""]` (this form is required for paths containing +whitespace) + +The `ADD` instruction copies new files, directories or remote file URLs from `` +and adds them to the filesystem of the container at the path ``. + +Multiple `` resource may be specified but if they are files or +directories then they must be relative to the source directory that is +being built (the context of the build). + +Each `` may contain wildcards and matching will be done using Go's +[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. +For most command line uses this should act as expected, for example: + + ADD hom* /mydir/ # adds all files starting with "hom" + ADD hom?.txt /mydir/ # ? is replaced with any single character + +The `` is an absolute path, or a path relative to `WORKDIR`, into which +the source will be copied inside the destination container. + + ADD test aDir/ # adds "test" to `WORKDIR`/aDir/ + +All new files and directories are created with a UID and GID of 0. + +In the case where `` is a remote file URL, the destination will +have permissions of 600. If the remote file being retrieved has an HTTP +`Last-Modified` header, the timestamp from that header will be used +to set the `mtime` on the destination file. However, like any other file +processed during an `ADD`, `mtime` will not be included in the determination +of whether or not the file has changed and the cache should be updated. + +> **Note**: +> If you build by passing a `Dockerfile` through STDIN (`docker +> build - < somefile`), there is no build context, so the `Dockerfile` +> can only contain a URL based `ADD` instruction. You can also pass a +> compressed archive through STDIN: (`docker build - < archive.tar.gz`), +> the `Dockerfile` at the root of the archive and the rest of the +> archive will get used at the context of the build. + +> **Note**: +> If your URL files are protected using authentication, you +> will need to use `RUN wget`, `RUN curl` or use another tool from +> within the container as the `ADD` instruction does not support +> authentication. + +> **Note**: +> The first encountered `ADD` instruction will invalidate the cache for all +> following instructions from the Dockerfile if the contents of `` have +> changed. This includes invalidating the cache for `RUN` instructions. +> See the [`Dockerfile` Best Practices +guide](/articles/dockerfile_best-practices/#build-cache) for more information. + + +The copy obeys the following rules: + +- The `` path must be inside the *context* of the build; + you cannot `ADD ../something /something`, because the first step of a + `docker build` is to send the context directory (and subdirectories) to the + docker daemon. + +- If `` is a URL and `` does not end with a trailing slash, then a + file is downloaded from the URL and copied to ``. + +- If `` is a URL and `` does end with a trailing slash, then the + filename is inferred from the URL and the file is downloaded to + `/`. For instance, `ADD http://example.com/foobar /` would + create the file `/foobar`. The URL must have a nontrivial path so that an + appropriate filename can be discovered in this case (`http://example.com` + will not work). + +- If `` is a directory, the entire contents of the directory are copied, + including filesystem metadata. +> **Note**: +> The directory itself is not copied, just its contents. + +- If `` is a *local* tar archive in a recognized compression format + (identity, gzip, bzip2 or xz) then it is unpacked as a directory. Resources + from *remote* URLs are **not** decompressed. When a directory is copied or + unpacked, it has the same behavior as `tar -x`: the result is the union of: + + 1. Whatever existed at the destination path and + 2. The contents of the source tree, with conflicts resolved in favor + of "2." on a file-by-file basis. + +- If `` is any other kind of file, it is copied individually along with + its metadata. In this case, if `` ends with a trailing slash `/`, it + will be considered a directory and the contents of `` will be written + at `/base()`. + +- If multiple `` resources are specified, either directly or due to the + use of a wildcard, then `` must be a directory, and it must end with + a slash `/`. + +- If `` does not end with a trailing slash, it will be considered a + regular file and the contents of `` will be written at ``. + +- If `` doesn't exist, it is created along with all missing directories + in its path. + +## COPY + +COPY has two forms: + +- `COPY ... ` +- `COPY ["",... ""]` (this form is required for paths containing +whitespace) + +The `COPY` instruction copies new files or directories from `` +and adds them to the filesystem of the container at the path ``. + +Multiple `` resource may be specified but they must be relative +to the source directory that is being built (the context of the build). + +Each `` may contain wildcards and matching will be done using Go's +[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. +For most command line uses this should act as expected, for example: + + COPY hom* /mydir/ # adds all files starting with "hom" + COPY hom?.txt /mydir/ # ? is replaced with any single character + +The `` is an absolute path, or a path relative to `WORKDIR`, into which +the source will be copied inside the destination container. + + COPY test aDir/ # adds "test" to `WORKDIR`/aDir/ + +All new files and directories are created with a UID and GID of 0. + +> **Note**: +> If you build using STDIN (`docker build - < somefile`), there is no +> build context, so `COPY` can't be used. + +The copy obeys the following rules: + +- The `` path must be inside the *context* of the build; + you cannot `COPY ../something /something`, because the first step of a + `docker build` is to send the context directory (and subdirectories) to the + docker daemon. + +- If `` is a directory, the entire contents of the directory are copied, + including filesystem metadata. +> **Note**: +> The directory itself is not copied, just its contents. + +- If `` is any other kind of file, it is copied individually along with + its metadata. In this case, if `` ends with a trailing slash `/`, it + will be considered a directory and the contents of `` will be written + at `/base()`. + +- If multiple `` resources are specified, either directly or due to the + use of a wildcard, then `` must be a directory, and it must end with + a slash `/`. + +- If `` does not end with a trailing slash, it will be considered a + regular file and the contents of `` will be written at ``. + +- If `` doesn't exist, it is created along with all missing directories + in its path. + +## ENTRYPOINT + +ENTRYPOINT has two forms: + +- `ENTRYPOINT ["executable", "param1", "param2"]` + (the preferred *exec* form) +- `ENTRYPOINT command param1 param2` + (*shell* form) + +An `ENTRYPOINT` allows you to configure a container that will run as an executable. + +For example, the following will start nginx with its default content, listening +on port 80: + + docker run -i -t --rm -p 80:80 nginx + +Command line arguments to `docker run ` will be appended after all +elements in an *exec* form `ENTRYPOINT`, and will override all elements specified +using `CMD`. +This allows arguments to be passed to the entry point, i.e., `docker run -d` +will pass the `-d` argument to the entry point. +You can override the `ENTRYPOINT` instruction using the `docker run --entrypoint` +flag. + +The *shell* form prevents any `CMD` or `run` command line arguments from being +used, but has the disadvantage that your `ENTRYPOINT` will be started as a +subcommand of `/bin/sh -c`, which does not pass signals. +This means that the executable will not be the container's `PID 1` - and +will _not_ receive Unix signals - so your executable will not receive a +`SIGTERM` from `docker stop `. + +Only the last `ENTRYPOINT` instruction in the `Dockerfile` will have an effect. + +### Exec form ENTRYPOINT example + +You can use the *exec* form of `ENTRYPOINT` to set fairly stable default commands +and arguments and then use either form of `CMD` to set additional defaults that +are more likely to be changed. + + FROM ubuntu + ENTRYPOINT ["top", "-b"] + CMD ["-c"] + +When you run the container, you can see that `top` is the only process: + + $ docker run -it --rm --name test top -H + top - 08:25:00 up 7:27, 0 users, load average: 0.00, 0.01, 0.05 + Threads: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + %Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.7 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st + KiB Mem: 2056668 total, 1616832 used, 439836 free, 99352 buffers + KiB Swap: 1441840 total, 0 used, 1441840 free. 1324440 cached Mem + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 19744 2336 2080 R 0.0 0.1 0:00.04 top + +To examine the result further, you can use `docker exec`: + + $ docker exec -it test ps aux + USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND + root 1 2.6 0.1 19752 2352 ? Ss+ 08:24 0:00 top -b -H + root 7 0.0 0.1 15572 2164 ? R+ 08:25 0:00 ps aux + +And you can gracefully request `top` to shut down using `docker stop test`. + +The following `Dockerfile` shows using the `ENTRYPOINT` to run Apache in the +foreground (i.e., as `PID 1`): + +``` +FROM debian:stable +RUN apt-get update && apt-get install -y --force-yes apache2 +EXPOSE 80 443 +VOLUME ["/var/www", "/var/log/apache2", "/etc/apache2"] +ENTRYPOINT ["/usr/sbin/apache2ctl", "-D", "FOREGROUND"] +``` + +If you need to write a starter script for a single executable, you can ensure that +the final executable receives the Unix signals by using `exec` and `gosu` +commands: + +```bash +#!/bin/bash +set -e + +if [ "$1" = 'postgres' ]; then + chown -R postgres "$PGDATA" + + if [ -z "$(ls -A "$PGDATA")" ]; then + gosu postgres initdb + fi + + exec gosu postgres "$@" +fi + +exec "$@" +``` + +Lastly, if you need to do some extra cleanup (or communicate with other containers) +on shutdown, or are co-ordinating more than one executable, you may need to ensure +that the `ENTRYPOINT` script receives the Unix signals, passes them on, and then +does some more work: + +``` +#!/bin/sh +# Note: I've written this using sh so it works in the busybox container too + +# USE the trap if you need to also do manual cleanup after the service is stopped, +# or need to start multiple services in the one container +trap "echo TRAPed signal" HUP INT QUIT KILL TERM + +# start service in background here +/usr/sbin/apachectl start + +echo "[hit enter key to exit] or run 'docker stop '" +read + +# stop service and clean up here +echo "stopping apache" +/usr/sbin/apachectl stop + +echo "exited $0" +``` + +If you run this image with `docker run -it --rm -p 80:80 --name test apache`, +you can then examine the container's processes with `docker exec`, or `docker top`, +and then ask the script to stop Apache: + +```bash +$ docker exec -it test ps aux +USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND +root 1 0.1 0.0 4448 692 ? Ss+ 00:42 0:00 /bin/sh /run.sh 123 cmd cmd2 +root 19 0.0 0.2 71304 4440 ? Ss 00:42 0:00 /usr/sbin/apache2 -k start +www-data 20 0.2 0.2 360468 6004 ? Sl 00:42 0:00 /usr/sbin/apache2 -k start +www-data 21 0.2 0.2 360468 6000 ? Sl 00:42 0:00 /usr/sbin/apache2 -k start +root 81 0.0 0.1 15572 2140 ? R+ 00:44 0:00 ps aux +$ docker top test +PID USER COMMAND +10035 root {run.sh} /bin/sh /run.sh 123 cmd cmd2 +10054 root /usr/sbin/apache2 -k start +10055 33 /usr/sbin/apache2 -k start +10056 33 /usr/sbin/apache2 -k start +$ /usr/bin/time docker stop test +test +real 0m 0.27s +user 0m 0.03s +sys 0m 0.03s +``` + +> **Note:** you can over ride the `ENTRYPOINT` setting using `--entrypoint`, +> but this can only set the binary to *exec* (no `sh -c` will be used). + +> **Note**: +> The *exec* form is parsed as a JSON array, which means that +> you must use double-quotes (") around words not single-quotes ('). + +> **Note**: +> Unlike the *shell* form, the *exec* form does not invoke a command shell. +> This means that normal shell processing does not happen. For example, +> `ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. +> If you want shell processing then either use the *shell* form or execute +> a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo", "$HOME" ]`. +> Variables that are defined in the `Dockerfile`using `ENV`, will be substituted by +> the `Dockerfile` parser. + +### Shell form ENTRYPOINT example + +You can specify a plain string for the `ENTRYPOINT` and it will execute in `/bin/sh -c`. +This form will use shell processing to substitute shell environment variables, +and will ignore any `CMD` or `docker run` command line arguments. +To ensure that `docker stop` will signal any long running `ENTRYPOINT` executable +correctly, you need to remember to start it with `exec`: + + FROM ubuntu + ENTRYPOINT exec top -b + +When you run this image, you'll see the single `PID 1` process: + + $ docker run -it --rm --name test top + Mem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cached + CPU: 5% usr 0% sys 0% nic 94% idle 0% io 0% irq 0% sirq + Load average: 0.08 0.03 0.05 2/98 6 + PID PPID USER STAT VSZ %VSZ %CPU COMMAND + 1 0 root R 3164 0% 0% top -b + +Which will exit cleanly on `docker stop`: + + $ /usr/bin/time docker stop test + test + real 0m 0.20s + user 0m 0.02s + sys 0m 0.04s + +If you forget to add `exec` to the beginning of your `ENTRYPOINT`: + + FROM ubuntu + ENTRYPOINT top -b + CMD --ignored-param1 + +You can then run it (giving it a name for the next step): + + $ docker run -it --name test top --ignored-param2 + Mem: 1704184K used, 352484K free, 0K shrd, 0K buff, 140621524238337K cached + CPU: 9% usr 2% sys 0% nic 88% idle 0% io 0% irq 0% sirq + Load average: 0.01 0.02 0.05 2/101 7 + PID PPID USER STAT VSZ %VSZ %CPU COMMAND + 1 0 root S 3168 0% 0% /bin/sh -c top -b cmd cmd2 + 7 1 root R 3164 0% 0% top -b + +You can see from the output of `top` that the specified `ENTRYPOINT` is not `PID 1`. + +If you then run `docker stop test`, the container will not exit cleanly - the +`stop` command will be forced to send a `SIGKILL` after the timeout: + + $ docker exec -it test ps aux + PID USER COMMAND + 1 root /bin/sh -c top -b cmd cmd2 + 7 root top -b + 8 root ps aux + $ /usr/bin/time docker stop test + test + real 0m 10.19s + user 0m 0.04s + sys 0m 0.03s + +## VOLUME + + VOLUME ["/data"] + +The `VOLUME` instruction creates a mount point with the specified name +and marks it as holding externally mounted volumes from native host or other +containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain +string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log +/var/db`. For more information/examples and mounting instructions via the +Docker client, refer to +[*Share Directories via Volumes*](/userguide/dockervolumes/#volume) +documentation. + +The `docker run` command initializes the newly created volume with any data +that exists at the specified location within the base image. For example, +consider the following Dockerfile snippet: + + FROM ubuntu + RUN mkdir /myvol + RUN echo "hello world" > /myvol/greeting + VOLUME /myvol + +This Dockerfile results in an image that causes `docker run`, to +create a new mount point at `/myvol` and copy the `greeting` file +into the newly created volume. + +> **Note**: +> The list is parsed as a JSON array, which means that +> you must use double-quotes (") around words not single-quotes ('). + +## USER + + USER daemon + +The `USER` instruction sets the user name or UID to use when running the image +and for any `RUN`, `CMD` and `ENTRYPOINT` instructions that follow it in the +`Dockerfile`. + +## WORKDIR + + WORKDIR /path/to/workdir + +The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`, +`ENTRYPOINT`, `COPY` and `ADD` instructions that follow it in the `Dockerfile`. + +It can be used multiple times in the one `Dockerfile`. If a relative path +is provided, it will be relative to the path of the previous `WORKDIR` +instruction. For example: + + WORKDIR /a + WORKDIR b + WORKDIR c + RUN pwd + +The output of the final `pwd` command in this `Dockerfile` would be +`/a/b/c`. + +The `WORKDIR` instruction can resolve environment variables previously set using +`ENV`. You can only use environment variables explicitly set in the `Dockerfile`. +For example: + + ENV DIRPATH /path + WORKDIR $DIRPATH/$DIRNAME + +The output of the final `pwd` command in this `Dockerfile` would be +`/path/$DIRNAME` + +## ONBUILD + + ONBUILD [INSTRUCTION] + +The `ONBUILD` instruction adds to the image a *trigger* instruction to +be executed at a later time, when the image is used as the base for +another build. The trigger will be executed in the context of the +downstream build, as if it had been inserted immediately after the +`FROM` instruction in the downstream `Dockerfile`. + +Any build instruction can be registered as a trigger. + +This is useful if you are building an image which will be used as a base +to build other images, for example an application build environment or a +daemon which may be customized with user-specific configuration. + +For example, if your image is a reusable Python application builder, it +will require application source code to be added in a particular +directory, and it might require a build script to be called *after* +that. You can't just call `ADD` and `RUN` now, because you don't yet +have access to the application source code, and it will be different for +each application build. You could simply provide application developers +with a boilerplate `Dockerfile` to copy-paste into their application, but +that is inefficient, error-prone and difficult to update because it +mixes with application-specific code. + +The solution is to use `ONBUILD` to register advance instructions to +run later, during the next build stage. + +Here's how it works: + +1. When it encounters an `ONBUILD` instruction, the builder adds a + trigger to the metadata of the image being built. The instruction + does not otherwise affect the current build. +2. At the end of the build, a list of all triggers is stored in the + image manifest, under the key `OnBuild`. They can be inspected with + the `docker inspect` command. +3. Later the image may be used as a base for a new build, using the + `FROM` instruction. As part of processing the `FROM` instruction, + the downstream builder looks for `ONBUILD` triggers, and executes + them in the same order they were registered. If any of the triggers + fail, the `FROM` instruction is aborted which in turn causes the + build to fail. If all triggers succeed, the `FROM` instruction + completes and the build continues as usual. +4. Triggers are cleared from the final image after being executed. In + other words they are not inherited by "grand-children" builds. + +For example you might add something like this: + + [...] + ONBUILD ADD . /app/src + ONBUILD RUN /usr/local/bin/python-build --dir /app/src + [...] + +> **Warning**: Chaining `ONBUILD` instructions using `ONBUILD ONBUILD` isn't allowed. + +> **Warning**: The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions. + +## Dockerfile examples + + # Nginx + # + # VERSION 0.0.1 + + FROM ubuntu + MAINTAINER Victor Vieux + + LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products" Version="1.0" + RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server + + # Firefox over VNC + # + # VERSION 0.3 + + FROM ubuntu + + # Install vnc, xvfb in order to create a 'fake' display and firefox + RUN apt-get update && apt-get install -y x11vnc xvfb firefox + RUN mkdir ~/.vnc + # Setup a password + RUN x11vnc -storepasswd 1234 ~/.vnc/passwd + # Autostart firefox (might not be the best way, but it does the trick) + RUN bash -c 'echo "firefox" >> /.bashrc' + + EXPOSE 5900 + CMD ["x11vnc", "-forever", "-usepw", "-create"] + + # Multiple images example + # + # VERSION 0.1 + + FROM ubuntu + RUN echo foo > bar + # Will output something like ===> 907ad6c2736f + + FROM ubuntu + RUN echo moo > oink + # Will output something like ===> 695d7793cbe4 + + # You᾿ll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with + # /oink. + From dd4d6862d0ef7fa721657dbf66466354e1330142 Mon Sep 17 00:00:00 2001 From: Chris McKinnel Date: Fri, 26 Jun 2015 09:43:30 +0100 Subject: [PATCH 003/152] Fix a broken anchor tag on the CLI builder page Signed-off-by: Chris McKinnel --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 89b760265..49aa580d1 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -51,7 +51,7 @@ In most cases, it's best to put each Dockerfile in an empty directory. Then, only add the files needed for building the Dockerfile to the directory. To increase the build's performance, you can exclude files and directories by adding a `.dockerignore` file to the directory. For information about how to -[create a `.dockerignore` file](#the-dockerignore-file) on this page. +[create a `.dockerignore` file](#dockerignore-file) on this page. You can specify a repository and tag at which to save the new image if the build succeeds: From 5236fb74323b31482a741e249e9b364409ddb173 Mon Sep 17 00:00:00 2001 From: Tim Wraight Date: Mon, 22 Jun 2015 14:26:35 +0100 Subject: [PATCH 004/152] Clarify .dockerignore example for Markdown files The current documentation correctly states that dockerignore pattern searches are non-recursive. However, the example given for Markdown files seems to contradict this by saying that `*.md` will exclude *all* Markdown files. This commit clarifies the situation by explicitly specifying that `*.md` will only exclude files in the root directory of the project. Signed-off-by: Tim Wraight --- frontend/dockerfile/docs/reference.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 49aa580d1..93355fa3b 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -208,11 +208,11 @@ This file causes the following build behavior: | Rule | Behavior | |----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `*/temp*` | Exclude all files with names starting with`temp` in any subdirectory below the root directory. For example, a file named`/somedir/temporary.txt` is ignored. | +| `*/temp*` | Exclude all files with names starting with`temp` in any subdirectory below the root directory. For example, a file named`/somedir/temporary.txt` is ignored. | | `*/*/temp*` | Exclude files starting with name `temp` from any subdirectory that is two levels below the root directory. For example, the file `/somedir/subdir/temporary.txt` is ignored. | -| `temp?` | Exclude the files that match the pattern in the root directory. For example, the files `tempa`, `tempb` in the root directory are ignored. | -| `*.md ` | Exclude all markdown files. | -| `!LICENSE.md` | Exception to the exclude all Markdown files is this file, `LICENSE.md`, include this file in the build. | +| `temp?` | Exclude the files that match the pattern in the root directory. For example, the files `tempa`, `tempb` in the root directory are ignored. | +| `*.md ` | Exclude all markdown files in the root directory. | +| `!LICENSE.md` | Exception to the Markdown files exclusion is this file, `LICENSE.md`, Include this file in the build. | The placement of `!` exception rules influences the matching algorithm; the last line of the `.dockerignore` that matches a particular file determines @@ -229,8 +229,9 @@ example: ``` The build would exclude `LICENSE.md` because the last `*.md` rule adds all -Markdown files back onto the ignore list. The `!LICENSE.md` rule has no effect -because the subsequent `*.md` rule overrides it. +Markdown files in the root directory back onto the ignore list. The +`!LICENSE.md` rule has no effect because the subsequent `*.md` rule overrides +it. You can even use the `.dockerignore` file to ignore the `Dockerfile` and `.dockerignore` files. This is useful if you are copying files from the root of From e5a0893d0ea68a753a8163d814cad1965965b1c0 Mon Sep 17 00:00:00 2001 From: jgeiger Date: Wed, 22 Jul 2015 23:54:13 -0600 Subject: [PATCH 005/152] Fix typo in builder.mb .dockerignore example Signed-off-by: jgeiger --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 93355fa3b..b08ff584f 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -201,7 +201,7 @@ The following is an example `.dockerignore` file: */*/temp* temp? *.md - !LICENCSE.md + !LICENSE.md ``` This file causes the following build behavior: From 0fb686fbe5e50937ee371301bb3181b1be71ae9e Mon Sep 17 00:00:00 2001 From: John Tims Date: Sun, 26 Jul 2015 10:53:07 -0400 Subject: [PATCH 006/152] Fix typo Signed-off-by: John Tims --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index b08ff584f..e23ede533 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -224,7 +224,7 @@ example: */temp* */*/temp* temp? - !LICENCSE.md + !LICENSE.md *.md ``` From 2b384ac3ee15016b08f4f09fdaa00dae9d7d3be8 Mon Sep 17 00:00:00 2001 From: Charles Chan Date: Sat, 18 Jul 2015 21:09:48 -0700 Subject: [PATCH 007/152] Minor edits to Environment variables section * Clarify the list of supported instructions. * Clarify behavior of ONBUILD, based on comments by @SvenDowideit, @theJeztah in PR #14735. * Reorder list of instructions in alphabetical order. Signed-off-by: Charles Chan --- frontend/dockerfile/docs/reference.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index e23ede533..062c4793f 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -152,18 +152,24 @@ Example (parsed representation is displayed after the `#`): ADD . $foo # ADD . /bar COPY \$foo /quux # COPY $foo /quux -The instructions that handle environment variables in the `Dockerfile` are: +Environment variables are supported by the following list of instructions in +the `Dockerfile`: -* `ENV` * `ADD` * `COPY` -* `WORKDIR` +* `ENV` * `EXPOSE` -* `VOLUME` * `USER` +* `WORKDIR` +* `VOLUME` -`ONBUILD` instructions are **NOT** supported for environment replacement, even -the instructions above. +as well as: + +* `ONBUILD` (when combined with one of the supported instructions above) + +> **Note**: +> prior to 1.4, `ONBUILD` instructions did **NOT** support environment +> variable, even when combined with any of the instructions listed above. Environment variable substitution will use the same value for each variable throughout the entire command. In other words, in this example: From 8b6f3968a9c37c482f7ce990d7f456a635566f99 Mon Sep 17 00:00:00 2001 From: Ankush Agarwal Date: Fri, 7 Aug 2015 10:01:07 -0700 Subject: [PATCH 008/152] Remove note from docker version 1.3 on Env variables Fixes #14734 Signed-off-by: Ankush Agarwal --- frontend/dockerfile/docs/reference.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 062c4793f..5088edc4a 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -114,12 +114,6 @@ images. ### Environment replacement -> **Note**: prior to 1.3, `Dockerfile` environment variables were handled -> similarly, in that they would be replaced as described below. However, there -> was no formal definition on as to which instructions handled environment -> replacement at the time. After 1.3 this behavior will be preserved and -> canonical. - Environment variables (declared with [the `ENV` statement](#env)) can also be used in certain instructions as variables to be interpreted by the `Dockerfile`. Escapes are also handled for including variable-like syntax From 0b37796f4abc60b2ecbe7ad6cfdcfb2f44760364 Mon Sep 17 00:00:00 2001 From: Dharmit Shah Date: Sat, 15 Aug 2015 12:00:21 +0530 Subject: [PATCH 009/152] Fixing docs to remove references to links under terms/ Removed terms/ directory Signed-off-by: Dharmit Shah --- frontend/dockerfile/docs/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 5088edc4a..5fbed753c 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -100,7 +100,7 @@ be UPPERCASE in order to distinguish them from arguments more easily. Docker runs the instructions in a `Dockerfile` in order. **The first instruction must be \`FROM\`** in order to specify the [*Base -Image*](/terms/image/#base-image) from which you are building. +Image*](/reference/glossary/#base-image) from which you are building. Docker will treat lines that *begin* with `#` as a comment. A `#` marker anywhere else in the line will @@ -251,7 +251,7 @@ Or FROM @ -The `FROM` instruction sets the [*Base Image*](/terms/image/#base-image) +The `FROM` instruction sets the [*Base Image*](/reference/glossary/#base-image) for subsequent instructions. As such, a valid `Dockerfile` must have `FROM` as its first instruction. The image can be any valid image – it is especially easy to start by **pulling an image** from the [*Public Repositories*]( From 75e35776be410dfd13c4b3aaab19ae6312741b82 Mon Sep 17 00:00:00 2001 From: Patrick Hemmer Date: Wed, 5 Aug 2015 12:30:36 -0400 Subject: [PATCH 010/152] add documentation clarifying behavior of VOLUME instruction Signed-off-by: Patrick Hemmer --- frontend/dockerfile/docs/reference.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 5fbed753c..1d7a86aeb 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -906,6 +906,10 @@ This Dockerfile results in an image that causes `docker run`, to create a new mount point at `/myvol` and copy the `greeting` file into the newly created volume. +> **Note**: +> If any build steps change the data within the volume after it has been +> declared, those changes will be discarded. + > **Note**: > The list is parsed as a JSON array, which means that > you must use double-quotes (") around words not single-quotes ('). From bb13c6401f52526f3bf82aa931c7150699ab9f43 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Tue, 18 Aug 2015 12:25:59 -0700 Subject: [PATCH 011/152] Updating hashcode links to commands Signed-off-by: Mary Anthony --- frontend/dockerfile/docs/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 1d7a86aeb..5709168d8 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -25,7 +25,7 @@ Dockerfile knowledge with the [Dockerfile tutorial](/userguide/level1). ## Usage -To [*build*](/reference/commandline/cli/#build) an image from a source repository, +To [*build*](/reference/commandline/build) an image from a source repository, create a description file called `Dockerfile` at the root of your repository. This file will describe the steps to assemble the image. @@ -890,7 +890,7 @@ containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log /var/db`. For more information/examples and mounting instructions via the Docker client, refer to -[*Share Directories via Volumes*](/userguide/dockervolumes/#volume) +[*Share Directories via Volumes*](/userguide/dockervolumes/#mount-a-host-directory-as-a-data-volume) documentation. The `docker run` command initializes the newly created volume with any data From de1e2af2b00fa9668315a86ec37553c54b77f537 Mon Sep 17 00:00:00 2001 From: Morgan Bauer Date: Fri, 17 Jul 2015 11:40:56 -0700 Subject: [PATCH 012/152] remove references to 'source repository' - rewrite intro to Dockerfile reference usage section to remove references to 'source repository' - Closes #14714 - Fixes: #8648 - Updating with Seb's comments Signed-off-by: Mary Anthony --- frontend/dockerfile/docs/reference.md | 76 ++++++++++++++------------- 1 file changed, 39 insertions(+), 37 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 5709168d8..6ec9e7d1c 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -10,48 +10,50 @@ parent = "mn_reference" # Dockerfile reference -**Docker can build images automatically** by reading the instructions -from a `Dockerfile`. A `Dockerfile` is a text document that contains all -the commands you would normally execute manually in order to build a -Docker image. By calling `docker build` from your terminal, you can have -Docker build your image step by step, executing the instructions -successively. +Docker can build images automatically by reading the instructions from a +`Dockerfile`. A `Dockerfile` is a text document that contains all the commands a +user could call on the command line to assemble an image. Using `docker build` +users can create an automated build that executes several command-line +instructions in succession. -This page discusses the specifics of all the instructions you can use in your -`Dockerfile`. To further help you write a clear, readable, maintainable -`Dockerfile`, we've also written a [`Dockerfile` Best Practices -guide](/articles/dockerfile_best-practices). Lastly, you can test your -Dockerfile knowledge with the [Dockerfile tutorial](/userguide/level1). +This page describes the commands you can use in a `Dockerfile`. When you are +done reading this page, refer to the [`Dockerfile` Best +Practices](/articles/dockerfile_best-practices) for a tip-oriented guide. ## Usage -To [*build*](/reference/commandline/build) an image from a source repository, -create a description file called `Dockerfile` at the root of your repository. -This file will describe the steps to assemble the image. +The [`docker build`](/reference/commandline/build/) command builds an image from +a `Dockerfile` and a *context*. The build's context is the files at a specified +location `PATH` or `URL`. The `PATH` is a directory on your local filesystem. +The `URL` is a the location of a Git repository. -Then call `docker build` with the path of your source repository as the argument -(for example, `.`): +A context is processed recursively. So, a `PATH` includes any subdirectories and +the `URL` includes the repository and its submodules. A simple build command +that uses the current directory as context: $ docker build . + Sending build context to Docker daemon 6.51 MB + ... -The path to the source repository defines where to find the *context* of -the build. The build is run by the Docker daemon, not by the CLI, so the -whole context must be transferred to the daemon. The Docker CLI reports -"Sending build context to Docker daemon" when the context is sent to the daemon. +The build is run by the Docker daemon, not by the CLI. The first thing a build +process does is send the entire context (recursively) to the daemon. In most +cases, it's best to start with an empty directory as context and keep your +Dockerfile in that directory. Add only the files needed for building the +Dockerfile. -> **Warning** -> Avoid using your root directory, `/`, as the root of the source repository. The -> `docker build` command will use whatever directory contains the Dockerfile as the build -> context (including all of its subdirectories). The build context will be sent to the -> Docker daemon before building the image, which means if you use `/` as the source -> repository, the entire contents of your hard drive will get sent to the daemon (and -> thus to the machine running the daemon). You probably don't want that. +>**Warning**: Do not use your root directory, `/`, as the `PATH` as it causes +>the build to transfer the entire contents of your hard drive to the Docker +>daemon. -In most cases, it's best to put each Dockerfile in an empty directory. Then, -only add the files needed for building the Dockerfile to the directory. To -increase the build's performance, you can exclude files and directories by -adding a `.dockerignore` file to the directory. For information about how to -[create a `.dockerignore` file](#dockerignore-file) on this page. +To use a file in the build context, the `Dockerfile` refers to the file with +an instruction, for example, a `COPY` instruction. To increase the build's +performance, exclude files and directories by adding a `.dockerignore` file to +the context directory. For information about how to [create a `.dockerignore` +file](#dockerignore-file) see the documentation on this page. + +Traditionally, the `Dockerfile` is called `Dockerfile` and located in the root +of the context. You use the `-f` flag with `docker build` to point to a Dockerfile +anywhere in your file system. You can specify a repository and tag at which to save the new image if the build succeeds: @@ -166,13 +168,13 @@ as well as: > variable, even when combined with any of the instructions listed above. Environment variable substitution will use the same value for each variable -throughout the entire command. In other words, in this example: +throughout the entire command. In other words, in this example: ENV abc=hello ENV abc=bye def=$abc ENV ghi=$abc -will result in `def` having a value of `hello`, not `bye`. However, +will result in `def` having a value of `hello`, not `bye`. However, `ghi` will have a value of `bye` because it is not part of the same command that set `abc` to `bye`. @@ -191,7 +193,7 @@ expansion) is done using Go's You can specify exceptions to exclusion rules. To do this, simply prefix a pattern with an `!` (exclamation mark) in the same way you would in a -`.gitignore` file. Currently there is no support for regular expressions. +`.gitignore` file. Currently there is no support for regular expressions. Formats like `[^temp*]` are ignored. The following is an example `.dockerignore` file: @@ -310,7 +312,7 @@ commands using a base image that does not contain `/bin/sh`. The cache for `RUN` instructions isn't invalidated automatically during the next build. The cache for an instruction like -`RUN apt-get dist-upgrade -y` will be reused during the next build. The +`RUN apt-get dist-upgrade -y` will be reused during the next build. The cache for `RUN` instructions can be invalidated by using the `--no-cache` flag, for example `docker build --no-cache`. @@ -888,7 +890,7 @@ The `VOLUME` instruction creates a mount point with the specified name and marks it as holding externally mounted volumes from native host or other containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log -/var/db`. For more information/examples and mounting instructions via the +/var/db`. For more information/examples and mounting instructions via the Docker client, refer to [*Share Directories via Volumes*](/userguide/dockervolumes/#mount-a-host-directory-as-a-data-volume) documentation. From 436d963904a97c7651c99ed9f886d1b3ba71c6c1 Mon Sep 17 00:00:00 2001 From: bin liu Date: Wed, 19 Aug 2015 18:41:34 +0800 Subject: [PATCH 013/152] add missing instruction Signed-off-by: bin liu --- frontend/dockerfile/docs/reference.md | 1 + 1 file changed, 1 insertion(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 6ec9e7d1c..3a73b87d2 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -949,6 +949,7 @@ For example: ENV DIRPATH /path WORKDIR $DIRPATH/$DIRNAME + RUN pwd The output of the final `pwd` command in this `Dockerfile` would be `/path/$DIRNAME` From 1c0cd85881d6cfb75215e7ef13acf618d8578a7c Mon Sep 17 00:00:00 2001 From: David Calavera Date: Tue, 18 Aug 2015 10:30:44 -0700 Subject: [PATCH 014/152] Add `STOPSIGNAL` instruction to dockerfiles. This way, images creators can set the exit signal their programs use. Signed-off-by: David Calavera --- frontend/dockerfile/docs/reference.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 3a73b87d2..195139758 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -158,6 +158,7 @@ the `Dockerfile`: * `USER` * `WORKDIR` * `VOLUME` +* `STOPSIGNAL` as well as: @@ -1012,6 +1013,14 @@ For example you might add something like this: > **Warning**: The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions. +## STOPSIGNAL + + STOPSIGNAL signal + +The `STOPSIGNAL` instruction sets the system call signal that will be sent to the container to exit. +This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, +or a signal name in the format SIGNAME, for instance SIGKILL. + ## Dockerfile examples # Nginx From 0a2e545f13c8b2d83d5a4ec9c7d84a779a628762 Mon Sep 17 00:00:00 2001 From: Amen Belayneh Date: Sat, 12 Sep 2015 15:26:14 +0800 Subject: [PATCH 015/152] add a documentation note on backslash usage in shell form of RUN Signed-off-by: Amen Belayneh --- frontend/dockerfile/docs/reference.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 195139758..5ce217b22 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -311,6 +311,12 @@ commands using a base image that does not contain `/bin/sh`. > If you want shell processing then either use the *shell* form or execute > a shell directly, for example: `RUN [ "sh", "-c", "echo", "$HOME" ]`. +> **Note**: +> If you choose to use the *shell* form, any time you want to continue a single +> `RUN` instruction onto the next line, it has to be ended with a backslash `\`. +> For example, `RUN /bin/bash -c 'source $HOME/.bashrc ;\` then on the next +> line ` echo $HOME '`. + The cache for `RUN` instructions isn't invalidated automatically during the next build. The cache for an instruction like `RUN apt-get dist-upgrade -y` will be reused during the next build. The From d4ea363cfbe8513487bb2efae4fcf0366227fa3a Mon Sep 17 00:00:00 2001 From: Amen Belayneh Date: Mon, 14 Sep 2015 19:08:27 +0800 Subject: [PATCH 016/152] update documentation styling as per suggestions Signed-off-by: Amen Belayneh --- frontend/dockerfile/docs/reference.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 5ce217b22..537cc98ec 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -295,6 +295,17 @@ any point in an image's history, much like source control. The *exec* form makes it possible to avoid shell string munging, and to `RUN` commands using a base image that does not contain `/bin/sh`. +In the *shell* form you can use a `\` (backslash) to continue a single +RUN instruction onto the next line. For example, consider these two lines: +``` +RUN /bin/bash -c 'source $HOME/.bashrc ;\ +echo $HOME' +``` +Together they are equivalent to this single line: +``` +RUN /bin/bash -c 'source $HOME/.bashrc ; echo $HOME' +``` + > **Note**: > To use a different shell, other than '/bin/sh', use the *exec* form > passing in the desired shell. For example, @@ -311,12 +322,6 @@ commands using a base image that does not contain `/bin/sh`. > If you want shell processing then either use the *shell* form or execute > a shell directly, for example: `RUN [ "sh", "-c", "echo", "$HOME" ]`. -> **Note**: -> If you choose to use the *shell* form, any time you want to continue a single -> `RUN` instruction onto the next line, it has to be ended with a backslash `\`. -> For example, `RUN /bin/bash -c 'source $HOME/.bashrc ;\` then on the next -> line ` echo $HOME '`. - The cache for `RUN` instructions isn't invalidated automatically during the next build. The cache for an instruction like `RUN apt-get dist-upgrade -y` will be reused during the next build. The From d10edcb8a5926fe71a81a935568a4692d9547726 Mon Sep 17 00:00:00 2001 From: Madhav Puri Date: Fri, 14 Nov 2014 10:59:14 -0800 Subject: [PATCH 017/152] Support for passing build-time variables in build context - The build-time variables are passed as environment-context for command(s) run as part of the RUN primitve. These variables are not persisted in environment of intermediate and final images when passed as context for RUN. The build environment is prepended to the intermediate continer's command string for aiding cache lookups. It also helps with build traceability. But this also makes the feature less secure from point of view of passing build time secrets. - The build-time variables also get used to expand the symbols used in certain Dockerfile primitves like ADD, COPY, USER etc, without an explicit prior definiton using a ENV primitive. These variables get persisted in the intermediate and final images whenever they are expanded. - The build-time variables are only expanded or passed to the RUN primtive if they are defined in Dockerfile using the ARG primitive or belong to list of built-in variables. HTTP_PROXY, HTTPS_PROXY, http_proxy, https_proxy, FTP_PROXY and NO_PROXY are built-in variables that needn't be explicitly defined in Dockerfile to use this feature. Signed-off-by: Madhav Puri --- frontend/dockerfile/docs/reference.md | 121 ++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 537cc98ec..848d69717 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -966,6 +966,127 @@ For example: The output of the final `pwd` command in this `Dockerfile` would be `/path/$DIRNAME` +## ARG + + ARG [=] + +The `ARG` instruction defines a variable that users can pass at build-time to +the builder with the `docker build` command using the `--build-arg +=` flag. If a user specifies a build argument that was not +defined in the Dockerfile, the build outputs an error. + +``` +One or more build-args were not consumed, failing build. +``` + +The Dockerfile author can define a single variable by specifying `ARG` once or many +variables by specifying `ARG` more than once. For example, a valid Dockerfile: + +``` +FROM busybox +ARG user1 +ARG buildno +... +``` + +A Dockerfile author may optionally specify a default value for an `ARG` instruction: + +``` +FROM busybox +ARG user1=someuser +ARG buildno=1 +... +``` + +If an `ARG` value has a default and if there is no value passed at build-time, the +builder uses the default. + +An `ARG` variable definition comes into effect from the line on which it is +defined in the `Dockerfile` not from the argument's use on the command-line or +elsewhere. For example, consider this Dockerfile: + +``` +1 FROM busybox +2 USER ${user:-some_user} +3 ARG user +4 USER $user +... +``` +A user builds this file by calling: + +``` +$ docker build --build-arg user=what_user Dockerfile +``` + +The `USER` at line 2 evaluates to `some_user` as the `user` variable is defined on the +subsequent line 3. The `USER` at line 4 evaluates to `what_user` as `user` is +defined and the `what_user` value was passed on the command line. Prior to its definition by an +`ARG` instruction, any use of a variable results in an empty string. + +> **Note:** It is not recommended to use build-time variables for +> passing secrets like github keys, user credentials etc. + +You can use an `ARG` or an `ENV` instruction to specify variables that are +available to the `RUN` instruction. Environment variables defined using the +`ENV` instruction always override an `ARG` instruction of the same name. Consider +this Dockerfile with an `ENV` and `ARG` instruction. + +``` +1 FROM ubuntu +2 ARG CONT_IMG_VER +3 ENV CONT_IMG_VER v1.0.0 +4 RUN echo $CONT_IMG_VER +``` +Then, assume this image is built with this command: + +``` +$ docker build --build-arg CONT_IMG_VER=v2.0.1 Dockerfile +``` + +In this case, the `RUN` instruction uses `v1.0.0` instead of the `ARG` setting +passed by the user:`v2.0.1` This behavior is similar to a shell +script where a locally scoped variable overrides the variables passed as +arguments or inherited from environment, from its point of definition. + +Using the example above but a different `ENV` specification you can create more +useful interactions between `ARG` and `ENV` instructions: + +``` +1 FROM ubuntu +2 ARG CONT_IMG_VER +3 ENV CONT_IMG_VER ${CONT_IMG_VER:-v1.0.0} +4 RUN echo $CONT_IMG_VER +``` + +The command line passes the `--build-arg` and sets the `v2.0.1` value. And the `ARG +CONT_IMG_VER` is defined on line 2 of the Dockerfile. On line 3, the `ENV` +instruction of the same name resolves to `v2.0.1` as the build-time variable +was passed from the command line and expanded here. + +The variable expansion technique in this example allows you to pass arguments +from the command line and persist them in the final image by leveraging the `ENV` +instruction. Variable expansion is only supported for the `Dockerfile` instructions +described [here](#environment-replacement). + +Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. If +`docker build` were run without setting the `--build-arg` flag, then +`CONT_IMG_VER` is still persisted in the image but its value would be `v1.0.0`. + +Docker has a set of predefined `ARG` variables that you can use without a +corresponding `ARG` instruction in the Dockerfile. + +* `HTTP_PROXY` +* `http_proxy` +* `HTTPS_PROXY` +* `https_proxy` +* `FTP_PROXY` +* `ftp_proxy` +* `NO_PROXY` +* `no_proxy` + +To use these, simply pass them on the command line using the `--build-arg +=` flag. + ## ONBUILD ONBUILD [INSTRUCTION] From c822f735b8865bcdda04693ed07cd708fb01e0a2 Mon Sep 17 00:00:00 2001 From: Madhav Puri Date: Wed, 16 Sep 2015 01:47:10 -0700 Subject: [PATCH 018/152] incorporate doc review comments Signed-off-by: Madhav Puri --- frontend/dockerfile/docs/reference.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 848d69717..c51910205 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1058,19 +1058,20 @@ useful interactions between `ARG` and `ENV` instructions: 4 RUN echo $CONT_IMG_VER ``` -The command line passes the `--build-arg` and sets the `v2.0.1` value. And the `ARG -CONT_IMG_VER` is defined on line 2 of the Dockerfile. On line 3, the `ENV` -instruction of the same name resolves to `v2.0.1` as the build-time variable -was passed from the command line and expanded here. +Unlike an `ARG` instruction, `ENV` values are always persisted in the built +image. Consider a docker build without the --build-arg flag: + +``` +$ docker build Dockerfile +``` + +Using this Dockerfile example, `CONT_IMG_VER` is still persisted in the image but +its value would be `v1.0.0` as it is the default set in line 3 by the `ENV` instruction. The variable expansion technique in this example allows you to pass arguments -from the command line and persist them in the final image by leveraging the `ENV` -instruction. Variable expansion is only supported for the `Dockerfile` instructions -described [here](#environment-replacement). - -Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. If -`docker build` were run without setting the `--build-arg` flag, then -`CONT_IMG_VER` is still persisted in the image but its value would be `v1.0.0`. +from the command line and persist them in the final image by leveraging the +`ENV` instruction. Variable expansion is only supported for [a limited set of +Dockerfile instructions.](#environment-replacement) Docker has a set of predefined `ARG` variables that you can use without a corresponding `ARG` instruction in the Dockerfile. From 478526363898c41ad6471b6f281d09d43c9a7b1b Mon Sep 17 00:00:00 2001 From: Tim Waugh Date: Wed, 16 Sep 2015 14:38:58 +0100 Subject: [PATCH 019/152] Add documentation note that LABEL allows environment replacement Signed-off-by: Tim Waugh --- frontend/dockerfile/docs/reference.md | 1 + 1 file changed, 1 insertion(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index c51910205..29dd61aee 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -155,6 +155,7 @@ the `Dockerfile`: * `COPY` * `ENV` * `EXPOSE` +* `LABEL` * `USER` * `WORKDIR` * `VOLUME` From 0d7602a4efa252e36a24d62c68a7c247732d2491 Mon Sep 17 00:00:00 2001 From: Charles Chan Date: Sun, 6 Sep 2015 15:48:05 -0700 Subject: [PATCH 020/152] Touch up "Dockerfile reference" - add example for `docker build -f ...` - modifiy `FROM` explaination into bullet points - add/clarify examples for `LABEL` and `ADD` instructions - fix review comments (PR #16109) Signed-off-by: Charles Chan --- frontend/dockerfile/docs/reference.md | 83 +++++++++++++++------------ 1 file changed, 46 insertions(+), 37 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 29dd61aee..7c3051153 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -45,8 +45,8 @@ Dockerfile. >the build to transfer the entire contents of your hard drive to the Docker >daemon. -To use a file in the build context, the `Dockerfile` refers to the file with -an instruction, for example, a `COPY` instruction. To increase the build's +To use a file in the build context, the `Dockerfile` refers to the file specified +in an instruction, for example, a `COPY` instruction. To increase the build's performance, exclude files and directories by adding a `.dockerignore` file to the context directory. For information about how to [create a `.dockerignore` file](#dockerignore-file) see the documentation on this page. @@ -55,12 +55,15 @@ Traditionally, the `Dockerfile` is called `Dockerfile` and located in the root of the context. You use the `-f` flag with `docker build` to point to a Dockerfile anywhere in your file system. + $ docker build -f /path/to/a/Dockerfile . + You can specify a repository and tag at which to save the new image if the build succeeds: $ docker build -t shykes/myapp . -The Docker daemon will run your steps one-by-one, committing the result +The Docker daemon runs the instructions in the `Dockerfile` one-by-one, +committing the result of each instruction to a new image if necessary, before finally outputting the ID of your new image. The Docker daemon will automatically clean up the context you sent. @@ -69,10 +72,11 @@ Note that each instruction is run independently, and causes a new image to be created - so `RUN cd /tmp` will not have any effect on the next instructions. -Whenever possible, Docker will re-use the intermediate images, -accelerating `docker build` significantly (indicated by `Using cache` - -see the [`Dockerfile` Best Practices -guide](/articles/dockerfile_best-practices/#build-cache) for more information): +Whenever possible, Docker will re-use the intermediate images (cache), +to accelerate the `docker build` process significantly. This is indicated by +the `Using cache` message in the console output. +(For more information, see the [Build cache section](/articles/dockerfile_best-practices/#build-cache)) in the +`Dockerfile` best practices guide: $ docker build -t SvenDowideit/ambassador . Uploading context 10.24 kB @@ -97,7 +101,7 @@ Here is the format of the `Dockerfile`: # Comment INSTRUCTION arguments -The Instruction is not case-sensitive, however convention is for them to +The instruction is not case-sensitive, however convention is for them to be UPPERCASE in order to distinguish them from arguments more easily. Docker runs the instructions in a `Dockerfile` in order. **The @@ -216,7 +220,7 @@ This file causes the following build behavior: | `*/*/temp*` | Exclude files starting with name `temp` from any subdirectory that is two levels below the root directory. For example, the file `/somedir/subdir/temporary.txt` is ignored. | | `temp?` | Exclude the files that match the pattern in the root directory. For example, the files `tempa`, `tempb` in the root directory are ignored. | | `*.md ` | Exclude all markdown files in the root directory. | -| `!LICENSE.md` | Exception to the Markdown files exclusion is this file, `LICENSE.md`, Include this file in the build. | +| `!LICENSE.md` | Exception to the Markdown files exclusion. `LICENSE.md`is included in the build. | The placement of `!` exception rules influences the matching algorithm; the last line of the `.dockerignore` that matches a particular file determines @@ -261,13 +265,13 @@ its first instruction. The image can be any valid image – it is especially eas to start by **pulling an image** from the [*Public Repositories*]( /userguide/dockerrepos). -`FROM` must be the first non-comment instruction in the `Dockerfile`. +- `FROM` must be the first non-comment instruction in the `Dockerfile`. -`FROM` can appear multiple times within a single `Dockerfile` in order to create +- `FROM` can appear multiple times within a single `Dockerfile` in order to create multiple images. Simply make a note of the last image ID output by the commit before each new `FROM` command. -The `tag` or `digest` values are optional. If you omit either of them, the builder +- The `tag` or `digest` values are optional. If you omit either of them, the builder assumes a `latest` by default. The builder returns an error if it cannot match the `tag` value. @@ -282,7 +286,7 @@ generated images. RUN has 2 forms: -- `RUN ` (the command is run in a shell - `/bin/sh -c` - *shell* form) +- `RUN ` (*shell* form, the command is run in a shell - `/bin/sh -c`) - `RUN ["executable", "param1", "param2"]` (*exec* form) The `RUN` instruction will execute any commands in a new layer on top of the @@ -415,28 +419,31 @@ default specified in `CMD`. The `LABEL` instruction adds metadata to an image. A `LABEL` is a key-value pair. To include spaces within a `LABEL` value, use quotes and -backslashes as you would in command-line parsing. +backslashes as you would in command-line parsing. A few usage examples: LABEL "com.example.vendor"="ACME Incorporated" - -An image can have more than one label. To specify multiple labels, separate each -key-value pair with whitespace. - LABEL com.example.label-with-value="foo" LABEL version="1.0" LABEL description="This text illustrates \ that label-values can span multiple lines." -Docker recommends combining labels in a single `LABEL` instruction where +An image can have more than one label. To specify multiple labels, +Docker recommends combining labels into a single `LABEL` instruction where possible. Each `LABEL` instruction produces a new layer which can result in an -inefficient image if you use many labels. This example results in four image -layers. +inefficient image if you use many labels. This example results in a single image +layer. LABEL multi.label1="value1" multi.label2="value2" other="value3" + +The above can also be written as: + + LABEL multi.label1="value1" \ + multi.label2="value2" \ + other="value3" -Labels are additive including `LABEL`s in `FROM` images. As the system -encounters and then applies a new label, new `key`s override any previous labels -with identical keys. +Labels are additive including `LABEL`s in `FROM` images. If Docker +encounters a label/key that already exists, the new value overrides any previous +labels with identical keys. To view an image's labels, use the `docker inspect` command. @@ -497,14 +504,14 @@ and ENV myCat fluffy will yield the same net results in the final container, but the first form -does it all in one layer. +is preferred because it produces a single cache layer. The environment variables set using `ENV` will persist when a container is run from the resulting image. You can view the values using `docker inspect`, and change them using `docker run --env =`. > **Note**: -> Environment persistence can cause unexpected effects. For example, +> Environment persistence can cause unexpected side effects. For example, > setting `ENV DEBIAN_FRONTEND noninteractive` may confuse apt-get > users on a Debian-based image. To set a value for a single command, use > `RUN = `. @@ -525,16 +532,16 @@ directories then they must be relative to the source directory that is being built (the context of the build). Each `` may contain wildcards and matching will be done using Go's -[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. -For most command line uses this should act as expected, for example: +[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: ADD hom* /mydir/ # adds all files starting with "hom" - ADD hom?.txt /mydir/ # ? is replaced with any single character + ADD hom?.txt /mydir/ # ? is replaced with any single character, e.g., "home.txt" The `` is an absolute path, or a path relative to `WORKDIR`, into which the source will be copied inside the destination container. - ADD test aDir/ # adds "test" to `WORKDIR`/aDir/ + ADD test relativeDir/ # adds "test" to `WORKDIR`/relativeDir/ + ADD test /absoluteDir # adds "test" to /absoluteDir All new files and directories are created with a UID and GID of 0. @@ -567,7 +574,7 @@ of whether or not the file has changed and the cache should be updated. guide](/articles/dockerfile_best-practices/#build-cache) for more information. -The copy obeys the following rules: +`ADD` obeys the following rules: - The `` path must be inside the *context* of the build; you cannot `ADD ../something /something`, because the first step of a @@ -586,6 +593,7 @@ The copy obeys the following rules: - If `` is a directory, the entire contents of the directory are copied, including filesystem metadata. + > **Note**: > The directory itself is not copied, just its contents. @@ -628,16 +636,16 @@ Multiple `` resource may be specified but they must be relative to the source directory that is being built (the context of the build). Each `` may contain wildcards and matching will be done using Go's -[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. -For most command line uses this should act as expected, for example: +[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: COPY hom* /mydir/ # adds all files starting with "hom" - COPY hom?.txt /mydir/ # ? is replaced with any single character + COPY hom?.txt /mydir/ # ? is replaced with any single character, e.g., "home.txt" The `` is an absolute path, or a path relative to `WORKDIR`, into which the source will be copied inside the destination container. - COPY test aDir/ # adds "test" to `WORKDIR`/aDir/ + COPY test relativeDir/ # adds "test" to `WORKDIR`/relativeDir/ + COPY test /absoluteDir # adds "test" to /absoluteDir All new files and directories are created with a UID and GID of 0. @@ -645,7 +653,7 @@ All new files and directories are created with a UID and GID of 0. > If you build using STDIN (`docker build - < somefile`), there is no > build context, so `COPY` can't be used. -The copy obeys the following rules: +`COPY` obeys the following rules: - The `` path must be inside the *context* of the build; you cannot `COPY ../something /something`, because the first step of a @@ -654,6 +662,7 @@ The copy obeys the following rules: - If `` is a directory, the entire contents of the directory are copied, including filesystem metadata. + > **Note**: > The directory itself is not copied, just its contents. @@ -677,7 +686,7 @@ The copy obeys the following rules: ENTRYPOINT has two forms: - `ENTRYPOINT ["executable", "param1", "param2"]` - (the preferred *exec* form) + (*exec* form, preferred) - `ENTRYPOINT command param1 param2` (*shell* form) From dc5ec1af7e4599595954abd7ad9e4a7025fe6152 Mon Sep 17 00:00:00 2001 From: Aidan Hobson Sayers Date: Tue, 6 Oct 2015 22:58:23 +0100 Subject: [PATCH 021/152] Don't put dockerfiles in one continuous code block Signed-off-by: Aidan Hobson Sayers --- frontend/dockerfile/docs/reference.md | 69 ++++++++++++++------------- 1 file changed, 37 insertions(+), 32 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 7c3051153..1f558c7e1 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1166,45 +1166,50 @@ or a signal name in the format SIGNAME, for instance SIGKILL. ## Dockerfile examples - # Nginx - # - # VERSION 0.0.1 +``` +# Nginx +# +# VERSION 0.0.1 - FROM ubuntu - MAINTAINER Victor Vieux +FROM ubuntu +MAINTAINER Victor Vieux - LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products" Version="1.0" - RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server +LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products" Version="1.0" +RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server +``` - # Firefox over VNC - # - # VERSION 0.3 +``` +# Firefox over VNC +# +# VERSION 0.3 - FROM ubuntu +FROM ubuntu - # Install vnc, xvfb in order to create a 'fake' display and firefox - RUN apt-get update && apt-get install -y x11vnc xvfb firefox - RUN mkdir ~/.vnc - # Setup a password - RUN x11vnc -storepasswd 1234 ~/.vnc/passwd - # Autostart firefox (might not be the best way, but it does the trick) - RUN bash -c 'echo "firefox" >> /.bashrc' +# Install vnc, xvfb in order to create a 'fake' display and firefox +RUN apt-get update && apt-get install -y x11vnc xvfb firefox +RUN mkdir ~/.vnc +# Setup a password +RUN x11vnc -storepasswd 1234 ~/.vnc/passwd +# Autostart firefox (might not be the best way, but it does the trick) +RUN bash -c 'echo "firefox" >> /.bashrc' - EXPOSE 5900 - CMD ["x11vnc", "-forever", "-usepw", "-create"] +EXPOSE 5900 +CMD ["x11vnc", "-forever", "-usepw", "-create"] +``` - # Multiple images example - # - # VERSION 0.1 +``` +# Multiple images example +# +# VERSION 0.1 - FROM ubuntu - RUN echo foo > bar - # Will output something like ===> 907ad6c2736f +FROM ubuntu +RUN echo foo > bar +# Will output something like ===> 907ad6c2736f - FROM ubuntu - RUN echo moo > oink - # Will output something like ===> 695d7793cbe4 - - # You᾿ll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with - # /oink. +FROM ubuntu +RUN echo moo > oink +# Will output something like ===> 695d7793cbe4 +# You᾿ll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with +# /oink. +``` From 62262c82836d852578b736b409c16c35f1afe1f4 Mon Sep 17 00:00:00 2001 From: Aidan Hobson Sayers Date: Wed, 7 Oct 2015 11:45:46 +0100 Subject: [PATCH 022/152] Mention more realistic examples are available Signed-off-by: Aidan Hobson Sayers --- frontend/dockerfile/docs/reference.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 1f558c7e1..1e85f138b 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1166,6 +1166,9 @@ or a signal name in the format SIGNAME, for instance SIGKILL. ## Dockerfile examples +Below you can see some examples of Dockerfile syntax. If you're interested in +something more realistic, take a look at the list of [Dockerization examples](/examples/). + ``` # Nginx # From e5cf7efcfc29651129cf0d614159659aeaeca76f Mon Sep 17 00:00:00 2001 From: Grant Reaber Date: Wed, 7 Oct 2015 15:51:57 -0500 Subject: [PATCH 023/152] clarify dockerignore semantics Signed-off-by: Grant Reaber --- frontend/dockerfile/docs/reference.md | 102 ++++++++++++++++---------- 1 file changed, 63 insertions(+), 39 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 1e85f138b..34a4fef0e 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -186,66 +186,90 @@ that set `abc` to `bye`. ### .dockerignore file -If a file named `.dockerignore` exists in the root of `PATH`, then Docker -interprets it as a newline-separated list of exclusion patterns. Docker excludes -files or directories relative to `PATH` that match these exclusion patterns. If -there are any `.dockerignore` files in `PATH` subdirectories, Docker treats -them as normal files. +Before the docker CLI sends the context to the docker daemon, it looks +for a file named `.dockerignore` in the root directory of the context. +If this file exists, the CLI modifies the context to exclude files and +directories that match patterns in it. This helps to avoid +unnecessarily sending large or sensitive files and directories to the +daemon and potentially adding them to images using `ADD` or `COPY`. -Filepaths in `.dockerignore` are absolute with the current directory as the -root. Wildcards are allowed but the search is not recursive. Globbing (file name -expansion) is done using Go's -[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. +The CLI interprets the `.dockerignore` file as a newline-separated +list of patterns similar to the file globs of Unix shells. For the +purposes of matching, the root of the context is considered to be both +the working and the root directory. For example, the patterns +`/foo/bar` and `foo/bar` both exclude a file or directory named `bar` +in the `foo` subdirectory of `PATH` or in the root of the git +repository located at `URL`. Neither excludes anything else. -You can specify exceptions to exclusion rules. To do this, simply prefix a -pattern with an `!` (exclamation mark) in the same way you would in a -`.gitignore` file. Currently there is no support for regular expressions. -Formats like `[^temp*]` are ignored. - -The following is an example `.dockerignore` file: +Here is an example `.dockerignore` file: ``` */temp* */*/temp* temp? - *.md - !LICENSE.md ``` This file causes the following build behavior: | Rule | Behavior | |----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `*/temp*` | Exclude all files with names starting with`temp` in any subdirectory below the root directory. For example, a file named`/somedir/temporary.txt` is ignored. | -| `*/*/temp*` | Exclude files starting with name `temp` from any subdirectory that is two levels below the root directory. For example, the file `/somedir/subdir/temporary.txt` is ignored. | -| `temp?` | Exclude the files that match the pattern in the root directory. For example, the files `tempa`, `tempb` in the root directory are ignored. | -| `*.md ` | Exclude all markdown files in the root directory. | -| `!LICENSE.md` | Exception to the Markdown files exclusion. `LICENSE.md`is included in the build. | +| `*/temp*` | Exclude files and directories whose names start with `temp` in any immediate subdirectory of the root. For example, the plain file `/somedir/temporary.txt` is excluded, as is the directory `/somedir/temp`. | +| `*/*/temp*` | Exclude files and directories starting with `temp` from any subdirectory that is two levels below the root. For example, `/somedir/subdir/temporary.txt` is excluded. | +| `temp?` | Exclude files and directories in the root directory whose names are a one-character extension of `temp`. For example, `/tempa` and `/tempb` are excluded. -The placement of `!` exception rules influences the matching algorithm; the -last line of the `.dockerignore` that matches a particular file determines -whether it is included or excluded. In the above example, the `LICENSE.md` file -matches both the `*.md` and `!LICENSE.md` rule. If you reverse the lines in the -example: + +Matching is done using Go's +[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. A +preprocessing step removes leading and trailing whitespace and +eliminates `.` and `..` elements using Go's +[filepath.Clean](http://golang.org/pkg/path/filepath/#Clean). Lines +that are blank after preprocessing are ignored. + +Lines starting with `!` (exclamation mark) can be used to make exceptions +to exclusions. The following is an example `.dockerignore` file that +uses this mechanism: ``` - */temp* - */*/temp* - temp? - !LICENSE.md *.md + !README.md ``` -The build would exclude `LICENSE.md` because the last `*.md` rule adds all -Markdown files in the root directory back onto the ignore list. The -`!LICENSE.md` rule has no effect because the subsequent `*.md` rule overrides -it. +All markdown files *except* `README.md` are excluded from the context. -You can even use the `.dockerignore` file to ignore the `Dockerfile` and -`.dockerignore` files. This is useful if you are copying files from the root of -the build context into your new container but do not want to include the -`Dockerfile` or `.dockerignore` files (e.g. `ADD . /someDir/`). +The placement of `!` exception rules influences the behavior: the last +line of the `.dockerignore` that matches a particular file determines +whether it is included or excluded. Consider the following example: +``` + *.md + !README*.md + README-secret.md +``` + +No markdown files are included in the context except README files other than +`README-secret.md`. + +Now consider this example: + +``` + *.md + README-secret.md + !README*.md +``` + +All of the README files are included. The middle line has no effect because +`!README*.md` matches `README-secret.md` and comes last. + +You can even use the `.dockerignore` file to exclude the `Dockerfile` +and `.dockerignore` files. These files are still sent to the daemon +because it needs them to do its job. But the `ADD` and `COPY` commands +do not copy them to the the image. + +Finally, you may want to specify which files to include in the +context, rather than which to exclude. To achieve this, specify `*` as +the first pattern, followed by one or more `!` exception patterns. + +**Note**: For historical reasons, the pattern `.` is ignored. ## FROM From c3b646bc1899d91ae3dbe5ac3e24f2df9a1c44a9 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Fri, 9 Oct 2015 16:50:41 -0700 Subject: [PATCH 024/152] Enabled GitHub Flavored Markdown GitHub flavored markdown is now supported for links and images. Also, ran LinkChecker and FileResolver. Yay! Fixes from Spider check Output for docker/docker now goes into engine directory Signed-off-by: Mary Anthony --- frontend/dockerfile/docs/reference.md | 31 +++++++++++++-------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 34a4fef0e..f022d51d1 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -18,11 +18,11 @@ instructions in succession. This page describes the commands you can use in a `Dockerfile`. When you are done reading this page, refer to the [`Dockerfile` Best -Practices](/articles/dockerfile_best-practices) for a tip-oriented guide. +Practices](../articles/dockerfile_best-practices.md) for a tip-oriented guide. ## Usage -The [`docker build`](/reference/commandline/build/) command builds an image from +The [`docker build`](commandline/build.md) command builds an image from a `Dockerfile` and a *context*. The build's context is the files at a specified location `PATH` or `URL`. The `PATH` is a directory on your local filesystem. The `URL` is a the location of a Git repository. @@ -75,7 +75,7 @@ instructions. Whenever possible, Docker will re-use the intermediate images (cache), to accelerate the `docker build` process significantly. This is indicated by the `Using cache` message in the console output. -(For more information, see the [Build cache section](/articles/dockerfile_best-practices/#build-cache)) in the +(For more information, see the [Build cache section](../articles/dockerfile_best-practices.md#build-cache)) in the `Dockerfile` best practices guide: $ docker build -t SvenDowideit/ambassador . @@ -92,7 +92,7 @@ the `Using cache` message in the console output. Successfully built 1a5ffc17324d When you're done with your build, you're ready to look into [*Pushing a -repository to its registry*]( /userguide/dockerrepos/#contributing-to-docker-hub). +repository to its registry*](../userguide/dockerrepos.md#contributing-to-docker-hub). ## Format @@ -106,7 +106,7 @@ be UPPERCASE in order to distinguish them from arguments more easily. Docker runs the instructions in a `Dockerfile` in order. **The first instruction must be \`FROM\`** in order to specify the [*Base -Image*](/reference/glossary/#base-image) from which you are building. +Image*](glossary.md#base-image) from which you are building. Docker will treat lines that *begin* with `#` as a comment. A `#` marker anywhere else in the line will @@ -283,11 +283,10 @@ Or FROM @ -The `FROM` instruction sets the [*Base Image*](/reference/glossary/#base-image) +The `FROM` instruction sets the [*Base Image*](glossary.md#base-image) for subsequent instructions. As such, a valid `Dockerfile` must have `FROM` as its first instruction. The image can be any valid image – it is especially easy -to start by **pulling an image** from the [*Public Repositories*]( -/userguide/dockerrepos). +to start by **pulling an image** from the [*Public Repositories*](../userguide/dockerrepos.md). - `FROM` must be the first non-comment instruction in the `Dockerfile`. @@ -358,7 +357,7 @@ cache for `RUN` instructions can be invalidated by using the `--no-cache` flag, for example `docker build --no-cache`. See the [`Dockerfile` Best Practices -guide](/articles/dockerfile_best-practices/#build-cache) for more information. +guide](../articles/dockerfile_best-practices.md#build-cache) for more information. The cache for `RUN` instructions can be invalidated by `ADD` instructions. See [below](#add) for details. @@ -488,14 +487,14 @@ To view an image's labels, use the `docker inspect` command. The `EXPOSE` instructions informs Docker that the container will listen on the specified network ports at runtime. Docker uses this information to interconnect containers using links (see the [Docker User -Guide](/userguide/dockerlinks)) and to determine which ports to expose to the -host when [using the -P flag](/reference/run/#expose-incoming-ports). +Guide](../userguide/dockerlinks.md) and to determine which ports to expose to the +host when [using the -P flag](run.md#expose-incoming-ports). > **Note**: > `EXPOSE` doesn't define which ports can be exposed to the host or make ports > accessible from the host by default. To expose ports to the host, at runtime, -> [use the `-p` flag](/userguide/dockerlinks) or -> [the -P flag](/reference/run/#expose-incoming-ports). +> [use the `-p` flag](../userguide/dockerlinks.md) or +> [the -P flag](run.md#expose-incoming-ports). ## ENV @@ -595,7 +594,7 @@ of whether or not the file has changed and the cache should be updated. > following instructions from the Dockerfile if the contents of `` have > changed. This includes invalidating the cache for `RUN` instructions. > See the [`Dockerfile` Best Practices -guide](/articles/dockerfile_best-practices/#build-cache) for more information. +guide](../articles/dockerfile_best-practices.md#build-cache) for more information. `ADD` obeys the following rules: @@ -938,7 +937,7 @@ containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log /var/db`. For more information/examples and mounting instructions via the Docker client, refer to -[*Share Directories via Volumes*](/userguide/dockervolumes/#mount-a-host-directory-as-a-data-volume) +[*Share Directories via Volumes*](../userguide/dockervolumes.md#mount-a-host-directory-as-a-data-volume) documentation. The `docker run` command initializes the newly created volume with any data @@ -1191,7 +1190,7 @@ or a signal name in the format SIGNAME, for instance SIGKILL. ## Dockerfile examples Below you can see some examples of Dockerfile syntax. If you're interested in -something more realistic, take a look at the list of [Dockerization examples](/examples/). +something more realistic, take a look at the list of [Dockerization examples](../examples/). ``` # Nginx From 8dc156fe4d50546960e4fe81eb4844145c857484 Mon Sep 17 00:00:00 2001 From: Mike Brown Date: Mon, 12 Oct 2015 16:59:25 -0500 Subject: [PATCH 025/152] updating docs for EXPOSE option on run command; fixes #16634 Signed-off-by: Mike Brown --- frontend/dockerfile/docs/reference.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index f022d51d1..4a1050a86 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -484,17 +484,15 @@ To view an image's labels, use the `docker inspect` command. EXPOSE [...] -The `EXPOSE` instructions informs Docker that the container will listen on the -specified network ports at runtime. Docker uses this information to interconnect -containers using links (see the [Docker User -Guide](../userguide/dockerlinks.md) and to determine which ports to expose to the -host when [using the -P flag](run.md#expose-incoming-ports). - -> **Note**: -> `EXPOSE` doesn't define which ports can be exposed to the host or make ports -> accessible from the host by default. To expose ports to the host, at runtime, -> [use the `-p` flag](../userguide/dockerlinks.md) or -> [the -P flag](run.md#expose-incoming-ports). +The `EXPOSE` instruction informs Docker that the container listens on the +specified network ports at runtime. `EXPOSE` does not make the ports of the +container accessible to the host. To do that, you must use either the `-p` flag +to publish a range of ports or the `-P` flag to publish all of the exposed ports. +You can expose one port number and publish it externally under another number. + +Docker uses exposed and published ports to interconnect containers using links +(see [Linking containers together](../userguide/dockerlinks.md)) +and to set up port redirection on the host system when [using the -P flag](run.md#expose-incoming-ports). ## ENV From 4f9009332da152d3312f87ca1e2a438b215a7457 Mon Sep 17 00:00:00 2001 From: Aidan Hobson Sayers Date: Tue, 6 Oct 2015 11:43:06 +0100 Subject: [PATCH 026/152] Update ambassador image, use the socat -t option Signed-off-by: Aidan Hobson Sayers --- frontend/dockerfile/docs/reference.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 4a1050a86..c65f34c30 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -78,18 +78,20 @@ the `Using cache` message in the console output. (For more information, see the [Build cache section](../articles/dockerfile_best-practices.md#build-cache)) in the `Dockerfile` best practices guide: - $ docker build -t SvenDowideit/ambassador . - Uploading context 10.24 kB - Uploading context - Step 1 : FROM docker-ut - ---> cbba202fe96b - Step 2 : MAINTAINER SvenDowideit@home.org.au + $ docker build -t svendowideit/ambassador . + Sending build context to Docker daemon 15.36 kB + Step 0 : FROM alpine:3.2 + ---> 31f630c65071 + Step 1 : MAINTAINER SvenDowideit@home.org.au ---> Using cache - ---> 51182097be13 - Step 3 : CMD env | grep _TCP= | sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' | sh && top + ---> 2a1c91448f5f + Step 2 : RUN apk update && apk add socat && rm -r /var/cache/ ---> Using cache - ---> 1a5ffc17324d - Successfully built 1a5ffc17324d + ---> 21ed6e7fbb73 + Step 3 : CMD env | grep _TCP= | sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \& wait/' | sh + ---> Using cache + ---> 7ea8aef582cc + Successfully built 7ea8aef582cc When you're done with your build, you're ready to look into [*Pushing a repository to its registry*](../userguide/dockerrepos.md#contributing-to-docker-hub). From 342ddd8466f18d751d6b624cb0c7ffd23d73fed7 Mon Sep 17 00:00:00 2001 From: Shijiang Wei Date: Sun, 30 Aug 2015 21:48:03 +0800 Subject: [PATCH 027/152] Add ability to add multiple tags with docker build Signed-off-by: Shijiang Wei --- frontend/dockerfile/docs/reference.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index c65f34c30..b1ed35ded 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -62,6 +62,11 @@ the build succeeds: $ docker build -t shykes/myapp . +To tag the image into multiple repositories after the build, +add multiple `-t` parameters when you run the `build` command: + + $ docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest . + The Docker daemon runs the instructions in the `Dockerfile` one-by-one, committing the result of each instruction to a new image if necessary, before finally outputting the ID of your From 7406e179c4eee68e3b0dba8cc4cea3f8fb32fcee Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Wed, 30 Sep 2015 13:11:36 -0700 Subject: [PATCH 028/152] First pass at consolidating Removing old networking.md Updating dockernetworks.md with images Adding information on network plugins Adding blurb about links to docker networking Updating the working documentation Adding Overlay Getting Started Downplaying links by removing refs/examples, adding refs/examples for network. Updating getting started to reflect networks not links Pulling out old network material Updating per discussion with Madhu to add Default docs section Updating with bridge default Fix bad merge Updating with new cluster-advertise behavior Update working and NetworkSettings examples Correcting example for default bridge discovery behavior Entering comments Fixing broken Markdown Syntax Updating with comments Updating all the links Signed-off-by: Mary Anthony --- frontend/dockerfile/docs/reference.md | 88 ++++++++++++++------------- 1 file changed, 46 insertions(+), 42 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index b1ed35ded..5479bb001 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -43,7 +43,7 @@ Dockerfile. >**Warning**: Do not use your root directory, `/`, as the `PATH` as it causes >the build to transfer the entire contents of your hard drive to the Docker ->daemon. +>daemon. To use a file in the build context, the `Dockerfile` refers to the file specified in an instruction, for example, a `COPY` instruction. To increase the build's @@ -159,7 +159,7 @@ Example (parsed representation is displayed after the `#`): ADD . $foo # ADD . /bar COPY \$foo /quux # COPY $foo /quux -Environment variables are supported by the following list of instructions in +Environment variables are supported by the following list of instructions in the `Dockerfile`: * `ADD` @@ -177,7 +177,7 @@ as well as: * `ONBUILD` (when combined with one of the supported instructions above) > **Note**: -> prior to 1.4, `ONBUILD` instructions did **NOT** support environment +> prior to 1.4, `ONBUILD` instructions did **NOT** support environment > variable, even when combined with any of the instructions listed above. Environment variable substitution will use the same value for each variable @@ -187,7 +187,7 @@ throughout the entire command. In other words, in this example: ENV abc=bye def=$abc ENV ghi=$abc -will result in `def` having a value of `hello`, not `bye`. However, +will result in `def` having a value of `hello`, not `bye`. However, `ghi` will have a value of `bye` because it is not part of the same command that set `abc` to `bye`. @@ -354,13 +354,13 @@ RUN /bin/bash -c 'source $HOME/.bashrc ; echo $HOME' > Unlike the *shell* form, the *exec* form does not invoke a command shell. > This means that normal shell processing does not happen. For example, > `RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. -> If you want shell processing then either use the *shell* form or execute +> If you want shell processing then either use the *shell* form or execute > a shell directly, for example: `RUN [ "sh", "-c", "echo", "$HOME" ]`. The cache for `RUN` instructions isn't invalidated automatically during -the next build. The cache for an instruction like -`RUN apt-get dist-upgrade -y` will be reused during the next build. The -cache for `RUN` instructions can be invalidated by using the `--no-cache` +the next build. The cache for an instruction like +`RUN apt-get dist-upgrade -y` will be reused during the next build. The +cache for `RUN` instructions can be invalidated by using the `--no-cache` flag, for example `docker build --no-cache`. See the [`Dockerfile` Best Practices @@ -399,8 +399,8 @@ the executable, in which case you must specify an `ENTRYPOINT` instruction as well. > **Note**: -> If `CMD` is used to provide default arguments for the `ENTRYPOINT` -> instruction, both the `CMD` and `ENTRYPOINT` instructions should be specified +> If `CMD` is used to provide default arguments for the `ENTRYPOINT` +> instruction, both the `CMD` and `ENTRYPOINT` instructions should be specified > with the JSON array format. > **Note**: @@ -411,7 +411,7 @@ instruction as well. > Unlike the *shell* form, the *exec* form does not invoke a command shell. > This means that normal shell processing does not happen. For example, > `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. -> If you want shell processing then either use the *shell* form or execute +> If you want shell processing then either use the *shell* form or execute > a shell directly, for example: `CMD [ "sh", "-c", "echo", "$HOME" ]`. When used in the shell or exec formats, the `CMD` instruction sets the command @@ -461,7 +461,7 @@ An image can have more than one label. To specify multiple labels, Docker recommends combining labels into a single `LABEL` instruction where possible. Each `LABEL` instruction produces a new layer which can result in an inefficient image if you use many labels. This example results in a single image -layer. +layer. LABEL multi.label1="value1" multi.label2="value2" other="value3" @@ -470,7 +470,7 @@ The above can also be written as: LABEL multi.label1="value1" \ multi.label2="value2" \ other="value3" - + Labels are additive including `LABEL`s in `FROM` images. If Docker encounters a label/key that already exists, the new value overrides any previous labels with identical keys. @@ -494,12 +494,15 @@ To view an image's labels, use the `docker inspect` command. The `EXPOSE` instruction informs Docker that the container listens on the specified network ports at runtime. `EXPOSE` does not make the ports of the container accessible to the host. To do that, you must use either the `-p` flag -to publish a range of ports or the `-P` flag to publish all of the exposed ports. -You can expose one port number and publish it externally under another number. - -Docker uses exposed and published ports to interconnect containers using links -(see [Linking containers together](../userguide/dockerlinks.md)) -and to set up port redirection on the host system when [using the -P flag](run.md#expose-incoming-ports). +to publish a range of ports or the `-P` flag to publish all of the exposed +ports. You can expose one port number and publish it externally under another +number. + +To set up port redirection on the host system, see [using the -P +flag](run.md#expose-incoming-ports). The Docker network feature supports +creating networks without the need to expose ports within the network, for +detailed information see the [overview of this +feature](../userguide/networking/index.md)). ## ENV @@ -507,17 +510,18 @@ and to set up port redirection on the host system when [using the -P flag](run.m ENV = ... The `ENV` instruction sets the environment variable `` to the value -``. This value will be in the environment of all "descendent" `Dockerfile` -commands and can be [replaced inline](#environment-replacement) in many as well. +``. This value will be in the environment of all "descendent" +`Dockerfile` commands and can be [replaced inline](#environment-replacement) in +many as well. The `ENV` instruction has two forms. The first form, `ENV `, will set a single variable to a value. The entire string after the first -space will be treated as the `` - including characters such as +space will be treated as the `` - including characters such as spaces and quotes. -The second form, `ENV = ...`, allows for multiple variables to -be set at one time. Notice that the second form uses the equals sign (=) -in the syntax, while the first form does not. Like command line parsing, +The second form, `ENV = ...`, allows for multiple variables to +be set at one time. Notice that the second form uses the equals sign (=) +in the syntax, while the first form does not. Like command line parsing, quotes and backslashes can be used to include spaces within values. For example: @@ -531,7 +535,7 @@ and ENV myDog Rex The Dog ENV myCat fluffy -will yield the same net results in the final container, but the first form +will yield the same net results in the final container, but the first form is preferred because it produces a single cache layer. The environment variables set using `ENV` will persist when a container is run @@ -555,8 +559,8 @@ whitespace) The `ADD` instruction copies new files, directories or remote file URLs from `` and adds them to the filesystem of the container at the path ``. -Multiple `` resource may be specified but if they are files or -directories then they must be relative to the source directory that is +Multiple `` resource may be specified but if they are files or +directories then they must be relative to the source directory that is being built (the context of the build). Each `` may contain wildcards and matching will be done using Go's @@ -619,8 +623,8 @@ guide](../articles/dockerfile_best-practices.md#build-cache) for more informatio appropriate filename can be discovered in this case (`http://example.com` will not work). -- If `` is a directory, the entire contents of the directory are copied, - including filesystem metadata. +- If `` is a directory, the entire contents of the directory are copied, + including filesystem metadata. > **Note**: > The directory itself is not copied, just its contents. @@ -640,7 +644,7 @@ guide](../articles/dockerfile_best-practices.md#build-cache) for more informatio at `/base()`. - If multiple `` resources are specified, either directly or due to the - use of a wildcard, then `` must be a directory, and it must end with + use of a wildcard, then `` must be a directory, and it must end with a slash `/`. - If `` does not end with a trailing slash, it will be considered a @@ -688,8 +692,8 @@ All new files and directories are created with a UID and GID of 0. `docker build` is to send the context directory (and subdirectories) to the docker daemon. -- If `` is a directory, the entire contents of the directory are copied, - including filesystem metadata. +- If `` is a directory, the entire contents of the directory are copied, + including filesystem metadata. > **Note**: > The directory itself is not copied, just its contents. @@ -700,7 +704,7 @@ All new files and directories are created with a UID and GID of 0. at `/base()`. - If multiple `` resources are specified, either directly or due to the - use of a wildcard, then `` must be a directory, and it must end with + use of a wildcard, then `` must be a directory, and it must end with a slash `/`. - If `` does not end with a trailing slash, it will be considered a @@ -729,7 +733,7 @@ Command line arguments to `docker run ` will be appended after all elements in an *exec* form `ENTRYPOINT`, and will override all elements specified using `CMD`. This allows arguments to be passed to the entry point, i.e., `docker run -d` -will pass the `-d` argument to the entry point. +will pass the `-d` argument to the entry point. You can override the `ENTRYPOINT` instruction using the `docker run --entrypoint` flag. @@ -760,10 +764,10 @@ When you run the container, you can see that `top` is the only process: %Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.7 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st KiB Mem: 2056668 total, 1616832 used, 439836 free, 99352 buffers KiB Swap: 1441840 total, 0 used, 1441840 free. 1324440 cached Mem - + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND 1 root 20 0 19744 2336 2080 R 0.0 0.1 0:00.04 top - + To examine the result further, you can use `docker exec`: $ docker exec -it test ps aux @@ -867,7 +871,7 @@ sys 0m 0.03s > Unlike the *shell* form, the *exec* form does not invoke a command shell. > This means that normal shell processing does not happen. For example, > `ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. -> If you want shell processing then either use the *shell* form or execute +> If you want shell processing then either use the *shell* form or execute > a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo", "$HOME" ]`. > Variables that are defined in the `Dockerfile`using `ENV`, will be substituted by > the `Dockerfile` parser. @@ -941,12 +945,12 @@ and marks it as holding externally mounted volumes from native host or other containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log /var/db`. For more information/examples and mounting instructions via the -Docker client, refer to +Docker client, refer to [*Share Directories via Volumes*](../userguide/dockervolumes.md#mount-a-host-directory-as-a-data-volume) documentation. -The `docker run` command initializes the newly created volume with any data -that exists at the specified location within the base image. For example, +The `docker run` command initializes the newly created volume with any data +that exists at the specified location within the base image. For example, consider the following Dockerfile snippet: FROM ubuntu @@ -955,7 +959,7 @@ consider the following Dockerfile snippet: VOLUME /myvol This Dockerfile results in an image that causes `docker run`, to -create a new mount point at `/myvol` and copy the `greeting` file +create a new mount point at `/myvol` and copy the `greeting` file into the newly created volume. > **Note**: From 56c36e3abf718b69e38875304cf7bf36d934019a Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Wed, 14 Oct 2015 14:42:21 -0700 Subject: [PATCH 029/152] Support multi-dir wildcards in .dockerignore Closes #13113 Signed-off-by: Doug Davis --- frontend/dockerfile/docs/reference.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 5479bb001..7c0e54d24 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -232,6 +232,11 @@ eliminates `.` and `..` elements using Go's [filepath.Clean](http://golang.org/pkg/path/filepath/#Clean). Lines that are blank after preprocessing are ignored. +Beyond Go's filepath.Match rules, Docker also supports a special +wildcard string `**` that matches any number of directories (including +zero). For example, `**/*.go` will exclude all files that end with `.go` +that are found in all directories, including the root of the build context. + Lines starting with `!` (exclamation mark) can be used to make exceptions to exclusions. The following is an example `.dockerignore` file that uses this mechanism: From 60176d93b11d039741ea5e99c05bb9b28443ecbc Mon Sep 17 00:00:00 2001 From: Sven Dowideit Date: Mon, 23 Nov 2015 11:15:39 +1000 Subject: [PATCH 030/152] Fixes found by docs validation tool Signed-off-by: Sven Dowideit --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 7c0e54d24..55c006258 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1204,7 +1204,7 @@ or a signal name in the format SIGNAME, for instance SIGKILL. ## Dockerfile examples Below you can see some examples of Dockerfile syntax. If you're interested in -something more realistic, take a look at the list of [Dockerization examples](../examples/). +something more realistic, take a look at the list of [Dockerization examples](../examples/index.md). ``` # Nginx From 49e0a7f933fd1ebfc17da4a4be21617526defe76 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Mon, 23 Nov 2015 03:08:21 -0800 Subject: [PATCH 031/152] Add some docs about build-arg's impact on the cache Closes #18017 Signed-off-by: Doug Davis --- frontend/dockerfile/docs/reference.md | 36 ++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 55c006258..5663e837a 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -562,7 +562,7 @@ ADD has two forms: whitespace) The `ADD` instruction copies new files, directories or remote file URLs from `` -and adds them to the filesystem of the container at the path ``. +and adds them to the filesystem of the container at the path ``. Multiple `` resource may be specified but if they are files or directories then they must be relative to the source directory that is @@ -1135,6 +1135,40 @@ corresponding `ARG` instruction in the Dockerfile. To use these, simply pass them on the command line using the `--build-arg =` flag. +### Impact on build caching + +`ARG` variables are not persisted into the built image as `ENV` variables are. +However, `ARG` variables do impact the build cache in similar ways. If a +Dockerfile defines an `ARG` variable whose value is different from a previous +build, then a "cache miss" occurs upon its first usage, not its declaration. +For example, consider this Dockerfile: + +``` +1 FROM ubuntu +2 ARG CONT_IMG_VER +3 RUN echo $CONT_IMG_VER +``` + +If you specify `--build-arg CONT_IMG_VER=` on the command line the +specification on line 2 does not cause a cache miss; line 3 does cause a cache +miss. The definition on line 2 has no impact on the resulting image. The `RUN` +on line 3 executes a command and in doing so defines a set of environment +variables, including `CONT_IMG_VER`. At that point, the `ARG` variable may +impact the resulting image, so a cache miss occurs. + +Consider another example under the same command line: + +``` +1 FROM ubuntu +2 ARG CONT_IMG_VER +3 ENV CONT_IMG_VER $CONT_IMG_VER +4 RUN echo $CONT_IMG_VER +``` +In this example, the cache miss occurs on line 3. The miss happens because +the variable's value in the `ENV` references the `ARG` variable and that +variable is changed through the command line. In this example, the `ENV` +command causes the image to include the value. + ## ONBUILD ONBUILD [INSTRUCTION] From d048033ec2855b36705574a47b3d0b2be288c346 Mon Sep 17 00:00:00 2001 From: Aidan Hobson Sayers Date: Fri, 8 Jan 2016 20:52:11 +0000 Subject: [PATCH 032/152] Fix ambassador script based on SvenDowideit/dockerfiles#37 Signed-off-by: Aidan Hobson Sayers --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 5663e837a..355c5e376 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -93,7 +93,7 @@ the `Using cache` message in the console output. Step 2 : RUN apk update && apk add socat && rm -r /var/cache/ ---> Using cache ---> 21ed6e7fbb73 - Step 3 : CMD env | grep _TCP= | sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \& wait/' | sh + Step 3 : CMD env | grep _TCP= | (sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' && echo wait) | sh ---> Using cache ---> 7ea8aef582cc Successfully built 7ea8aef582cc From 813ab5c55d66b3328653f1efcb46014bb1c9e284 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Fri, 22 Jan 2016 08:52:36 -0800 Subject: [PATCH 033/152] Add some helper text for magical ADD Closes: #15777 Signed-off-by: Doug Davis --- frontend/dockerfile/docs/reference.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 355c5e376..8d9aeda17 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -643,6 +643,14 @@ guide](../articles/dockerfile_best-practices.md#build-cache) for more informatio 2. The contents of the source tree, with conflicts resolved in favor of "2." on a file-by-file basis. + > **Note**: + > Whether a file is identified as a recognized compression format or not + > is done soley based on the contents of the file, not the name of the file. + > For example, if an empty file happens to end with `.tar.gz` this will not + > be recognized as a compressed file and **will not** generate any kind of + > decompression error message, rather the file will simply be copied to the + > destination. + - If `` is any other kind of file, it is copied individually along with its metadata. In this case, if `` ends with a trailing slash `/`, it will be considered a directory and the contents of `` will be written From 6ad3d910d1ebb53197aed12a3ecebbceda3cb7b1 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Sat, 23 Jan 2016 20:36:40 -0800 Subject: [PATCH 034/152] Creating Engine specific menu Fixing the links Updating with Seb's comments Adding weight Fixing the engine aliases Updating after Arun pushed Removing empty file Signed-off-by: Mary Anthony --- frontend/dockerfile/docs/reference.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 8d9aeda17..79036e39b 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -4,7 +4,8 @@ title = "Dockerfile reference" description = "Dockerfiles use a simple DSL which allows you to automate the steps you would normally manually take to create an image." keywords = ["builder, docker, Dockerfile, automation, image creation"] [menu.main] -parent = "mn_reference" +parent = "engine_ref" +weight=-90 +++ @@ -18,7 +19,7 @@ instructions in succession. This page describes the commands you can use in a `Dockerfile`. When you are done reading this page, refer to the [`Dockerfile` Best -Practices](../articles/dockerfile_best-practices.md) for a tip-oriented guide. +Practices](../userguide/eng-image/dockerfile_best-practices.md) for a tip-oriented guide. ## Usage @@ -80,7 +81,7 @@ instructions. Whenever possible, Docker will re-use the intermediate images (cache), to accelerate the `docker build` process significantly. This is indicated by the `Using cache` message in the console output. -(For more information, see the [Build cache section](../articles/dockerfile_best-practices.md#build-cache)) in the +(For more information, see the [Build cache section](../userguide/eng-image/dockerfile_best-practices.md#build-cache)) in the `Dockerfile` best practices guide: $ docker build -t svendowideit/ambassador . @@ -99,7 +100,7 @@ the `Using cache` message in the console output. Successfully built 7ea8aef582cc When you're done with your build, you're ready to look into [*Pushing a -repository to its registry*](../userguide/dockerrepos.md#contributing-to-docker-hub). +repository to its registry*](../userguide/containers/dockerrepos.md#contributing-to-docker-hub). ## Format @@ -298,7 +299,7 @@ Or The `FROM` instruction sets the [*Base Image*](glossary.md#base-image) for subsequent instructions. As such, a valid `Dockerfile` must have `FROM` as its first instruction. The image can be any valid image – it is especially easy -to start by **pulling an image** from the [*Public Repositories*](../userguide/dockerrepos.md). +to start by **pulling an image** from the [*Public Repositories*](../userguide/containers/dockerrepos.md). - `FROM` must be the first non-comment instruction in the `Dockerfile`. @@ -369,7 +370,7 @@ cache for `RUN` instructions can be invalidated by using the `--no-cache` flag, for example `docker build --no-cache`. See the [`Dockerfile` Best Practices -guide](../articles/dockerfile_best-practices.md#build-cache) for more information. +guide](../userguide/eng-image/dockerfile_best-practices.md#build-cache) for more information. The cache for `RUN` instructions can be invalidated by `ADD` instructions. See [below](#add) for details. @@ -608,7 +609,7 @@ of whether or not the file has changed and the cache should be updated. > following instructions from the Dockerfile if the contents of `` have > changed. This includes invalidating the cache for `RUN` instructions. > See the [`Dockerfile` Best Practices -guide](../articles/dockerfile_best-practices.md#build-cache) for more information. +guide](../userguide/eng-image/dockerfile_best-practices.md#build-cache) for more information. `ADD` obeys the following rules: @@ -959,7 +960,7 @@ containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log /var/db`. For more information/examples and mounting instructions via the Docker client, refer to -[*Share Directories via Volumes*](../userguide/dockervolumes.md#mount-a-host-directory-as-a-data-volume) +[*Share Directories via Volumes*](../userguide/containers/dockervolumes.md#mount-a-host-directory-as-a-data-volume) documentation. The `docker run` command initializes the newly created volume with any data From 35b4bdefb80338c27f0f297c175b0e3dab42f21c Mon Sep 17 00:00:00 2001 From: Prayag Verma Date: Mon, 1 Feb 2016 01:25:59 +0530 Subject: [PATCH 035/152] Fix typo Signed-off-by: Prayag Verma --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 79036e39b..3b9a6d5ea 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -276,7 +276,7 @@ All of the README files are included. The middle line has no effect because You can even use the `.dockerignore` file to exclude the `Dockerfile` and `.dockerignore` files. These files are still sent to the daemon because it needs them to do its job. But the `ADD` and `COPY` commands -do not copy them to the the image. +do not copy them to the image. Finally, you may want to specify which files to include in the context, rather than which to exclude. To achieve this, specify `*` as From ffc3fdc15442a9638f7cab7403407eb6deb337c7 Mon Sep 17 00:00:00 2001 From: Victor Vieux Date: Thu, 11 Feb 2016 15:21:52 -0800 Subject: [PATCH 036/152] fix common misspell Signed-off-by: Victor Vieux --- frontend/dockerfile/docs/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 3b9a6d5ea..9b5cfdaf7 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -516,7 +516,7 @@ feature](../userguide/networking/index.md)). ENV = ... The `ENV` instruction sets the environment variable `` to the value -``. This value will be in the environment of all "descendent" +``. This value will be in the environment of all "descendant" `Dockerfile` commands and can be [replaced inline](#environment-replacement) in many as well. @@ -646,7 +646,7 @@ guide](../userguide/eng-image/dockerfile_best-practices.md#build-cache) for more > **Note**: > Whether a file is identified as a recognized compression format or not - > is done soley based on the contents of the file, not the name of the file. + > is done solely based on the contents of the file, not the name of the file. > For example, if an empty file happens to end with `.tar.gz` this will not > be recognized as a compressed file and **will not** generate any kind of > decompression error message, rather the file will simply be copied to the From 3e439bc04d9d6add17869750de24d35392361f9f Mon Sep 17 00:00:00 2001 From: Bastiaan Bakker Date: Tue, 16 Feb 2016 22:36:51 +0100 Subject: [PATCH 037/152] add missing trailing slash in ADD and COPY /absoluteDir examples. According to the specs they are mandatory. Signed-off-by: Bastiaan Bakker --- frontend/dockerfile/docs/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 9b5cfdaf7..5dfb7f09f 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -579,7 +579,7 @@ The `` is an absolute path, or a path relative to `WORKDIR`, into which the source will be copied inside the destination container. ADD test relativeDir/ # adds "test" to `WORKDIR`/relativeDir/ - ADD test /absoluteDir # adds "test" to /absoluteDir + ADD test /absoluteDir/ # adds "test" to /absoluteDir/ All new files and directories are created with a UID and GID of 0. @@ -691,7 +691,7 @@ The `` is an absolute path, or a path relative to `WORKDIR`, into which the source will be copied inside the destination container. COPY test relativeDir/ # adds "test" to `WORKDIR`/relativeDir/ - COPY test /absoluteDir # adds "test" to /absoluteDir + COPY test /absoluteDir/ # adds "test" to /absoluteDir/ All new files and directories are created with a UID and GID of 0. From 336df57699a56c13e320771a0b8a7da09edc6250 Mon Sep 17 00:00:00 2001 From: Tomasz Kopczynski Date: Tue, 23 Feb 2016 22:03:45 +0100 Subject: [PATCH 038/152] Docs: add note about CMD and ENTRYPOINT commands Signed-off-by: Tomasz Kopczynski --- frontend/dockerfile/docs/reference.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 5dfb7f09f..8a01d41d5 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -950,6 +950,29 @@ If you then run `docker stop test`, the container will not exit cleanly - the user 0m 0.04s sys 0m 0.03s +### Understand how CMD and ENTRYPOINT interact + +Both `CMD` and `ENTRYPOINT` instructions define what command gets executed when running a container. +There are few rules that describe their co-operation. + +1. Dockerfile should specify at least one of `CMD` or `ENTRYPOINT` commands. + +2. `ENTRYPOINT` should be defined when using the container as an executable. + +3. `CMD` should be used as a way of defining default arguments for an `ENTRYPOINT` command +or for executing an ad-hoc command in a container. + +4. `CMD` will be overridden when running the container with alternative arguments. + +The table below shows what command is executed for different `ENTRYPOINT` / `CMD` combinations: + +| | No ENTRYPOINT | ENTRYPOINT exec_entry p1_entry | ENTRYPOINT ["exec_entry", "p1_entry"] | +|--------------------------------|----------------------------|-----------------------------------------------------------|------------------------------------------------| +| **No CMD** | *error, not allowed* | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry | +| **CMD ["exec_cmd", "p1_cmd"]** | exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry exec_cmd p1_cmd | exec_entry p1_entry exec_cmd p1_cmd | +| **CMD ["p1_cmd", "p2_cmd"]** | p1_cmd p2_cmd | /bin/sh -c exec_entry p1_entry p1_cmd p2_cmd | exec_entry p1_entry p1_cmd p2_cmd | +| **CMD exec_cmd p1_cmd** | /bin/sh -c exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry /bin/sh -c exec_cmd p1_cmd | exec_entry p1_entry /bin/sh -c exec_cmd p1_cmd | + ## VOLUME VOLUME ["/data"] From 437dd08647e390badd4ad17e610105d9be6827f6 Mon Sep 17 00:00:00 2001 From: Sven Dowideit Date: Sat, 19 Mar 2016 22:20:40 +1000 Subject: [PATCH 039/152] WORKDIR is like calling mkdir - but we've not told people Signed-off-by: Sven Dowideit --- frontend/dockerfile/docs/reference.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 8a01d41d5..5819ea36f 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1021,6 +1021,8 @@ and for any `RUN`, `CMD` and `ENTRYPOINT` instructions that follow it in the The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY` and `ADD` instructions that follow it in the `Dockerfile`. +If the `WORKDIR` doesn't exist, it will be created even if its not used in any +subsequent `Dockerfile` instruction. It can be used multiple times in the one `Dockerfile`. If a relative path is provided, it will be relative to the path of the previous `WORKDIR` From a6081b4e3b7df529f5db1f3fe82dcb4c4b753862 Mon Sep 17 00:00:00 2001 From: mikelinjie <294893458@qq.com> Date: Wed, 16 Mar 2016 15:26:57 +0800 Subject: [PATCH 040/152] make the cache miss clear Signed-off-by: mikelinjie <294893458@qq.com> Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 37 +++++++++++++++++++++------ 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 5819ea36f..a932276b7 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1174,8 +1174,10 @@ To use these, simply pass them on the command line using the `--build-arg `ARG` variables are not persisted into the built image as `ENV` variables are. However, `ARG` variables do impact the build cache in similar ways. If a Dockerfile defines an `ARG` variable whose value is different from a previous -build, then a "cache miss" occurs upon its first usage, not its declaration. -For example, consider this Dockerfile: +build, then a "cache miss" occurs upon first use of the `ARG` variable. The +declaration of the `ARG` variable does not count as a use. + +For example, consider these two Dockerfile: ``` 1 FROM ubuntu @@ -1183,12 +1185,17 @@ For example, consider this Dockerfile: 3 RUN echo $CONT_IMG_VER ``` -If you specify `--build-arg CONT_IMG_VER=` on the command line the -specification on line 2 does not cause a cache miss; line 3 does cause a cache -miss. The definition on line 2 has no impact on the resulting image. The `RUN` -on line 3 executes a command and in doing so defines a set of environment -variables, including `CONT_IMG_VER`. At that point, the `ARG` variable may -impact the resulting image, so a cache miss occurs. +``` +1 FROM ubuntu +2 ARG CONT_IMG_VER +3 RUN echo hello +``` + +If you specify `--build-arg CONT_IMG_VER=` on the command line, in both +cases, the specification on line 2 does not cause a cache miss; line 3 does +cause a cache miss.`ARG CONT_IMG_VER` causes the RUN line to be identified +as the same as running `CONT_IMG_VER=` echo hello, so if the `` +changes, we get a cache miss. Consider another example under the same command line: @@ -1203,6 +1210,20 @@ the variable's value in the `ENV` references the `ARG` variable and that variable is changed through the command line. In this example, the `ENV` command causes the image to include the value. +If an `ENV` instruction overrides an `ARG` instruction of the same name, like +this Dockerfile: + +``` +1 FROM ubuntu +2 ARG CONT_IMG_VER +3 ENV CONT_IMG_VER hello +4 RUN echo $CONT_IMG_VER +``` + +Line 3 does not cause a cache miss because the value of `CONT_IMG_VER` is a +constant (`hello`). As a result, the environment variables and values used on +the `RUN` (line 4) doesn't change between builds. + ## ONBUILD ONBUILD [INSTRUCTION] From 9136e941e4c6fad292bff3127515e209d99b9063 Mon Sep 17 00:00:00 2001 From: Thomas Riccardi Date: Fri, 8 Apr 2016 11:23:48 +0200 Subject: [PATCH 041/152] Improve build cache miss doc for `ARG` and `RUN` The documentation already says the cache miss happens only at `ARG` variable usage, not declaration, but there is a very common implicit usage: `RUN`, which this commit documents even more, improving on #21790. Also, use `definition` instead of `declaration`: it's the same thing, and `definition` is already used in this documentation, contrary to `declaration`. Also, distinguish between "instructions" and "variables defined by `ARG` instructions". Signed-off-by: Thomas Riccardi --- frontend/dockerfile/docs/reference.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index a932276b7..f1838ee0e 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1174,8 +1174,9 @@ To use these, simply pass them on the command line using the `--build-arg `ARG` variables are not persisted into the built image as `ENV` variables are. However, `ARG` variables do impact the build cache in similar ways. If a Dockerfile defines an `ARG` variable whose value is different from a previous -build, then a "cache miss" occurs upon first use of the `ARG` variable. The -declaration of the `ARG` variable does not count as a use. +build, then a "cache miss" occurs upon its first usage, not its definition. In +particular, all `RUN` instructions following an `ARG` instruction use the `ARG` +variable implicitly (as an environment variable), thus can cause a cache miss. For example, consider these two Dockerfile: From 8e22645abfe90462ff8d5349cbc2f033a12e0287 Mon Sep 17 00:00:00 2001 From: kevinmeredith Date: Wed, 11 May 2016 14:49:24 -0400 Subject: [PATCH 042/152] Correct docs for a docker container's clean-up. The 'Unix Signals' (https://en.wikipedia.org/wiki/Unix_signal#Handling_signals) wiki explains that: > 'There are two signals which cannot be intercepted and handled: SIGKILL and SIGSTOP.' Signed-off-by: kevinmeredith --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index f1838ee0e..2da885d30 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -834,7 +834,7 @@ does some more work: # USE the trap if you need to also do manual cleanup after the service is stopped, # or need to start multiple services in the one container -trap "echo TRAPed signal" HUP INT QUIT KILL TERM +trap "echo TRAPed signal" HUP INT QUIT TERM # start service in background here /usr/sbin/apachectl start From 1eb917aa986feaa39fbd3cfecde20c3baa4f417a Mon Sep 17 00:00:00 2001 From: Charles Law Date: Fri, 13 May 2016 10:55:36 -0700 Subject: [PATCH 043/152] Fix error for env variables example in docker reference Signed-off-by: Charles Law --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 2da885d30..49e33cc1c 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -361,7 +361,7 @@ RUN /bin/bash -c 'source $HOME/.bashrc ; echo $HOME' > This means that normal shell processing does not happen. For example, > `RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. > If you want shell processing then either use the *shell* form or execute -> a shell directly, for example: `RUN [ "sh", "-c", "echo", "$HOME" ]`. +> a shell directly, for example: `RUN [ "sh", "-c", "echo $HOME" ]`. The cache for `RUN` instructions isn't invalidated automatically during the next build. The cache for an instruction like From 650ab6b9bafac6d08a72919ea88ac2e2528ae5c2 Mon Sep 17 00:00:00 2001 From: John Howard Date: Fri, 20 May 2016 20:56:08 -0700 Subject: [PATCH 044/152] Docs: JSON vs Shell clarification Signed-off-by: John Howard --- frontend/dockerfile/docs/reference.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 49e33cc1c..6ed7fe661 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -362,6 +362,15 @@ RUN /bin/bash -c 'source $HOME/.bashrc ; echo $HOME' > `RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. > If you want shell processing then either use the *shell* form or execute > a shell directly, for example: `RUN [ "sh", "-c", "echo $HOME" ]`. +> +> **Note**: +> In the *JSON* form, it is necessary to escape backslashes. This is +> particularly relevant on Windows where the backslash is the path seperator. +> The following line would otherwise be treated as *shell* form due to not +> being valid JSON, and fail in an unexpected way: +> `RUN ["c:\windows\system32\tasklist.exe"]` +> The correct syntax for this example is: +> `RUN ["c:\\windows\\system32\\tasklist.exe"]` The cache for `RUN` instructions isn't invalidated automatically during the next build. The cache for an instruction like From afc5e6bed8f16be4b135ba4d009f3c360588aa4f Mon Sep 17 00:00:00 2001 From: John Howard Date: Fri, 22 Apr 2016 15:04:46 -0700 Subject: [PATCH 045/152] Support platform file paths through escape Signed-off-by: John Howard --- frontend/dockerfile/docs/reference.md | 202 ++++++++++++++++++++++++-- 1 file changed, 186 insertions(+), 16 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 6ed7fe661..863dcd36c 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -106,27 +106,197 @@ repository to its registry*](../userguide/containers/dockerrepos.md#contributing Here is the format of the `Dockerfile`: - # Comment - INSTRUCTION arguments +```Dockerfile +# Comment +INSTRUCTION arguments +``` -The instruction is not case-sensitive, however convention is for them to -be UPPERCASE in order to distinguish them from arguments more easily. +The instruction is not case-sensitive. However, convention is for them to +be UPPERCASE to distinguish them from arguments more easily. -Docker runs the instructions in a `Dockerfile` in order. **The -first instruction must be \`FROM\`** in order to specify the [*Base -Image*](glossary.md#base-image) from which you are building. -Docker will treat lines that *begin* with `#` as a -comment. A `#` marker anywhere else in the line will -be treated as an argument. This allows statements like: +Docker runs instructions in a `Dockerfile` in order. **The first +instruction must be \`FROM\`** in order to specify the [*Base +Image*](glossary.md#base-image) from which you are building. - # Comment - RUN echo 'we are running some # of cool things' +Docker treats lines that *begin* with `#` as a comment, unless the line is +a valid [parser directive](builder.md#parser directives). A `#` marker anywhere +else in a line is treated as an argument. This allows statements like: -Here is the set of instructions you can use in a `Dockerfile` for building -images. +```Dockerfile +# Comment +RUN echo 'we are running some # of cool things' +``` -### Environment replacement +Line continuation characters are not supported in comments. + +## Parser directives + +Parser directives are optional, and affect the way in which subsequent lines +in a `Dockerfile` are handled. Parser directives do not add layers to the build, +and will not be shown as a build step. Parser directives are written as a +special type of comment in the form `# directive=value`. A single directive +may only be used once. + +Once a comment, empty line or builder instruction has been processed, Docker +no longer looks for parser directives. Instead it treats anything formatted +as a parser directive as a comment and does not attempt to validate if it might +be a parser directive. Therefore, all parser directives must be at the very +top of a `Dockerfile`. + +Parser directives are not case-sensitive. However, convention is for them to +be lowercase. Convention is also to include a blank line following any +parser directives. Line continuation characters are not supported in parser +directives. + +Due to these rules, the following examples are all invalid: + +Invalid due to line continuation: + +```Dockerfile +# direc \ +tive=value +``` + +Invalid due to appearing twice: + +```Dockerfile +# directive=value1 +# directive=value2 + +FROM ImageName +``` + +Treated as a comment due to appearing after a builder instruction: + +```Dockerfile +FROM ImageName +# directive=value +``` + +Treated as a comment due to appearing after a comment which is not a parser +directive: + +```Dockerfile +# About my dockerfile +FROM ImageName +# directive=value +``` + +The unknown directive is treated as a comment due to not being recognized. In +addition, the known directive is treated as a comment due to appearing after +a comment which is not a parser directive. + +```Dockerfile +# unknowndirective=value +# knowndirective=value +``` + +Non line-breaking whitespace is permitted in a parser directive. Hence, the +following lines are all treated identically: + +```Dockerfile +#directive=value +# directive =value +# directive= value +# directive = value +# dIrEcTiVe=value +``` + +The following parser directive is supported: + +* `escape` + +## escape + + # escape=\ (backslash) + +Or + + # escape=` (backtick) + +The `escape` directive sets the character used to escape characters in a +`Dockerfile`. If not specified, the default escape character is `\`. + +The escape character is used both to escape characters in a line, and to +escape a newline. This allows a `Dockerfile` instruction to +span multiple lines. Note that regardless of whether the `escape` parser +directive is included in a `Dockerfile`, *escaping is not performed in +a `RUN` command, except at the end of a line.* + +Setting the escape character to `` ` `` is especially useful on +`Windows`, where `\` is the directory path separator. `` ` `` is consistent +with [Windows PowerShell](https://technet.microsoft.com/en-us/library/hh847755.aspx). + +Consider the following example which would fail in a non-obvious way on +`Windows`. The second `\` at the end of the second line would be interpreted as an +escape for the newline, instead of a target of the escape from the first `\`. +Similarly, the `\` at the end of the third line would, assuming it was actually +handled as an instruction, cause it be treated as a line continuation. The result +of this dockerfile is that second and third lines are considered a single +instruction: + +```Dockerfile +FROM windowsservercore +COPY testfile.txt c:\\ +RUN dir c:\ +``` + +Results in: + + PS C:\John> docker build -t cmd . + Sending build context to Docker daemon 3.072 kB + Step 1 : FROM windowsservercore + ---> dbfee88ee9fd + Step 2 : COPY testfile.txt c:RUN dir c: + GetFileAttributesEx c:RUN: The system cannot find the file specified. + PS C:\John> + +One solution to the above would be to use `/` as the target of both the `COPY` +instruction, and `dir`. However, this syntax is, at best, confusing as it is not +natural for paths on `Windows`, and at worst, error prone as not all commands on +`Windows` support `/` as the path separator. + +By adding the `escape` parser directive, the following `Dockerfile` succeeds as +expected with the use of natural platform semantics for file paths on `Windows`: + + # escape=` + + FROM windowsservercore + COPY testfile.txt c:\ + RUN dir c:\ + +Results in: + + PS C:\John> docker build -t succeeds --no-cache=true . + Sending build context to Docker daemon 3.072 kB + Step 1 : FROM windowsservercore + ---> dbfee88ee9fd + Step 2 : COPY testfile.txt c:\ + ---> 99ceb62e90df + Removing intermediate container 62afbe726221 + Step 3 : RUN dir c:\ + ---> Running in a5ff53ad6323 + Volume in drive C has no label. + Volume Serial Number is 1440-27FA + + Directory of c:\ + + 03/25/2016 05:28 AM inetpub + 03/25/2016 04:22 AM PerfLogs + 04/22/2016 10:59 PM Program Files + 03/25/2016 04:22 AM Program Files (x86) + 04/18/2016 09:26 AM 4 testfile.txt + 04/22/2016 10:59 PM Users + 04/22/2016 10:59 PM Windows + 1 File(s) 4 bytes + 6 Dir(s) 21,252,689,920 bytes free + ---> 2569aa19abef + Removing intermediate container a5ff53ad6323 + Successfully built 2569aa19abef + PS C:\John> + +## Environment replacement Environment variables (declared with [the `ENV` statement](#env)) can also be used in certain instructions as variables to be interpreted by the @@ -192,7 +362,7 @@ will result in `def` having a value of `hello`, not `bye`. However, `ghi` will have a value of `bye` because it is not part of the same command that set `abc` to `bye`. -### .dockerignore file +## .dockerignore file Before the docker CLI sends the context to the docker daemon, it looks for a file named `.dockerignore` in the root directory of the context. From 134237b2be2f7688fcf1e627e4fcec901e0c1233 Mon Sep 17 00:00:00 2001 From: Thomas Leonard Date: Mon, 18 Apr 2016 10:48:13 +0100 Subject: [PATCH 046/152] Add support for user-defined healthchecks This PR adds support for user-defined health-check probes for Docker containers. It adds a `HEALTHCHECK` instruction to the Dockerfile syntax plus some corresponding "docker run" options. It can be used with a restart policy to automatically restart a container if the check fails. The `HEALTHCHECK` instruction has two forms: * `HEALTHCHECK [OPTIONS] CMD command` (check container health by running a command inside the container) * `HEALTHCHECK NONE` (disable any healthcheck inherited from the base image) The `HEALTHCHECK` instruction tells Docker how to test a container to check that it is still working. This can detect cases such as a web server that is stuck in an infinite loop and unable to handle new connections, even though the server process is still running. When a container has a healthcheck specified, it has a _health status_ in addition to its normal status. This status is initially `starting`. Whenever a health check passes, it becomes `healthy` (whatever state it was previously in). After a certain number of consecutive failures, it becomes `unhealthy`. The options that can appear before `CMD` are: * `--interval=DURATION` (default: `30s`) * `--timeout=DURATION` (default: `30s`) * `--retries=N` (default: `1`) The health check will first run **interval** seconds after the container is started, and then again **interval** seconds after each previous check completes. If a single run of the check takes longer than **timeout** seconds then the check is considered to have failed. It takes **retries** consecutive failures of the health check for the container to be considered `unhealthy`. There can only be one `HEALTHCHECK` instruction in a Dockerfile. If you list more than one then only the last `HEALTHCHECK` will take effect. The command after the `CMD` keyword can be either a shell command (e.g. `HEALTHCHECK CMD /bin/check-running`) or an _exec_ array (as with other Dockerfile commands; see e.g. `ENTRYPOINT` for details). The command's exit status indicates the health status of the container. The possible values are: - 0: success - the container is healthy and ready for use - 1: unhealthy - the container is not working correctly - 2: starting - the container is not ready for use yet, but is working correctly If the probe returns 2 ("starting") when the container has already moved out of the "starting" state then it is treated as "unhealthy" instead. For example, to check every five minutes or so that a web-server is able to serve the site's main page within three seconds: HEALTHCHECK --interval=5m --timeout=3s \ CMD curl -f http://localhost/ || exit 1 To help debug failing probes, any output text (UTF-8 encoded) that the command writes on stdout or stderr will be stored in the health status and can be queried with `docker inspect`. Such output should be kept short (only the first 4096 bytes are stored currently). When the health status of a container changes, a `health_status` event is generated with the new status. The health status is also displayed in the `docker ps` output. Signed-off-by: Thomas Leonard Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 67 +++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 863dcd36c..f460338b2 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1470,6 +1470,73 @@ The `STOPSIGNAL` instruction sets the system call signal that will be sent to th This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, or a signal name in the format SIGNAME, for instance SIGKILL. +## HEALTHCHECK + +The `HEALTHCHECK` instruction has two forms: + +* `HEALTHCHECK [OPTIONS] CMD command` (check container health by running a command inside the container) +* `HEALTHCHECK NONE` (disable any healthcheck inherited from the base image) + +The `HEALTHCHECK` instruction tells Docker how to test a container to check that +it is still working. This can detect cases such as a web server that is stuck in +an infinite loop and unable to handle new connections, even though the server +process is still running. + +When a container has a healthcheck specified, it has a _health status_ in +addition to its normal status. This status is initially `starting`. Whenever a +health check passes, it becomes `healthy` (whatever state it was previously in). +After a certain number of consecutive failures, it becomes `unhealthy`. + +The options that can appear before `CMD` are: + +* `--interval=DURATION` (default: `30s`) +* `--timeout=DURATION` (default: `30s`) +* `--retries=N` (default: `1`) + +The health check will first run **interval** seconds after the container is +started, and then again **interval** seconds after each previous check completes. + +If a single run of the check takes longer than **timeout** seconds then the check +is considered to have failed. + +It takes **retries** consecutive failures of the health check for the container +to be considered `unhealthy`. + +There can only be one `HEALTHCHECK` instruction in a Dockerfile. If you list +more than one then only the last `HEALTHCHECK` will take effect. + +The command after the `CMD` keyword can be either a shell command (e.g. `HEALTHCHECK +CMD /bin/check-running`) or an _exec_ array (as with other Dockerfile commands; +see e.g. `ENTRYPOINT` for details). + +The command's exit status indicates the health status of the container. +The possible values are: + +- 0: success - the container is healthy and ready for use +- 1: unhealthy - the container is not working correctly +- 2: starting - the container is not ready for use yet, but is working correctly + +If the probe returns 2 ("starting") when the container has already moved out of the +"starting" state then it is treated as "unhealthy" instead. + +For example, to check every five minutes or so that a web-server is able to +serve the site's main page within three seconds: + + HEALTHCHECK --interval=5m --timeout=3s \ + CMD curl -f http://localhost/ || exit 1 + +To help debug failing probes, any output text (UTF-8 encoded) that the command writes +on stdout or stderr will be stored in the health status and can be queried with +`docker inspect`. Such output should be kept short (only the first 4096 bytes +are stored currently). + +When the health status of a container changes, a `health_status` event is +generated with the new status. + +The `HEALTHCHECK` feature was added in Docker 1.12. + + + ## Dockerfile examples Below you can see some examples of Dockerfile syntax. If you're interested in From 57de65c98f45eb1460a839f84817495dacc33663 Mon Sep 17 00:00:00 2001 From: Yong Tang Date: Wed, 1 Jun 2016 15:20:54 -0700 Subject: [PATCH 047/152] Add support for comment in .dockerignore This fix tries to address the issue raised in #20083 where comment is not supported in `.dockerignore`. This fix updated the processing of `.dockerignore` so that any lines starting with `#` are ignored, which is similiar to the behavior of `.gitignore`. Related documentation has been updated. Additional tests have been added to cover the changes. This fix fixes #20083. Signed-off-by: Yong Tang --- frontend/dockerfile/docs/reference.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index f460338b2..35d5dfd49 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -379,9 +379,13 @@ the working and the root directory. For example, the patterns in the `foo` subdirectory of `PATH` or in the root of the git repository located at `URL`. Neither excludes anything else. +If a line in `.dockerignore` file starts with `#` in column 1, then this line is +considered as a comment and is ignored before interpreted by the CLI. + Here is an example `.dockerignore` file: ``` +# comment */temp* */*/temp* temp? @@ -391,6 +395,7 @@ This file causes the following build behavior: | Rule | Behavior | |----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `# comment` | Ignored. | | `*/temp*` | Exclude files and directories whose names start with `temp` in any immediate subdirectory of the root. For example, the plain file `/somedir/temporary.txt` is excluded, as is the directory `/somedir/temp`. | | `*/*/temp*` | Exclude files and directories starting with `temp` from any subdirectory that is two levels below the root. For example, `/somedir/subdir/temporary.txt` is excluded. | | `temp?` | Exclude files and directories in the root directory whose names are a one-character extension of `temp`. For example, `/tempa` and `/tempb` are excluded. From 6b3e222019bfd2624dc96d090cc8021e218f451e Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Fri, 3 Jun 2016 13:28:08 +0200 Subject: [PATCH 048/152] Healthcheck: set default retries to 3 Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 35d5dfd49..b9a894444 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1496,7 +1496,7 @@ The options that can appear before `CMD` are: * `--interval=DURATION` (default: `30s`) * `--timeout=DURATION` (default: `30s`) -* `--retries=N` (default: `1`) +* `--retries=N` (default: `3`) The health check will first run **interval** seconds after the container is started, and then again **interval** seconds after each previous check completes. From 686b1ba31b268be1e9acd1a4e093968915af5477 Mon Sep 17 00:00:00 2001 From: John Howard Date: Tue, 3 May 2016 13:56:59 -0700 Subject: [PATCH 049/152] Builder default shell Signed-off-by: John Howard --- frontend/dockerfile/docs/reference.md | 124 +++++++++++++++++++++++++- 1 file changed, 121 insertions(+), 3 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index b9a894444..6217d0d34 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -497,7 +497,8 @@ generated images. RUN has 2 forms: -- `RUN ` (*shell* form, the command is run in a shell - `/bin/sh -c`) +- `RUN ` (*shell* form, the command is run in a shell, which by +default is `/bin/sh -c` on Linux or `cmd /S /C` on Windows) - `RUN ["executable", "param1", "param2"]` (*exec* form) The `RUN` instruction will execute any commands in a new layer on top of the @@ -509,7 +510,10 @@ concepts of Docker where commits are cheap and containers can be created from any point in an image's history, much like source control. The *exec* form makes it possible to avoid shell string munging, and to `RUN` -commands using a base image that does not contain `/bin/sh`. +commands using a base image that does not contain the specified shell executable. + +The default shell for the *shell* form can be changed using the `SHELL` +command. In the *shell* form you can use a `\` (backslash) to continue a single RUN instruction onto the next line. For example, consider these two lines: @@ -1469,7 +1473,7 @@ For example you might add something like this: ## STOPSIGNAL - STOPSIGNAL signal + STOPSIGNAL signal The `STOPSIGNAL` instruction sets the system call signal that will be sent to the container to exit. This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, @@ -1541,6 +1545,120 @@ generated with the new status. The `HEALTHCHECK` feature was added in Docker 1.12. +## SHELL + + SHELL ["executable", "parameters"] + +The `SHELL` instruction allows the default shell used for the *shell* form of +commands to be overridden. The default shell on Linux is `["/bin/sh", "-c"]`, and on +Windows is `["cmd", "/S", "/C"]`. The `SHELL` instruction *must* be written in JSON +form in a Dockerfile. + +The `SHELL` instruction is particularly useful on Windows where there are +two commonly used and quite different native shells: `cmd` and `powershell`, as +well as alternate shells available including `sh`. + +The `SHELL` instruction can appear multiple times. Each `SHELL` instruction overrides +all previous `SHELL` instructions, and affects all subsequent instructions. For example: + + FROM windowsservercore + + # Executed as cmd /S /C echo default + RUN echo default + + # Executed as cmd /S /C powershell -command Write-Host default + RUN powershell -command Write-Host default + + # Executed as powershell -command Write-Host hello + SHELL ["powershell", "-command"] + RUN Write-Host hello + + # Executed as cmd /S /C echo hello + SHELL ["cmd", "/S"", "/C"] + RUN echo hello + +The following instructions can be affected by the `SHELL` instruction when the +*shell* form of them is used in a Dockerfile: `RUN`, `CMD` and `ENTRYPOINT`. + +The following example is a common pattern found on Windows which can be +streamlined by using the `SHELL` instruction: + + ... + RUN powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" + ... + +The command invoked by docker will be: + + cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" + + This is inefficient for two reasons. First, there is an un-necessary cmd.exe command + processor (aka shell) being invoked. Second, each `RUN` instruction in the *shell* + form requires an extra `powershell -command` prefixing the command. + +To make this more efficient, one of two mechanisms can be employed. One is to +use the JSON form of the RUN command such as: + + ... + RUN ["powershell", "-command", "Execute-MyCmdlet", "-param1 \"c:\\foo.txt\""] + ... + +While the JSON form is unambiguous and does not use the un-necessary cmd.exe, +it does require more verbosity through double-quoting and escaping. The alternate +mechanism is to use the `SHELL` instruction and the *shell* form, +making a more natural syntax for Windows users, especially when combined with +the `escape` parser directive: + + # escape=` + + FROM windowsservercore + SHELL ["powershell","-command"] + RUN New-Item -ItemType Directory C:\Example + ADD Execute-MyCmdlet.ps1 c:\example\ + RUN c:\example\Execute-MyCmdlet -sample 'hello world' + +Resulting in: + + PS E:\docker\build\shell> docker build -t shell . + Sending build context to Docker daemon 3.584 kB + Step 1 : FROM windowsservercore + ---> 5bc36a335344 + Step 2 : SHELL powershell -command + ---> Running in 87d7a64c9751 + ---> 4327358436c1 + Removing intermediate container 87d7a64c9751 + Step 3 : RUN New-Item -ItemType Directory C:\Example + ---> Running in 3e6ba16b8df9 + + + Directory: C:\ + + + Mode LastWriteTime Length Name + ---- ------------- ------ ---- + d----- 6/2/2016 2:59 PM Example + + + ---> 1f1dfdcec085 + Removing intermediate container 3e6ba16b8df9 + Step 4 : ADD Execute-MyCmdlet.ps1 c:\example\ + ---> 6770b4c17f29 + Removing intermediate container b139e34291dc + Step 5 : RUN c:\example\Execute-MyCmdlet -sample 'hello world' + ---> Running in abdcf50dfd1f + Hello from Execute-MyCmdlet.ps1 - passed hello world + ---> ba0e25255fda + Removing intermediate container abdcf50dfd1f + Successfully built ba0e25255fda + PS E:\docker\build\shell> + +The `SHELL` instruction could also be used to modify the way in which +a shell operates. For example, using `SHELL cmd /S /C /V:ON|OFF` on Windows, delayed +environment variable expansion semantics could be modified. + +The `SHELL` instruction can also be used on Linux should an alternate shell be +required such `zsh`, `csh`, `tcsh` and others. + +The `SHELL` feature was added in Docker 1.12. ## Dockerfile examples From e594df191f269eb0c98c69473da45e1a457b0bc1 Mon Sep 17 00:00:00 2001 From: Kevin Burke Date: Sat, 11 Jun 2016 12:33:09 -0700 Subject: [PATCH 050/152] typo in builder.md: its => it's Signed-off-by: Kevin Burke --- frontend/dockerfile/docs/reference.md | 102 +++++++++++++------------- 1 file changed, 51 insertions(+), 51 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 6217d0d34..9635bddfa 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -115,11 +115,11 @@ The instruction is not case-sensitive. However, convention is for them to be UPPERCASE to distinguish them from arguments more easily. -Docker runs instructions in a `Dockerfile` in order. **The first +Docker runs instructions in a `Dockerfile` in order. **The first instruction must be \`FROM\`** in order to specify the [*Base -Image*](glossary.md#base-image) from which you are building. +Image*](glossary.md#base-image) from which you are building. -Docker treats lines that *begin* with `#` as a comment, unless the line is +Docker treats lines that *begin* with `#` as a comment, unless the line is a valid [parser directive](builder.md#parser directives). A `#` marker anywhere else in a line is treated as an argument. This allows statements like: @@ -132,20 +132,20 @@ Line continuation characters are not supported in comments. ## Parser directives -Parser directives are optional, and affect the way in which subsequent lines +Parser directives are optional, and affect the way in which subsequent lines in a `Dockerfile` are handled. Parser directives do not add layers to the build, and will not be shown as a build step. Parser directives are written as a special type of comment in the form `# directive=value`. A single directive may only be used once. -Once a comment, empty line or builder instruction has been processed, Docker +Once a comment, empty line or builder instruction has been processed, Docker no longer looks for parser directives. Instead it treats anything formatted as a parser directive as a comment and does not attempt to validate if it might be a parser directive. Therefore, all parser directives must be at the very -top of a `Dockerfile`. +top of a `Dockerfile`. Parser directives are not case-sensitive. However, convention is for them to -be lowercase. Convention is also to include a blank line following any +be lowercase. Convention is also to include a blank line following any parser directives. Line continuation characters are not supported in parser directives. @@ -166,7 +166,7 @@ Invalid due to appearing twice: FROM ImageName ``` - + Treated as a comment due to appearing after a builder instruction: ```Dockerfile @@ -190,10 +190,10 @@ a comment which is not a parser directive. ```Dockerfile # unknowndirective=value # knowndirective=value -``` - +``` + Non line-breaking whitespace is permitted in a parser directive. Hence, the -following lines are all treated identically: +following lines are all treated identically: ```Dockerfile #directive=value @@ -215,26 +215,26 @@ Or # escape=` (backtick) -The `escape` directive sets the character used to escape characters in a -`Dockerfile`. If not specified, the default escape character is `\`. +The `escape` directive sets the character used to escape characters in a +`Dockerfile`. If not specified, the default escape character is `\`. The escape character is used both to escape characters in a line, and to escape a newline. This allows a `Dockerfile` instruction to span multiple lines. Note that regardless of whether the `escape` parser -directive is included in a `Dockerfile`, *escaping is not performed in -a `RUN` command, except at the end of a line.* +directive is included in a `Dockerfile`, *escaping is not performed in +a `RUN` command, except at the end of a line.* -Setting the escape character to `` ` `` is especially useful on -`Windows`, where `\` is the directory path separator. `` ` `` is consistent +Setting the escape character to `` ` `` is especially useful on +`Windows`, where `\` is the directory path separator. `` ` `` is consistent with [Windows PowerShell](https://technet.microsoft.com/en-us/library/hh847755.aspx). -Consider the following example which would fail in a non-obvious way on +Consider the following example which would fail in a non-obvious way on `Windows`. The second `\` at the end of the second line would be interpreted as an -escape for the newline, instead of a target of the escape from the first `\`. +escape for the newline, instead of a target of the escape from the first `\`. Similarly, the `\` at the end of the third line would, assuming it was actually handled as an instruction, cause it be treated as a line continuation. The result of this dockerfile is that second and third lines are considered a single -instruction: +instruction: ```Dockerfile FROM windowsservercore @@ -250,18 +250,18 @@ Results in: ---> dbfee88ee9fd Step 2 : COPY testfile.txt c:RUN dir c: GetFileAttributesEx c:RUN: The system cannot find the file specified. - PS C:\John> + PS C:\John> One solution to the above would be to use `/` as the target of both the `COPY` instruction, and `dir`. However, this syntax is, at best, confusing as it is not natural for paths on `Windows`, and at worst, error prone as not all commands on `Windows` support `/` as the path separator. -By adding the `escape` parser directive, the following `Dockerfile` succeeds as +By adding the `escape` parser directive, the following `Dockerfile` succeeds as expected with the use of natural platform semantics for file paths on `Windows`: # escape=` - + FROM windowsservercore COPY testfile.txt c:\ RUN dir c:\ @@ -279,9 +279,9 @@ Results in: ---> Running in a5ff53ad6323 Volume in drive C has no label. Volume Serial Number is 1440-27FA - + Directory of c:\ - + 03/25/2016 05:28 AM inetpub 03/25/2016 04:22 AM PerfLogs 04/22/2016 10:59 PM Program Files @@ -497,7 +497,7 @@ generated images. RUN has 2 forms: -- `RUN ` (*shell* form, the command is run in a shell, which by +- `RUN ` (*shell* form, the command is run in a shell, which by default is `/bin/sh -c` on Linux or `cmd /S /C` on Windows) - `RUN ["executable", "param1", "param2"]` (*exec* form) @@ -1209,7 +1209,7 @@ and for any `RUN`, `CMD` and `ENTRYPOINT` instructions that follow it in the The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY` and `ADD` instructions that follow it in the `Dockerfile`. -If the `WORKDIR` doesn't exist, it will be created even if its not used in any +If the `WORKDIR` doesn't exist, it will be created even if it's not used in any subsequent `Dockerfile` instruction. It can be used multiple times in the one `Dockerfile`. If a relative path @@ -1548,7 +1548,7 @@ The `HEALTHCHECK` feature was added in Docker 1.12. ## SHELL SHELL ["executable", "parameters"] - + The `SHELL` instruction allows the default shell used for the *shell* form of commands to be overridden. The default shell on Linux is `["/bin/sh", "-c"]`, and on Windows is `["cmd", "/S", "/C"]`. The `SHELL` instruction *must* be written in JSON @@ -1558,21 +1558,21 @@ The `SHELL` instruction is particularly useful on Windows where there are two commonly used and quite different native shells: `cmd` and `powershell`, as well as alternate shells available including `sh`. -The `SHELL` instruction can appear multiple times. Each `SHELL` instruction overrides +The `SHELL` instruction can appear multiple times. Each `SHELL` instruction overrides all previous `SHELL` instructions, and affects all subsequent instructions. For example: FROM windowsservercore - - # Executed as cmd /S /C echo default + + # Executed as cmd /S /C echo default RUN echo default - - # Executed as cmd /S /C powershell -command Write-Host default + + # Executed as cmd /S /C powershell -command Write-Host default RUN powershell -command Write-Host default - + # Executed as powershell -command Write-Host hello SHELL ["powershell", "-command"] RUN Write-Host hello - + # Executed as cmd /S /C echo hello SHELL ["cmd", "/S"", "/C"] RUN echo hello @@ -1580,21 +1580,21 @@ all previous `SHELL` instructions, and affects all subsequent instructions. For The following instructions can be affected by the `SHELL` instruction when the *shell* form of them is used in a Dockerfile: `RUN`, `CMD` and `ENTRYPOINT`. -The following example is a common pattern found on Windows which can be -streamlined by using the `SHELL` instruction: +The following example is a common pattern found on Windows which can be +streamlined by using the `SHELL` instruction: ... RUN powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" - ... + ... The command invoked by docker will be: cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" - + This is inefficient for two reasons. First, there is an un-necessary cmd.exe command processor (aka shell) being invoked. Second, each `RUN` instruction in the *shell* form requires an extra `powershell -command` prefixing the command. - + To make this more efficient, one of two mechanisms can be employed. One is to use the JSON form of the RUN command such as: @@ -1602,14 +1602,14 @@ use the JSON form of the RUN command such as: RUN ["powershell", "-command", "Execute-MyCmdlet", "-param1 \"c:\\foo.txt\""] ... -While the JSON form is unambiguous and does not use the un-necessary cmd.exe, +While the JSON form is unambiguous and does not use the un-necessary cmd.exe, it does require more verbosity through double-quoting and escaping. The alternate mechanism is to use the `SHELL` instruction and the *shell* form, -making a more natural syntax for Windows users, especially when combined with +making a more natural syntax for Windows users, especially when combined with the `escape` parser directive: - + # escape=` - + FROM windowsservercore SHELL ["powershell","-command"] RUN New-Item -ItemType Directory C:\Example @@ -1628,16 +1628,16 @@ Resulting in: Removing intermediate container 87d7a64c9751 Step 3 : RUN New-Item -ItemType Directory C:\Example ---> Running in 3e6ba16b8df9 - - + + Directory: C:\ - - + + Mode LastWriteTime Length Name ---- ------------- ------ ---- d----- 6/2/2016 2:59 PM Example - - + + ---> 1f1dfdcec085 Removing intermediate container 3e6ba16b8df9 Step 4 : ADD Execute-MyCmdlet.ps1 c:\example\ @@ -1654,7 +1654,7 @@ Resulting in: The `SHELL` instruction could also be used to modify the way in which a shell operates. For example, using `SHELL cmd /S /C /V:ON|OFF` on Windows, delayed environment variable expansion semantics could be modified. - + The `SHELL` instruction can also be used on Linux should an alternate shell be required such `zsh`, `csh`, `tcsh` and others. From e3821f1d58dc8ff3183c04e6c29344dff701f7d0 Mon Sep 17 00:00:00 2001 From: Victoria Bialas Date: Mon, 13 Jun 2016 11:08:11 -0700 Subject: [PATCH 051/152] surfacing Learn by example topics to top level of Docker Engine docs fixing links after moving surfacing tutorials fixing more links for the newly located tutorials Signed-off-by: Victoria Bialas --- frontend/dockerfile/docs/reference.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 9635bddfa..f26143e77 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -100,7 +100,7 @@ the `Using cache` message in the console output. Successfully built 7ea8aef582cc When you're done with your build, you're ready to look into [*Pushing a -repository to its registry*](../userguide/containers/dockerrepos.md#contributing-to-docker-hub). +repository to its registry*](../tutorials/dockerrepos.md#contributing-to-docker-hub). ## Format @@ -474,7 +474,7 @@ Or The `FROM` instruction sets the [*Base Image*](glossary.md#base-image) for subsequent instructions. As such, a valid `Dockerfile` must have `FROM` as its first instruction. The image can be any valid image – it is especially easy -to start by **pulling an image** from the [*Public Repositories*](../userguide/containers/dockerrepos.md). +to start by **pulling an image** from the [*Public Repositories*](../tutorials/dockerrepos.md). - `FROM` must be the first non-comment instruction in the `Dockerfile`. @@ -1171,7 +1171,7 @@ containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log /var/db`. For more information/examples and mounting instructions via the Docker client, refer to -[*Share Directories via Volumes*](../userguide/containers/dockervolumes.md#mount-a-host-directory-as-a-data-volume) +[*Share Directories via Volumes*](../tutorials/dockervolumes.md#mount-a-host-directory-as-a-data-volume) documentation. The `docker run` command initializes the newly created volume with any data From e375e7f35bef2f7bd22fbbd0fba2eadb9a311f7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Serhat=20G=C3=BCl=C3=A7i=C3=A7ek?= Date: Mon, 20 Jun 2016 12:35:26 +0200 Subject: [PATCH 052/152] Fix error for env variables example in docker reference - 2 The reason why the issue occurs is because sh parses the first argument after -c as the whole script to execute. Everything after isn't executed as one might expect. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When working on the 'fix' I found out the same fix is also done in commit 2af7c5cfe24b4c8e931f751979b5e69e20ba77e2, except only for one occurrence. Signed-off-by: Serhat Gülçiçek --- frontend/dockerfile/docs/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index f26143e77..4c7e059c8 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -606,7 +606,7 @@ instruction as well. > This means that normal shell processing does not happen. For example, > `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. > If you want shell processing then either use the *shell* form or execute -> a shell directly, for example: `CMD [ "sh", "-c", "echo", "$HOME" ]`. +> a shell directly, for example: `CMD [ "sh", "-c", "echo $HOME" ]`. When used in the shell or exec formats, the `CMD` instruction sets the command to be executed when running the image. @@ -1074,7 +1074,7 @@ sys 0m 0.03s > This means that normal shell processing does not happen. For example, > `ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. > If you want shell processing then either use the *shell* form or execute -> a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo", "$HOME" ]`. +> a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo $HOME" ]`. > Variables that are defined in the `Dockerfile`using `ENV`, will be substituted by > the `Dockerfile` parser. From eb979e7c4c815683e8a64cc9f42ce7e2733f19ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Otto=20Kek=C3=A4l=C3=A4inen?= Date: Sun, 3 Jul 2016 20:58:11 +0300 Subject: [PATCH 053/152] Fix spelling in comments, strings and documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Otto Kekäläinen --- frontend/dockerfile/docs/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 4c7e059c8..8090aa94d 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -502,7 +502,7 @@ default is `/bin/sh -c` on Linux or `cmd /S /C` on Windows) - `RUN ["executable", "param1", "param2"]` (*exec* form) The `RUN` instruction will execute any commands in a new layer on top of the -current image and commit the results. The resulting committed image will be +current image and commit the results. The resulting comitted image will be used for the next step in the `Dockerfile`. Layering `RUN` instructions and generating commits conforms to the core @@ -544,7 +544,7 @@ RUN /bin/bash -c 'source $HOME/.bashrc ; echo $HOME' > > **Note**: > In the *JSON* form, it is necessary to escape backslashes. This is -> particularly relevant on Windows where the backslash is the path seperator. +> particularly relevant on Windows where the backslash is the path separator. > The following line would otherwise be treated as *shell* form due to not > being valid JSON, and fail in an unexpected way: > `RUN ["c:\windows\system32\tasklist.exe"]` From 88db05720a65ce59f7504dc9d14bf34091b31c92 Mon Sep 17 00:00:00 2001 From: Dave Henderson Date: Mon, 11 Jul 2016 21:18:03 -0400 Subject: [PATCH 054/152] Clarify warning against using build-time variables for secrets Signed-off-by: Dave Henderson --- frontend/dockerfile/docs/reference.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 8090aa94d..9180e6b78 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1292,8 +1292,9 @@ subsequent line 3. The `USER` at line 4 evaluates to `what_user` as `user` is defined and the `what_user` value was passed on the command line. Prior to its definition by an `ARG` instruction, any use of a variable results in an empty string. -> **Note:** It is not recommended to use build-time variables for -> passing secrets like github keys, user credentials etc. +> **Warning:** It is not recommended to use build-time variables for +> passing secrets like github keys, user credentials etc. Build-time variable +> values are visible to any user of the image with the `docker history` command. You can use an `ARG` or an `ENV` instruction to specify variables that are available to the `RUN` instruction. Environment variables defined using the From e6b9733408c9da7731e340bdfeaa216900550ee1 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 12 Jul 2016 21:51:14 +0200 Subject: [PATCH 055/152] Fix some broken sourceforge.net links Looks like there's issues with sourceforge project pages. Given that sourceforge isn't really what it used to be, trying to find alternative URLs where possible. Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 9180e6b78..d677d63b8 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -572,7 +572,7 @@ The cache for `RUN` instructions can be invalidated by `ADD` instructions. See For systems that have recent aufs version (i.e., `dirperm1` mount option can be set), docker will attempt to fix the issue automatically by mounting the layers with `dirperm1` option. More details on `dirperm1` option can be - found at [`aufs` man page](http://aufs.sourceforge.net/aufs3/man.html) + found at [`aufs` man page](https://github.com/sfjro/aufs3-linux/tree/aufs3.18/Documentation/filesystems/aufs) If your system doesn't have support for `dirperm1`, the issue describes a workaround. From ed48009778a84032382acc1fac997dff7c1b181b Mon Sep 17 00:00:00 2001 From: Tibor Vass Date: Wed, 20 Jul 2016 10:50:04 -0700 Subject: [PATCH 056/152] healthcheck: do not interpret exit code 2 as "starting" Instead reserve exit code 2 to be future proof, document that it should not be used. Implementation-wise, it is considered as unhealthy, but users should not rely on this as it may change in the future. Signed-off-by: Tibor Vass --- frontend/dockerfile/docs/reference.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index d677d63b8..5975110fe 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1524,10 +1524,7 @@ The possible values are: - 0: success - the container is healthy and ready for use - 1: unhealthy - the container is not working correctly -- 2: starting - the container is not ready for use yet, but is working correctly - -If the probe returns 2 ("starting") when the container has already moved out of the -"starting" state then it is treated as "unhealthy" instead. +- 2: reserved - do not use this exit code For example, to check every five minutes or so that a web-server is able to serve the site's main page within three seconds: From 8d2f2d8e66700df9376b69363c927761d5d2ea10 Mon Sep 17 00:00:00 2001 From: Mihai Borobocea Date: Sat, 20 Aug 2016 16:19:05 +0300 Subject: [PATCH 057/152] docs: fix typo in url fragment I noticed the broken hyperlink in this page: https://docs.docker.com/engine/reference/builder/ The link should point to `#parser-directives`. Signed-off-by: Mihai Borobocea --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 5975110fe..2a21056ad 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -120,7 +120,7 @@ instruction must be \`FROM\`** in order to specify the [*Base Image*](glossary.md#base-image) from which you are building. Docker treats lines that *begin* with `#` as a comment, unless the line is -a valid [parser directive](builder.md#parser directives). A `#` marker anywhere +a valid [parser directive](builder.md#parser-directives). A `#` marker anywhere else in a line is treated as an argument. This allows statements like: ```Dockerfile From da47c4153ff9287b39299bb769851a4518a3cd42 Mon Sep 17 00:00:00 2001 From: David Dooling Date: Tue, 16 Aug 2016 15:01:05 -0500 Subject: [PATCH 058/152] Remove erroneous ENTRYPOINT note The Dockerfile parser does not subsitute ENV variables in any form of the ENTRYPOINT command. Any substitution, if done, is done by the shell when the command is executed. Signed-off-by: David Dooling --- frontend/dockerfile/docs/reference.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 2a21056ad..b84f1811f 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1075,8 +1075,6 @@ sys 0m 0.03s > `ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. > If you want shell processing then either use the *shell* form or execute > a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo $HOME" ]`. -> Variables that are defined in the `Dockerfile`using `ENV`, will be substituted by -> the `Dockerfile` parser. ### Shell form ENTRYPOINT example From 78a11895f18b3b7ff3abcb5cf073f713d44955e4 Mon Sep 17 00:00:00 2001 From: David Dooling Date: Wed, 17 Aug 2016 06:31:19 -0500 Subject: [PATCH 059/152] Make it clear who is doing variable expansion Add sentece to RUN, CMD, and ENTRYPOINT exec sections making it clear that it is the shell doing the environment variable expansion. Signed-off-by: David Dooling --- frontend/dockerfile/docs/reference.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index b84f1811f..c63bcf534 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -541,6 +541,9 @@ RUN /bin/bash -c 'source $HOME/.bashrc ; echo $HOME' > `RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. > If you want shell processing then either use the *shell* form or execute > a shell directly, for example: `RUN [ "sh", "-c", "echo $HOME" ]`. +> When using the exec form and executing a shell directly, as in the case for +> the shell form, it is the shell that is doing the environment variable +> expansion, not docker. > > **Note**: > In the *JSON* form, it is necessary to escape backslashes. This is @@ -607,6 +610,9 @@ instruction as well. > `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. > If you want shell processing then either use the *shell* form or execute > a shell directly, for example: `CMD [ "sh", "-c", "echo $HOME" ]`. +> When using the exec form and executing a shell directly, as in the case for +> the shell form, it is the shell that is doing the environment variable +> expansion, not docker. When used in the shell or exec formats, the `CMD` instruction sets the command to be executed when running the image. @@ -1075,6 +1081,9 @@ sys 0m 0.03s > `ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. > If you want shell processing then either use the *shell* form or execute > a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo $HOME" ]`. +> When using the exec form and executing a shell directly, as in the case for +> the shell form, it is the shell that is doing the environment variable +> expansion, not docker. ### Shell form ENTRYPOINT example From 902da1f9f6bb8af41953b2e4f6ac3ec0aeadaa81 Mon Sep 17 00:00:00 2001 From: Kris-Mikael Krister Date: Tue, 30 Aug 2016 09:23:10 +0200 Subject: [PATCH 060/152] Fix typo in builder.md Signed-off-by: Kris-Mikael Krister --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index c63bcf534..cba4ddb51 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1068,7 +1068,7 @@ user 0m 0.03s sys 0m 0.03s ``` -> **Note:** you can over ride the `ENTRYPOINT` setting using `--entrypoint`, +> **Note:** you can override the `ENTRYPOINT` setting using `--entrypoint`, > but this can only set the binary to *exec* (no `sh -c` will be used). > **Note**: From 047c41f9d2fea1670ff7683efc383b3c2478d53a Mon Sep 17 00:00:00 2001 From: Yong Tang Date: Sun, 11 Sep 2016 10:52:40 -0700 Subject: [PATCH 061/152] Fix documentation for `Step 0` to `Step 1` in `docker build` The indexing of steps in the output of `docker build` starts with `Step 1`. However, there are several places in the docs that start with `Step 0`. This fix addresses the issue and changes `Step 0` to `Step 1` (and subsequent steps). Signed-off-by: Yong Tang --- frontend/dockerfile/docs/reference.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index cba4ddb51..3434c1b43 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -86,15 +86,15 @@ the `Using cache` message in the console output. $ docker build -t svendowideit/ambassador . Sending build context to Docker daemon 15.36 kB - Step 0 : FROM alpine:3.2 + Step 1 : FROM alpine:3.2 ---> 31f630c65071 - Step 1 : MAINTAINER SvenDowideit@home.org.au + Step 2 : MAINTAINER SvenDowideit@home.org.au ---> Using cache ---> 2a1c91448f5f - Step 2 : RUN apk update && apk add socat && rm -r /var/cache/ + Step 3 : RUN apk update && apk add socat && rm -r /var/cache/ ---> Using cache ---> 21ed6e7fbb73 - Step 3 : CMD env | grep _TCP= | (sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' && echo wait) | sh + Step 4 : CMD env | grep _TCP= | (sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' && echo wait) | sh ---> Using cache ---> 7ea8aef582cc Successfully built 7ea8aef582cc From 14a21f18f382518053fc81909cb34521b6bba930 Mon Sep 17 00:00:00 2001 From: Justin Cormack Date: Sat, 6 Aug 2016 14:34:49 +0200 Subject: [PATCH 062/152] Begin process of deprecating MAINTAINER This may take some time, but start by pointing people at LABEL instead. MAINTAINER predates general LABEL and has basically no tooling, only allows a single item to be added, and is has been unofficially deprecated for some time, with many images not including it, but we have never specifically said that it should be replaced by LABEL as a better more generic metadata solution. Signed-off-by: Justin Cormack --- frontend/dockerfile/docs/reference.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 3434c1b43..cd9417080 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -486,13 +486,6 @@ before each new `FROM` command. assumes a `latest` by default. The builder returns an error if it cannot match the `tag` value. -## MAINTAINER - - MAINTAINER - -The `MAINTAINER` instruction allows you to set the *Author* field of the -generated images. - ## RUN RUN has 2 forms: @@ -687,6 +680,20 @@ To view an image's labels, use the `docker inspect` command. "other": "value3" }, +## MAINTAINER (deprecated) + + MAINTAINER + +The `MAINTAINER` instruction sets the *Author* field of the generated images. +The `LABEL` instruction is a much more flexible version of this and you should use +it instead, as it enables setting any metadata you require, and can be viewed +easily, for example with `docker inspect`. To set a label corresponding to the +`MAINTAINER` field you could use: + + LABEL maintainer "SvenDowideit@home.org.au" + +This will then be visible from `docker inspect` with the other labels. + ## EXPOSE EXPOSE [...] @@ -1676,8 +1683,6 @@ something more realistic, take a look at the list of [Dockerization examples](.. # VERSION 0.0.1 FROM ubuntu -MAINTAINER Victor Vieux - LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products" Version="1.0" RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server ``` From dbf21b22c930276966012c8ae905a1558d110ddf Mon Sep 17 00:00:00 2001 From: David Dooling Date: Tue, 16 Aug 2016 15:08:07 -0500 Subject: [PATCH 063/152] Update ENTRYPOINT/CMD table to agree with docs Several other places in the document it states that when using the shell form of ENTRYPOINT, CMD and command line arguments are ignored. That is accurate, this table was not. It is now. Signed-off-by: David Dooling --- frontend/dockerfile/docs/reference.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index cd9417080..a42b631eb 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1168,12 +1168,12 @@ or for executing an ad-hoc command in a container. The table below shows what command is executed for different `ENTRYPOINT` / `CMD` combinations: -| | No ENTRYPOINT | ENTRYPOINT exec_entry p1_entry | ENTRYPOINT ["exec_entry", "p1_entry"] | -|--------------------------------|----------------------------|-----------------------------------------------------------|------------------------------------------------| -| **No CMD** | *error, not allowed* | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry | -| **CMD ["exec_cmd", "p1_cmd"]** | exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry exec_cmd p1_cmd | exec_entry p1_entry exec_cmd p1_cmd | -| **CMD ["p1_cmd", "p2_cmd"]** | p1_cmd p2_cmd | /bin/sh -c exec_entry p1_entry p1_cmd p2_cmd | exec_entry p1_entry p1_cmd p2_cmd | -| **CMD exec_cmd p1_cmd** | /bin/sh -c exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry /bin/sh -c exec_cmd p1_cmd | exec_entry p1_entry /bin/sh -c exec_cmd p1_cmd | +| | No ENTRYPOINT | ENTRYPOINT exec_entry p1_entry | ENTRYPOINT ["exec_entry", "p1_entry"] | +|--------------------------------|----------------------------|--------------------------------|------------------------------------------------| +| **No CMD** | *error, not allowed* | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry | +| **CMD ["exec_cmd", "p1_cmd"]** | exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry exec_cmd p1_cmd | +| **CMD ["p1_cmd", "p2_cmd"]** | p1_cmd p2_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry p1_cmd p2_cmd | +| **CMD exec_cmd p1_cmd** | /bin/sh -c exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry /bin/sh -c exec_cmd p1_cmd | ## VOLUME From da1f851a5506c4f65466aa6a2ddddaec0dbcbdef Mon Sep 17 00:00:00 2001 From: Yong Tang Date: Wed, 21 Sep 2016 17:42:53 -0700 Subject: [PATCH 064/152] Update documentation and change log to include the preliminary validation of dockerfile. This commit updates documentation and change log to include the preliminary validation of the dockerfile before instructions in dockerfile is run one-by-one. Signed-off-by: Yong Tang --- frontend/dockerfile/docs/reference.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index a42b631eb..a4352bb91 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -68,6 +68,13 @@ add multiple `-t` parameters when you run the `build` command: $ docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest . +Before the Docker daemon runs the instructions in the `Dockerfile`, it performs +a preliminary validation of the `Dockerfile` and returns an error if the syntax is incorrect: + + $ docker build -t test/myapp . + Sending build context to Docker daemon 2.048 kB + Error response from daemon: Unknown instruction: RUNCMD + The Docker daemon runs the instructions in the `Dockerfile` one-by-one, committing the result of each instruction to a new image if necessary, before finally outputting the ID of your From efbd8a634516251c4ce3d489d388dc96221bad94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?To=CC=83nis=20Tiigi?= Date: Thu, 22 Sep 2016 14:38:00 -0700 Subject: [PATCH 065/152] Implement build cache based on history array Based on work by KJ Tsanaktsidis Signed-off-by: Tonis Tiigi Signed-off-by: KJ Tsanaktsidis --- frontend/dockerfile/docs/reference.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index a4352bb91..bef2b8553 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -106,6 +106,13 @@ the `Using cache` message in the console output. ---> 7ea8aef582cc Successfully built 7ea8aef582cc +Build cache is only used from images that have a local parent chain. This means +that these images were created by previous builds or the whole chain of images +was loaded with `docker load`. If you wish to use build cache of a specific +image you can specify it with `--cache-from` option. Images specified with +`--cache-from` do not need to have a parent chain and may be pulled from other +registries. + When you're done with your build, you're ready to look into [*Pushing a repository to its registry*](../tutorials/dockerrepos.md#contributing-to-docker-hub). From a209c9b78375aa5c659bbaa739119b64f5e6884b Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Fri, 14 Oct 2016 15:30:36 -0700 Subject: [PATCH 066/152] Convert Markdown frontmatter to YAML Some frontmatter such as the weights, menu stuff, etc is no longer used 'draft=true' becomes 'published: false' Signed-off-by: Misty Stanley-Jones --- frontend/dockerfile/docs/reference.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index bef2b8553..5b22fa141 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1,13 +1,8 @@ - +--- +title: "Dockerfile reference" +description: "Dockerfiles use a simple DSL which allows you to automate the steps you would normally manually take to create an image." +keywords: ["builder, docker, Dockerfile, automation, image creation"] +--- # Dockerfile reference @@ -698,7 +693,7 @@ To view an image's labels, use the `docker inspect` command. MAINTAINER -The `MAINTAINER` instruction sets the *Author* field of the generated images. +The `MAINTAINER` instruction sets the *Author* field of the generated images. The `LABEL` instruction is a much more flexible version of this and you should use it instead, as it enables setting any metadata you require, and can be viewed easily, for example with `docker inspect`. To set a label corresponding to the From 9e53272bb6bafd2a5af7522bec1cdf01f5d41f69 Mon Sep 17 00:00:00 2001 From: Ding Fei Date: Sat, 15 Oct 2016 19:03:47 +0800 Subject: [PATCH 067/152] Fix typos in docs/reference/builder.md. Signed-off-by: Ding Fei --- frontend/dockerfile/docs/reference.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 5b22fa141..dab06da99 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -21,7 +21,7 @@ Practices](../userguide/eng-image/dockerfile_best-practices.md) for a tip-orient The [`docker build`](commandline/build.md) command builds an image from a `Dockerfile` and a *context*. The build's context is the files at a specified location `PATH` or `URL`. The `PATH` is a directory on your local filesystem. -The `URL` is a the location of a Git repository. +The `URL` is a Git repository location. A context is processed recursively. So, a `PATH` includes any subdirectories and the `URL` includes the repository and its submodules. A simple build command @@ -504,7 +504,7 @@ default is `/bin/sh -c` on Linux or `cmd /S /C` on Windows) - `RUN ["executable", "param1", "param2"]` (*exec* form) The `RUN` instruction will execute any commands in a new layer on top of the -current image and commit the results. The resulting comitted image will be +current image and commit the results. The resulting committed image will be used for the next step in the `Dockerfile`. Layering `RUN` instructions and generating commits conforms to the core @@ -519,13 +519,15 @@ command. In the *shell* form you can use a `\` (backslash) to continue a single RUN instruction onto the next line. For example, consider these two lines: + ``` -RUN /bin/bash -c 'source $HOME/.bashrc ;\ +RUN /bin/bash -c 'source $HOME/.bashrc; \ echo $HOME' ``` Together they are equivalent to this single line: + ``` -RUN /bin/bash -c 'source $HOME/.bashrc ; echo $HOME' +RUN /bin/bash -c 'source $HOME/.bashrc; echo $HOME' ``` > **Note**: @@ -641,7 +643,7 @@ If the user specifies arguments to `docker run` then they will override the default specified in `CMD`. > **Note**: -> don't confuse `RUN` with `CMD`. `RUN` actually runs a command and commits +> Don't confuse `RUN` with `CMD`. `RUN` actually runs a command and commits > the result; `CMD` does not execute anything at build time, but specifies > the intended command for the image. @@ -751,7 +753,7 @@ and ENV myDog Rex The Dog ENV myCat fluffy -will yield the same net results in the final container, but the first form +will yield the same net results in the final image, but the first form is preferred because it produces a single cache layer. The environment variables set using `ENV` will persist when a container is run @@ -773,7 +775,7 @@ ADD has two forms: whitespace) The `ADD` instruction copies new files, directories or remote file URLs from `` -and adds them to the filesystem of the container at the path ``. +and adds them to the filesystem of the image at the path ``. Multiple `` resource may be specified but if they are files or directories then they must be relative to the source directory that is @@ -806,7 +808,7 @@ of whether or not the file has changed and the cache should be updated. > can only contain a URL based `ADD` instruction. You can also pass a > compressed archive through STDIN: (`docker build - < archive.tar.gz`), > the `Dockerfile` at the root of the archive and the rest of the -> archive will get used at the context of the build. +> archive will be used as the context of the build. > **Note**: > If your URL files are protected using authentication, you @@ -848,7 +850,7 @@ guide](../userguide/eng-image/dockerfile_best-practices.md#build-cache) for more - If `` is a *local* tar archive in a recognized compression format (identity, gzip, bzip2 or xz) then it is unpacked as a directory. Resources from *remote* URLs are **not** decompressed. When a directory is copied or - unpacked, it has the same behavior as `tar -x`: the result is the union of: + unpacked, it has the same behavior as `tar -x`, the result is the union of: 1. Whatever existed at the destination path and 2. The contents of the source tree, with conflicts resolved in favor @@ -1677,7 +1679,7 @@ a shell operates. For example, using `SHELL cmd /S /C /V:ON|OFF` on Windows, del environment variable expansion semantics could be modified. The `SHELL` instruction can also be used on Linux should an alternate shell be -required such `zsh`, `csh`, `tcsh` and others. +required such as `zsh`, `csh`, `tcsh` and others. The `SHELL` feature was added in Docker 1.12. From bad605add33575468db4ae146023aca1400f2451 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Wed, 19 Oct 2016 10:25:45 -0700 Subject: [PATCH 068/152] Sync docker/docker refs with files mistakenly edited in docker.github.io repo Signed-off-by: Misty Stanley-Jones --- frontend/dockerfile/docs/reference.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index dab06da99..19e693482 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -4,6 +4,15 @@ description: "Dockerfiles use a simple DSL which allows you to automate the step keywords: ["builder, docker, Dockerfile, automation, image creation"] --- + + # Dockerfile reference Docker can build images automatically by reading the instructions from a @@ -129,7 +138,7 @@ instruction must be \`FROM\`** in order to specify the [*Base Image*](glossary.md#base-image) from which you are building. Docker treats lines that *begin* with `#` as a comment, unless the line is -a valid [parser directive](builder.md#parser-directives). A `#` marker anywhere +a valid [parser directive](#parser-directives). A `#` marker anywhere else in a line is treated as an argument. This allows statements like: ```Dockerfile @@ -1265,9 +1274,9 @@ The output of the final `pwd` command in this `Dockerfile` would be ARG [=] The `ARG` instruction defines a variable that users can pass at build-time to -the builder with the `docker build` command using the `--build-arg -=` flag. If a user specifies a build argument that was not -defined in the Dockerfile, the build outputs an error. +the builder with the `docker build` command using the +`--build-arg =` flag. If a user specifies a build argument +that was not defined in the Dockerfile, the build outputs an error. ``` One or more build-args were not consumed, failing build. @@ -1380,8 +1389,11 @@ corresponding `ARG` instruction in the Dockerfile. * `NO_PROXY` * `no_proxy` -To use these, simply pass them on the command line using the `--build-arg -=` flag. +To use these, simply pass them on the command line using the flag: + +``` +--build-arg = +``` ### Impact on build caching From e43b75f136cd1804aad7c3128cdeb718c061581f Mon Sep 17 00:00:00 2001 From: John Howard Date: Fri, 28 Oct 2016 11:36:11 -0700 Subject: [PATCH 069/152] Update examples in builder.md Signed-off-by: John Howard --- frontend/dockerfile/docs/reference.md | 111 +++++++++++++------------- 1 file changed, 55 insertions(+), 56 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 19e693482..a242a4af1 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -255,7 +255,7 @@ of this dockerfile is that second and third lines are considered a single instruction: ```Dockerfile -FROM windowsservercore +FROM microsoft/nanoserver COPY testfile.txt c:\\ RUN dir c:\ ``` @@ -264,9 +264,9 @@ Results in: PS C:\John> docker build -t cmd . Sending build context to Docker daemon 3.072 kB - Step 1 : FROM windowsservercore - ---> dbfee88ee9fd - Step 2 : COPY testfile.txt c:RUN dir c: + Step 1/2 : FROM microsoft/nanoserver + ---> 22738ff49c6d + Step 2/2 : COPY testfile.txt c:\RUN dir c: GetFileAttributesEx c:RUN: The system cannot find the file specified. PS C:\John> @@ -280,7 +280,7 @@ expected with the use of natural platform semantics for file paths on `Windows`: # escape=` - FROM windowsservercore + FROM microsoft/nanoserver COPY testfile.txt c:\ RUN dir c:\ @@ -288,30 +288,29 @@ Results in: PS C:\John> docker build -t succeeds --no-cache=true . Sending build context to Docker daemon 3.072 kB - Step 1 : FROM windowsservercore - ---> dbfee88ee9fd - Step 2 : COPY testfile.txt c:\ - ---> 99ceb62e90df - Removing intermediate container 62afbe726221 - Step 3 : RUN dir c:\ - ---> Running in a5ff53ad6323 + Step 1/3 : FROM microsoft/nanoserver + ---> 22738ff49c6d + Step 2/3 : COPY testfile.txt c:\ + ---> 96655de338de + Removing intermediate container 4db9acbb1682 + Step 3/3 : RUN dir c:\ + ---> Running in a2c157f842f5 Volume in drive C has no label. - Volume Serial Number is 1440-27FA - + Volume Serial Number is 7E6D-E0F7 + Directory of c:\ - - 03/25/2016 05:28 AM inetpub - 03/25/2016 04:22 AM PerfLogs - 04/22/2016 10:59 PM Program Files - 03/25/2016 04:22 AM Program Files (x86) - 04/18/2016 09:26 AM 4 testfile.txt - 04/22/2016 10:59 PM Users - 04/22/2016 10:59 PM Windows - 1 File(s) 4 bytes - 6 Dir(s) 21,252,689,920 bytes free - ---> 2569aa19abef - Removing intermediate container a5ff53ad6323 - Successfully built 2569aa19abef + + 10/05/2016 05:04 PM 1,894 License.txt + 10/05/2016 02:22 PM Program Files + 10/05/2016 02:14 PM Program Files (x86) + 10/28/2016 11:18 AM 62 testfile.txt + 10/28/2016 11:20 AM Users + 10/28/2016 11:20 AM Windows + 2 File(s) 1,956 bytes + 4 Dir(s) 21,259,096,064 bytes free + ---> 01c7f3bef04f + Removing intermediate container a2c157f842f5 + Successfully built 01c7f3bef04f PS C:\John> ## Environment replacement @@ -1596,7 +1595,7 @@ well as alternate shells available including `sh`. The `SHELL` instruction can appear multiple times. Each `SHELL` instruction overrides all previous `SHELL` instructions, and affects all subsequent instructions. For example: - FROM windowsservercore + FROM microsoft/windowsservercore # Executed as cmd /S /C echo default RUN echo default @@ -1645,7 +1644,7 @@ the `escape` parser directive: # escape=` - FROM windowsservercore + FROM microsoft/nanoserver SHELL ["powershell","-command"] RUN New-Item -ItemType Directory C:\Example ADD Execute-MyCmdlet.ps1 c:\example\ @@ -1654,36 +1653,36 @@ the `escape` parser directive: Resulting in: PS E:\docker\build\shell> docker build -t shell . - Sending build context to Docker daemon 3.584 kB - Step 1 : FROM windowsservercore - ---> 5bc36a335344 - Step 2 : SHELL powershell -command - ---> Running in 87d7a64c9751 - ---> 4327358436c1 - Removing intermediate container 87d7a64c9751 - Step 3 : RUN New-Item -ItemType Directory C:\Example - ---> Running in 3e6ba16b8df9 - - + Sending build context to Docker daemon 4.096 kB + Step 1/5 : FROM microsoft/nanoserver + ---> 22738ff49c6d + Step 2/5 : SHELL powershell -command + ---> Running in 6fcdb6855ae2 + ---> 6331462d4300 + Removing intermediate container 6fcdb6855ae2 + Step 3/5 : RUN New-Item -ItemType Directory C:\Example + ---> Running in d0eef8386e97 + + Directory: C:\ - - + + Mode LastWriteTime Length Name ---- ------------- ------ ---- - d----- 6/2/2016 2:59 PM Example - - - ---> 1f1dfdcec085 - Removing intermediate container 3e6ba16b8df9 - Step 4 : ADD Execute-MyCmdlet.ps1 c:\example\ - ---> 6770b4c17f29 - Removing intermediate container b139e34291dc - Step 5 : RUN c:\example\Execute-MyCmdlet -sample 'hello world' - ---> Running in abdcf50dfd1f - Hello from Execute-MyCmdlet.ps1 - passed hello world - ---> ba0e25255fda - Removing intermediate container abdcf50dfd1f - Successfully built ba0e25255fda + d----- 10/28/2016 11:26 AM Example + + + ---> 3f2fbf1395d9 + Removing intermediate container d0eef8386e97 + Step 4/5 : ADD Execute-MyCmdlet.ps1 c:\example\ + ---> a955b2621c31 + Removing intermediate container b825593d39fc + Step 5/5 : RUN c:\example\Execute-MyCmdlet 'hello world' + ---> Running in be6d8e63fe75 + hello world + ---> 8e559e9bf424 + Removing intermediate container be6d8e63fe75 + Successfully built 8e559e9bf424 PS E:\docker\build\shell> The `SHELL` instruction could also be used to modify the way in which From e1704420f0e7a70d4cfb15c8f68a4f462be6988b Mon Sep 17 00:00:00 2001 From: lixiaobing10051267 Date: Thu, 27 Oct 2016 16:24:55 +0800 Subject: [PATCH 070/152] fill the complete address because of no userguide directory Signed-off-by: lixiaobing10051267 --- frontend/dockerfile/docs/reference.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index a242a4af1..9563fe21e 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -23,7 +23,7 @@ instructions in succession. This page describes the commands you can use in a `Dockerfile`. When you are done reading this page, refer to the [`Dockerfile` Best -Practices](../userguide/eng-image/dockerfile_best-practices.md) for a tip-oriented guide. +Practices](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/) for a tip-oriented guide. ## Usage @@ -92,7 +92,7 @@ instructions. Whenever possible, Docker will re-use the intermediate images (cache), to accelerate the `docker build` process significantly. This is indicated by the `Using cache` message in the console output. -(For more information, see the [Build cache section](../userguide/eng-image/dockerfile_best-practices.md#build-cache)) in the +(For more information, see the [Build cache section](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/#/build-cache)) in the `Dockerfile` best practices guide: $ docker build -t svendowideit/ambassador . @@ -573,7 +573,7 @@ cache for `RUN` instructions can be invalidated by using the `--no-cache` flag, for example `docker build --no-cache`. See the [`Dockerfile` Best Practices -guide](../userguide/eng-image/dockerfile_best-practices.md#build-cache) for more information. +guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/#/build-cache) for more information. The cache for `RUN` instructions can be invalidated by `ADD` instructions. See [below](#add) for details. @@ -728,7 +728,7 @@ To set up port redirection on the host system, see [using the -P flag](run.md#expose-incoming-ports). The Docker network feature supports creating networks without the need to expose ports within the network, for detailed information see the [overview of this -feature](../userguide/networking/index.md)). +feature](https://docs.docker.com/engine/userguide/networking/)). ## ENV @@ -829,7 +829,7 @@ of whether or not the file has changed and the cache should be updated. > following instructions from the Dockerfile if the contents of `` have > changed. This includes invalidating the cache for `RUN` instructions. > See the [`Dockerfile` Best Practices -guide](../userguide/eng-image/dockerfile_best-practices.md#build-cache) for more information. +guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/#/build-cache) for more information. `ADD` obeys the following rules: From 97188aa216104399fc49f02a4ea7170009f85074 Mon Sep 17 00:00:00 2001 From: lixiaobing10051267 Date: Thu, 27 Oct 2016 16:47:28 +0800 Subject: [PATCH 071/152] fill all the rest invalid address because no related directory Signed-off-by: lixiaobing10051267 --- frontend/dockerfile/docs/reference.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 9563fe21e..ffe010ddb 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -118,7 +118,7 @@ image you can specify it with `--cache-from` option. Images specified with registries. When you're done with your build, you're ready to look into [*Pushing a -repository to its registry*](../tutorials/dockerrepos.md#contributing-to-docker-hub). +repository to its registry*](https://docs.docker.com/engine/tutorials/dockerrepos/#/contributing-to-docker-hub). ## Format @@ -491,7 +491,7 @@ Or The `FROM` instruction sets the [*Base Image*](glossary.md#base-image) for subsequent instructions. As such, a valid `Dockerfile` must have `FROM` as its first instruction. The image can be any valid image – it is especially easy -to start by **pulling an image** from the [*Public Repositories*](../tutorials/dockerrepos.md). +to start by **pulling an image** from the [*Public Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/). - `FROM` must be the first non-comment instruction in the `Dockerfile`. @@ -1204,7 +1204,7 @@ containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log /var/db`. For more information/examples and mounting instructions via the Docker client, refer to -[*Share Directories via Volumes*](../tutorials/dockervolumes.md#mount-a-host-directory-as-a-data-volume) +[*Share Directories via Volumes*](https://docs.docker.com/engine/tutorials/dockervolumes/#/mount-a-host-directory-as-a-data-volume) documentation. The `docker run` command initializes the newly created volume with any data @@ -1697,7 +1697,7 @@ The `SHELL` feature was added in Docker 1.12. ## Dockerfile examples Below you can see some examples of Dockerfile syntax. If you're interested in -something more realistic, take a look at the list of [Dockerization examples](../examples/index.md). +something more realistic, take a look at the list of [Dockerization examples](https://docs.docker.com/engine/examples/). ``` # Nginx From e6c6436decb577d1053d1f91d9475087f331206f Mon Sep 17 00:00:00 2001 From: John Howard Date: Fri, 28 Oct 2016 10:28:38 -0700 Subject: [PATCH 072/152] Windows: Clarify WORKDIR in docs Signed-off-by: John Howard --- frontend/dockerfile/docs/reference.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index ffe010ddb..3c7a2b8b6 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1268,6 +1268,19 @@ For example: The output of the final `pwd` command in this `Dockerfile` would be `/path/$DIRNAME` +On Windows, `WORKDIR` behaves differently depending on whether using Windows +Server containers or Hyper-V containers. For Hyper-V containers, the engine +is, for architectural reasons, unable to create the directory if it does not +previously exist. For Windows Server containers, the directory is created +if it does not exist. Hence, for consistency between Windows Server and +Hyper-V containers, it is strongly recommended to include an explict instruction +to create the directory in the Dockerfile. For example: + + # escape=` + FROM microsoft/nanoserver + RUN mkdir c:\myapp + WORKDIR c:\myapp + ## ARG ARG [=] From 1cc76e528b509e9b018c9e9da302790a2f688338 Mon Sep 17 00:00:00 2001 From: Qiang Huang Date: Sat, 29 Oct 2016 15:03:26 +0800 Subject: [PATCH 073/152] Fix bunch of typos Signed-off-by: Qiang Huang --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 3c7a2b8b6..b3010a47d 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1273,7 +1273,7 @@ Server containers or Hyper-V containers. For Hyper-V containers, the engine is, for architectural reasons, unable to create the directory if it does not previously exist. For Windows Server containers, the directory is created if it does not exist. Hence, for consistency between Windows Server and -Hyper-V containers, it is strongly recommended to include an explict instruction +Hyper-V containers, it is strongly recommended to include an explicit instruction to create the directory in the Dockerfile. For example: # escape=` From 701b16e21c55040a9443ca8fb733352f9cc45999 Mon Sep 17 00:00:00 2001 From: Addam Hardy Date: Sat, 15 Oct 2016 22:37:15 -0500 Subject: [PATCH 074/152] Convert Unused ARG error to warning Signed-off-by: Addam Hardy --- frontend/dockerfile/docs/reference.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index b3010a47d..68b2db1f6 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1286,12 +1286,12 @@ to create the directory in the Dockerfile. For example: ARG [=] The `ARG` instruction defines a variable that users can pass at build-time to -the builder with the `docker build` command using the -`--build-arg =` flag. If a user specifies a build argument -that was not defined in the Dockerfile, the build outputs an error. +the builder with the `docker build` command using the `--build-arg +=` flag. If a user specifies a build argument that was not +defined in the Dockerfile, the build outputs a warning. ``` -One or more build-args were not consumed, failing build. +[Warning] One or more build-args [foo] were not consumed. ``` The Dockerfile author can define a single variable by specifying `ARG` once or many From 6e3db95dd2634ad636cd0a030622f28b8919093b Mon Sep 17 00:00:00 2001 From: Gaetan de Villele Date: Thu, 3 Nov 2016 15:48:30 -0700 Subject: [PATCH 075/152] fix frontmatter keywords value type (string, instead of []string) in /docs/reference Signed-off-by: Gaetan de Villele --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 68b2db1f6..2b85edd98 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1,7 +1,7 @@ --- title: "Dockerfile reference" description: "Dockerfiles use a simple DSL which allows you to automate the steps you would normally manually take to create an image." -keywords: ["builder, docker, Dockerfile, automation, image creation"] +keywords: "builder, docker, Dockerfile, automation, image creation" --- 31f630c65071 - Step 2 : MAINTAINER SvenDowideit@home.org.au + Step 2/4 : MAINTAINER SvenDowideit@home.org.au ---> Using cache ---> 2a1c91448f5f - Step 3 : RUN apk update && apk add socat && rm -r /var/cache/ + Step 3/4 : RUN apk update && apk add socat && rm -r /var/cache/ ---> Using cache ---> 21ed6e7fbb73 - Step 4 : CMD env | grep _TCP= | (sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' && echo wait) | sh + Step 4/4 : CMD env | grep _TCP= | (sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' && echo wait) | sh ---> Using cache ---> 7ea8aef582cc Successfully built 7ea8aef582cc From 42f83861c3f330fa219cfc43c79124604b86c841 Mon Sep 17 00:00:00 2001 From: liwenqi Date: Tue, 20 Dec 2016 16:44:17 +0800 Subject: [PATCH 077/152] correct some words Signed-off-by: liwenqi Update ISSUE-TRIAGE.md Signed-off-by: vicky <395658237@qq.com> --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 3e28b54f5..a95385f90 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1754,6 +1754,6 @@ FROM ubuntu RUN echo moo > oink # Will output something like ===> 695d7793cbe4 -# You᾿ll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with +# You'll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with # /oink. ``` From d84740164f5a32d1404a14028f0da48f38ba0525 Mon Sep 17 00:00:00 2001 From: Victor Vieux Date: Fri, 20 Jan 2017 14:14:15 -0800 Subject: [PATCH 078/152] Merge pull request #30329 from johndmulhausen/patch-2 Fixing formatting errors in Run refdoc Signed-off-by: Misty Stanley-Jones --- frontend/dockerfile/docs/reference.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index a95385f90..988211932 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1286,8 +1286,8 @@ to create the directory in the Dockerfile. For example: ARG [=] The `ARG` instruction defines a variable that users can pass at build-time to -the builder with the `docker build` command using the `--build-arg -=` flag. If a user specifies a build argument that was not +the builder with the `docker build` command using the `--build-arg =` +flag. If a user specifies a build argument that was not defined in the Dockerfile, the build outputs a warning. ``` @@ -1375,7 +1375,7 @@ useful interactions between `ARG` and `ENV` instructions: ``` Unlike an `ARG` instruction, `ENV` values are always persisted in the built -image. Consider a docker build without the --build-arg flag: +image. Consider a docker build without the `--build-arg` flag: ``` $ docker build Dockerfile @@ -1638,9 +1638,9 @@ The command invoked by docker will be: cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" - This is inefficient for two reasons. First, there is an un-necessary cmd.exe command - processor (aka shell) being invoked. Second, each `RUN` instruction in the *shell* - form requires an extra `powershell -command` prefixing the command. +This is inefficient for two reasons. First, there is an un-necessary cmd.exe command +processor (aka shell) being invoked. Second, each `RUN` instruction in the *shell* +form requires an extra `powershell -command` prefixing the command. To make this more efficient, one of two mechanisms can be employed. One is to use the JSON form of the RUN command such as: From fb7f253e3c4c9887248784efd87a9bfca3509cba Mon Sep 17 00:00:00 2001 From: Michael Friis Date: Sun, 22 Jan 2017 10:46:04 -0800 Subject: [PATCH 079/152] remove indent from .dockerignore example Signed-off-by: Michael Friis --- frontend/dockerfile/docs/reference.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 988211932..4c9ae7fba 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -403,9 +403,9 @@ Here is an example `.dockerignore` file: ``` # comment - */temp* - */*/temp* - temp? +*/temp* +*/*/temp* +temp? ``` This file causes the following build behavior: From 11e9d9e35d251ce291c6470a6fe770a302d735ff Mon Sep 17 00:00:00 2001 From: jroenf Date: Tue, 31 Jan 2017 22:54:16 +0100 Subject: [PATCH 080/152] Fix syntax in example Signed-off-by: Jeroen Franse --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 4c9ae7fba..e22e54390 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -709,7 +709,7 @@ it instead, as it enables setting any metadata you require, and can be viewed easily, for example with `docker inspect`. To set a label corresponding to the `MAINTAINER` field you could use: - LABEL maintainer "SvenDowideit@home.org.au" + LABEL maintainer="SvenDowideit@home.org.au" This will then be visible from `docker inspect` with the other labels. From 48a69de5d71212eceaf45277c9a350b5f791176c Mon Sep 17 00:00:00 2001 From: John Mulhausen Date: Tue, 31 Jan 2017 18:53:42 -0800 Subject: [PATCH 081/152] Fix for https://github.com/docker/docker.github.io/issues/1413 Signed-off-by: John Mulhausen --- frontend/dockerfile/docs/reference.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index e22e54390..df7d63c98 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -2,6 +2,8 @@ title: "Dockerfile reference" description: "Dockerfiles use a simple DSL which allows you to automate the steps you would normally manually take to create an image." keywords: "builder, docker, Dockerfile, automation, image creation" +redirect_from: +- /reference/builder/ --- 89b8556cb9ca Step 2/5 : WORKDIR c:\installer ---> 7e0f41d08204 Removing intermediate container 236c7802042a Step 3/5 : ENV GOROOT c:\installer ---> Running in 8ea5237183c1 ---> 394b70435261 Removing intermediate container 8ea5237183c1 Step 4/5 : ADD go.exe . ---> e47401a1745c Removing intermediate container 88dcc28e74b1 Step 5/5 : RUN go --help ---> Running in efe90e1b6b8b container efe90e1b6b8b76586abc5c1dc0e2797b75adc26517c48733d90651e767c8463b encountered an error during CreateProcess: failure in a Windows system call: The directory name is invalid. (0x10b) extra info: {"ApplicationName":"","CommandLine":"cmd /S /C go --help","User":"","WorkingDirectory":"C:\\installer","Environment":{"GOROOT":"c:\\installer"},"EmulateConsole":false,"CreateStdInPipe":true,"CreateStdOutPipe":true,"CreateStdErrPipe":true,"ConsoleSize":[0,0]} PS E:\docker\build\unifyworkdir> Then forcing process isolation: PS E:\docker\build\unifyworkdir> docker build --isolation=process --no-cache . Sending build context to Docker daemon 10.1 MB Step 1/5 : FROM microsoft/nanoserver ---> 89b8556cb9ca Step 2/5 : WORKDIR c:\installer ---> 350c955980c8 Removing intermediate container 8339c1e9250c Step 3/5 : ENV GOROOT c:\installer ---> Running in bde511c5e3e0 ---> b8820063b5b6 Removing intermediate container bde511c5e3e0 Step 4/5 : ADD go.exe . ---> e4ac32f8902b Removing intermediate container d586e8492eda Step 5/5 : RUN go --help ---> Running in 9e1aa235af5f Cannot mkdir: C:\installer is not a directory PS E:\docker\build\unifyworkdir> Now compare the same results after this PR. Again, first with no explicit isolation (defaulting to Hyper-V containers as that's what the daemon it set to) - note it now succeeds 😄 PS E:\docker\build\unifyworkdir> docker build --no-cache . Sending build context to Docker daemon 10.1 MB Step 1/5 : FROM microsoft/nanoserver ---> 89b8556cb9ca Step 2/5 : WORKDIR c:\installer ---> 4f319f301c69 Removing intermediate container 61b9c0b1ff6f Step 3/5 : ENV GOROOT c:\installer ---> Running in c464a1d612d8 ---> 96a26ab9a7b5 Removing intermediate container c464a1d612d8 Step 4/5 : ADD go.exe . ---> 0290d61faf57 Removing intermediate container dc5a085fffe3 Step 5/5 : RUN go --help ---> Running in 60bd56042ff8 Go is a tool for managing Go source code. Usage: go command [arguments] The commands are: build compile packages and dependencies clean remove object files doc show documentation for package or symbol env print Go environment information fix run go tool fix on packages fmt run gofmt on package sources generate generate Go files by processing source get download and install packages and dependencies install compile and install packages and dependencies list list packages run compile and run Go program test test packages tool run specified go tool version print Go version vet run go tool vet on packages Use "go help [command]" for more information about a command. Additional help topics: c calling between Go and C buildmode description of build modes filetype file types gopath GOPATH environment variable environment environment variables importpath import path syntax packages description of package lists testflag description of testing flags testfunc description of testing functions Use "go help [topic]" for more information about that topic. The command 'cmd /S /C go --help' returned a non-zero code: 2 And the same with forcing process isolation. Also works 😄 PS E:\docker\build\unifyworkdir> docker build --isolation=process --no-cache . Sending build context to Docker daemon 10.1 MB Step 1/5 : FROM microsoft/nanoserver ---> 89b8556cb9ca Step 2/5 : WORKDIR c:\installer ---> f423b9cc3e78 Removing intermediate container 41330c88893d Step 3/5 : ENV GOROOT c:\installer ---> Running in 0b99a2d7bf19 ---> e051144bf8ec Removing intermediate container 0b99a2d7bf19 Step 4/5 : ADD go.exe . ---> 7072e32b7c37 Removing intermediate container a7a97aa37fd1 Step 5/5 : RUN go --help ---> Running in 7097438a54e5 Go is a tool for managing Go source code. Usage: go command [arguments] The commands are: build compile packages and dependencies clean remove object files doc show documentation for package or symbol env print Go environment information fix run go tool fix on packages fmt run gofmt on package sources generate generate Go files by processing source get download and install packages and dependencies install compile and install packages and dependencies list list packages run compile and run Go program test test packages tool run specified go tool version print Go version vet run go tool vet on packages Use "go help [command]" for more information about a command. Additional help topics: c calling between Go and C buildmode description of build modes filetype file types gopath GOPATH environment variable environment environment variables importpath import path syntax packages description of package lists testflag description of testing flags testfunc description of testing functions Use "go help [topic]" for more information about that topic. The command 'cmd /S /C go --help' returned a non-zero code: 2 PS E:\docker\build\unifyworkdir> --- frontend/dockerfile/docs/reference.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index df7d63c98..8dfc4d1fb 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1270,19 +1270,6 @@ For example: The output of the final `pwd` command in this `Dockerfile` would be `/path/$DIRNAME` -On Windows, `WORKDIR` behaves differently depending on whether using Windows -Server containers or Hyper-V containers. For Hyper-V containers, the engine -is, for architectural reasons, unable to create the directory if it does not -previously exist. For Windows Server containers, the directory is created -if it does not exist. Hence, for consistency between Windows Server and -Hyper-V containers, it is strongly recommended to include an explicit instruction -to create the directory in the Dockerfile. For example: - - # escape=` - FROM microsoft/nanoserver - RUN mkdir c:\myapp - WORKDIR c:\myapp - ## ARG ARG [=] From 23c1164e779cbde2e35692f02c4201cf4762ac63 Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Mon, 13 Feb 2017 11:01:54 -0800 Subject: [PATCH 083/152] Convert script shebangs from "#!/bin/bash" to "#!/usr/bin/env bash" This is especially important for distributions like NixOS where `/bin/bash` doesn't exist, or for MacOS users who've installed a newer version of Bash than the one that comes with their OS. Signed-off-by: Andrew "Tianon" Page --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 8dfc4d1fb..8c39b512c 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1029,7 +1029,7 @@ the final executable receives the Unix signals by using `exec` and `gosu` commands: ```bash -#!/bin/bash +#!/usr/bin/env bash set -e if [ "$1" = 'postgres' ]; then From 3c5a2368b41a70d4a26505abcec813d1589dc3ac Mon Sep 17 00:00:00 2001 From: Remy Suen Date: Fri, 10 Mar 2017 07:11:30 +0900 Subject: [PATCH 084/152] Fix directive example to match description The description claims the directive is appearing after a comment but the sample Dockerfile has the directive appear after an instruction. Changed the ordering of the lines to match the example's description. Signed-off-by: Remy Suen --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 8c39b512c..75c7e0c0c 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -199,8 +199,8 @@ directive: ```Dockerfile # About my dockerfile -FROM ImageName # directive=value +FROM ImageName ``` The unknown directive is treated as a comment due to not being recognized. In From dd1701ac483f49752db0f1532195ed25fc23af9b Mon Sep 17 00:00:00 2001 From: Dave Tucker Date: Mon, 6 Mar 2017 14:46:15 +0000 Subject: [PATCH 085/152] Ignore built-in allowed build-args in image history Removes the build-args from the image history if they are in the BuiltinAllowedBuildArgs map unless they are explicitly defined in an ARG instruction. Signed-off-by: Dave Tucker --- frontend/dockerfile/docs/reference.md | 31 +++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 75c7e0c0c..fa8b3e138 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1396,6 +1396,35 @@ To use these, simply pass them on the command line using the flag: --build-arg = ``` +By default, these pre-defined variables are excluded from the output of +`docker history`. Excluding them reduces the risk of accidentally leaking +sensitive authentication information in an `HTTP_PROXY` variable. + +For example, consider building the following Dockerfile using +`--build-arg HTTP_PROXY=http://user:pass@proxy.lon.example.com` + +``` Dockerfile +FROM ubuntu +RUN echo "Hello World" +``` + +In this case, the value of the `HTTP_PROXY` variable is not available in the +`docker history` and is not cached. If you were to change location, and your +proxy server changed to `http://user:pass@proxy.sfo.example.com`, a subsequent +build does not result in a cache miss. + +If you need to override this behaviour then you may do so by adding an `ARG` +statement in the Dockerfile as follows: + +``` Dockerfile +FROM ubuntu +ARG HTTP_PROXY +RUN echo "Hello World" +``` + +When building this Dockerfile, the `HTTP_PROXY` is preserved in the +`docker history`, and changing its value invalidates the build cache. + ### Impact on build caching `ARG` variables are not persisted into the built image as `ENV` variables are. @@ -1404,6 +1433,8 @@ Dockerfile defines an `ARG` variable whose value is different from a previous build, then a "cache miss" occurs upon its first usage, not its definition. In particular, all `RUN` instructions following an `ARG` instruction use the `ARG` variable implicitly (as an environment variable), thus can cause a cache miss. +All predefined `ARG` variables are exempt from caching unless there is a +matching `ARG` statement in the `Dockerfile`. For example, consider these two Dockerfile: From e00055ef1ffe043ccd127e582b530226ee455115 Mon Sep 17 00:00:00 2001 From: John Maguire Date: Tue, 21 Mar 2017 15:30:04 -0400 Subject: [PATCH 086/152] Add note regarding Windows VOLUME limitations Signed-off-by: John Maguire --- frontend/dockerfile/docs/reference.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index fa8b3e138..72ad7670f 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1222,6 +1222,11 @@ This Dockerfile results in an image that causes `docker run`, to create a new mount point at `/myvol` and copy the `greeting` file into the newly created volume. +> **Note**: +> When using Windows-based containers, the destination of a volume inside the +> container must be one of: a non-existing or empty directory; or a drive other +> than C:. + > **Note**: > If any build steps change the data within the volume after it has been > declared, those changes will be discarded. From a47576b18b3f70fac20dc1c87c3290393ab8fea7 Mon Sep 17 00:00:00 2001 From: Foysal Iqbal Date: Tue, 21 Mar 2017 15:22:29 -0400 Subject: [PATCH 087/152] remove the duplicate line from doc and rebase with master for 'example of ADD and COPY with special characters file name' Signed-off-by: Foysal Iqbal --- frontend/dockerfile/docs/reference.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 72ad7670f..8550b0a4f 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -803,6 +803,14 @@ the source will be copied inside the destination container. ADD test relativeDir/ # adds "test" to `WORKDIR`/relativeDir/ ADD test /absoluteDir/ # adds "test" to /absoluteDir/ +When adding files or directories that contain special characters (such as `[` +and `]`), you need to escape those paths following the Golang rules to prevent +them from being treated as a matching pattern. For example, to add a file +named `arr[0].txt`, use the following; + + ADD arr[[]0].txt /mydir/ # copy a file named "arr[0].txt" to /mydir/ + + All new files and directories are created with a UID and GID of 0. In the case where `` is a remote file URL, the destination will @@ -915,6 +923,14 @@ the source will be copied inside the destination container. COPY test relativeDir/ # adds "test" to `WORKDIR`/relativeDir/ COPY test /absoluteDir/ # adds "test" to /absoluteDir/ + +When copying files or directories that contain special characters (such as `[` +and `]`), you need to escape those paths following the Golang rules to prevent +them from being treated as a matching pattern. For example, to copy a file +named `arr[0].txt`, use the following; + + COPY arr[[]0].txt /mydir/ # copy a file named "arr[0].txt" to /mydir/ + All new files and directories are created with a UID and GID of 0. > **Note**: From 56e47243fc7854b732addb83050dcb885cc13bbc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Elias=20Fax=C3=B6?= Date: Tue, 29 Nov 2016 10:58:47 +0100 Subject: [PATCH 088/152] Added start period option to health check. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Elias Faxö --- frontend/dockerfile/docs/reference.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 8550b0a4f..426190450 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1591,6 +1591,7 @@ The options that can appear before `CMD` are: * `--interval=DURATION` (default: `30s`) * `--timeout=DURATION` (default: `30s`) +* `--start-period=DURATION` (default: `0s`) * `--retries=N` (default: `3`) The health check will first run **interval** seconds after the container is @@ -1602,6 +1603,11 @@ is considered to have failed. It takes **retries** consecutive failures of the health check for the container to be considered `unhealthy`. +**start period** provides initialization time for containers that need time to bootstrap. +Probe failure during that period will not be counted towards the maximum number of retries. +However, if a health check succeeds during the start period, the container is considered +started and all consecutive failures will be counted towards the maximum number of retries. + There can only be one `HEALTHCHECK` instruction in a Dockerfile. If you list more than one then only the last `HEALTHCHECK` will take effect. From 20a1b80f635342716774c2ca9f5e9e57191174eb Mon Sep 17 00:00:00 2001 From: Tonis Tiigi Date: Tue, 4 Apr 2017 12:31:00 -0700 Subject: [PATCH 089/152] Add docs for named build stages Signed-off-by: Tonis Tiigi --- frontend/dockerfile/docs/reference.md | 39 ++++++++++++++++++--------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 426190450..523fd2f80 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -480,30 +480,36 @@ the first pattern, followed by one or more `!` exception patterns. ## FROM - FROM + FROM [AS ] Or - FROM : + FROM [:] [AS ] Or - FROM @ + FROM [@] [AS ] -The `FROM` instruction sets the [*Base Image*](glossary.md#base-image) -for subsequent instructions. As such, a valid `Dockerfile` must have `FROM` as -its first instruction. The image can be any valid image – it is especially easy -to start by **pulling an image** from the [*Public Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/). +The `FROM` instruction initializes a new build stage and sets the +[*Base Image*](glossary.md#base-image) for subsequent instructions. As such, a +valid `Dockerfile` must have `FROM` as its first instruction. The image can be +any valid image – it is especially easy to start by **pulling an image** from +the [*Public Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/). - `FROM` must be the first non-comment instruction in the `Dockerfile`. -- `FROM` can appear multiple times within a single `Dockerfile` in order to create -multiple images. Simply make a note of the last image ID output by the commit -before each new `FROM` command. +- `FROM` can appear multiple times within a single `Dockerfile` in order to +create multiple images or use one build stage as a dependency for another. +Simply make a note of the last image ID output by the commit before each new +`FROM` command. Each `FROM` command resets all the previous commands. -- The `tag` or `digest` values are optional. If you omit either of them, the builder -assumes a `latest` by default. The builder returns an error if it cannot match -the `tag` value. +- Optionally a name can be given to a new build stage. That name can be then +used in subsequent `FROM` and `COPY --from=` commands to refer back +to the image built in this stage. + +- The `tag` or `digest` values are optional. If you omit either of them, the +builder assumes a `latest` tag by default. The builder returns an error if it +cannot match the `tag` value. ## RUN @@ -937,6 +943,13 @@ All new files and directories are created with a UID and GID of 0. > If you build using STDIN (`docker build - < somefile`), there is no > build context, so `COPY` can't be used. +Optionally `COPY` accepts a flag `--from=` that can be used to set +the source location to a previous build stage (created with `FROM .. AS `) +that will be used instead of a build context sent by the user. The flag also +accepts a numeric index assigned for all previous build stages started with +`FROM` command. In case a build stage with a specified name can't be found an +image with the same name is attempted to be used instead. + `COPY` obeys the following rules: - The `` path must be inside the *context* of the build; From a1bf74f7ffb337c8710a9a47bfac765a71aacf54 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Mon, 10 Apr 2017 15:45:21 -0400 Subject: [PATCH 090/152] Add Dockerfile reference docs for using ARG in FROM Also fixed some examples of using `docker build` to clarify that the positional argument is a directory, not a file. Also fixed some terminology. Dockerfiles contain instructions, not directives or commands. Signed-off-by: Daniel Nephin --- frontend/dockerfile/docs/reference.md | 67 +++++++++++++++++---------- 1 file changed, 43 insertions(+), 24 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 523fd2f80..9c28e8b47 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -135,9 +135,11 @@ The instruction is not case-sensitive. However, convention is for them to be UPPERCASE to distinguish them from arguments more easily. -Docker runs instructions in a `Dockerfile` in order. **The first -instruction must be \`FROM\`** in order to specify the [*Base -Image*](glossary.md#base-image) from which you are building. +Docker runs instructions in a `Dockerfile` in order. A `Dockerfile` **must +start with a \`FROM\` instruction**. The `FROM` instruction specifies the [*Base +Image*](glossary.md#base-image) from which you are building. `FROM` may only be +proceeded by one or more `ARG` instructions, which declare arguments that are used +in `FROM` lines in the `Dockerfile`. Docker treats lines that *begin* with `#` as a comment, unless the line is a valid [parser directive](#parser-directives). A `#` marker anywhere @@ -356,11 +358,12 @@ the `Dockerfile`: * `COPY` * `ENV` * `EXPOSE` +* `FROM` * `LABEL` -* `USER` -* `WORKDIR` -* `VOLUME` * `STOPSIGNAL` +* `USER` +* `VOLUME` +* `WORKDIR` as well as: @@ -371,14 +374,14 @@ as well as: > variable, even when combined with any of the instructions listed above. Environment variable substitution will use the same value for each variable -throughout the entire command. In other words, in this example: +throughout the entire instruction. In other words, in this example: ENV abc=hello ENV abc=bye def=$abc ENV ghi=$abc will result in `def` having a value of `hello`, not `bye`. However, -`ghi` will have a value of `bye` because it is not part of the same command +`ghi` will have a value of `bye` because it is not part of the same instruction that set `abc` to `bye`. ## .dockerignore file @@ -469,7 +472,7 @@ All of the README files are included. The middle line has no effect because You can even use the `.dockerignore` file to exclude the `Dockerfile` and `.dockerignore` files. These files are still sent to the daemon -because it needs them to do its job. But the `ADD` and `COPY` commands +because it needs them to do its job. But the `ADD` and `COPY` instructions do not copy them to the image. Finally, you may want to specify which files to include in the @@ -492,24 +495,40 @@ Or The `FROM` instruction initializes a new build stage and sets the [*Base Image*](glossary.md#base-image) for subsequent instructions. As such, a -valid `Dockerfile` must have `FROM` as its first instruction. The image can be +valid `Dockerfile` must start with a `FROM` instruction. The image can be any valid image – it is especially easy to start by **pulling an image** from the [*Public Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/). -- `FROM` must be the first non-comment instruction in the `Dockerfile`. +- `ARG` is the only instruction that may proceed `FROM` in the `Dockerfile`. + See [Understand how ARG and FROM interact](#understand-how-arg-and-from-interact). -- `FROM` can appear multiple times within a single `Dockerfile` in order to -create multiple images or use one build stage as a dependency for another. -Simply make a note of the last image ID output by the commit before each new -`FROM` command. Each `FROM` command resets all the previous commands. +- `FROM` can appear multiple times within a single `Dockerfile` to + create multiple images or use one build stage as a dependency for another. + Simply make a note of the last image ID output by the commit before each new + `FROM` instruction. Each `FROM` instruction clears any state created by previous + instructions. -- Optionally a name can be given to a new build stage. That name can be then -used in subsequent `FROM` and `COPY --from=` commands to refer back -to the image built in this stage. +- Optionally a name can be given to a new build stage by adding `AS name` to the + `FROM` instruction. The name can be used in subsequent `FROM` and + `COPY --from=` instructions to refer to the image built in this stage. - The `tag` or `digest` values are optional. If you omit either of them, the -builder assumes a `latest` tag by default. The builder returns an error if it -cannot match the `tag` value. + builder assumes a `latest` tag by default. The builder returns an error if it + cannot find the `tag` value. + +### Understand how ARG and FROM interact + +`FROM` instructions support variables that are declared by any `ARG` +instructions that occur before the first `FROM`. + +```Dockerfile +ARG CODE_VERSION=latest +FROM base:${CODE_VERSION} +CMD /code/run-app + +FROM extras:${CODE_VERSION} +CMD /code/run-extras +``` ## RUN @@ -947,7 +966,7 @@ Optionally `COPY` accepts a flag `--from=` that can be used to set the source location to a previous build stage (created with `FROM .. AS `) that will be used instead of a build context sent by the user. The flag also accepts a numeric index assigned for all previous build stages started with -`FROM` command. In case a build stage with a specified name can't be found an +`FROM` instruction. In case a build stage with a specified name can't be found an image with the same name is attempted to be used instead. `COPY` obeys the following rules: @@ -1353,7 +1372,7 @@ elsewhere. For example, consider this Dockerfile: A user builds this file by calling: ``` -$ docker build --build-arg user=what_user Dockerfile +$ docker build --build-arg user=what_user . ``` The `USER` at line 2 evaluates to `some_user` as the `user` variable is defined on the @@ -1379,7 +1398,7 @@ this Dockerfile with an `ENV` and `ARG` instruction. Then, assume this image is built with this command: ``` -$ docker build --build-arg CONT_IMG_VER=v2.0.1 Dockerfile +$ docker build --build-arg CONT_IMG_VER=v2.0.1 . ``` In this case, the `RUN` instruction uses `v1.0.0` instead of the `ARG` setting @@ -1401,7 +1420,7 @@ Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. Consider a docker build without the `--build-arg` flag: ``` -$ docker build Dockerfile +$ docker build . ``` Using this Dockerfile example, `CONT_IMG_VER` is still persisted in the image but From 7dda03c0f211c662a741b462e65c6a7acccd6937 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Fri, 12 May 2017 18:45:08 -0400 Subject: [PATCH 091/152] Document arg before from Signed-off-by: Daniel Nephin --- frontend/dockerfile/docs/reference.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 9c28e8b47..2571511b6 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -530,6 +530,17 @@ FROM extras:${CODE_VERSION} CMD /code/run-extras ``` +To use the default value of an `ARG` declared before the first `FROM` use an +`ARG` instruction without a value: + +```Dockerfile +ARG SETTINGS=default + +FROM busybox +ARG SETTINGS + +``` + ## RUN RUN has 2 forms: From be4cc777d5722c7b2dfd298b52b94e787f8637e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?T=C3=B5nis=20Tiigi?= Date: Thu, 20 Apr 2017 20:11:26 -0700 Subject: [PATCH 092/152] Merge pull request #32684 from scjane/patch-3 Update builder.md (cherry picked from commit 831066337743fc29ff122fce51afe44b8b3b3ba9) Signed-off-by: Sebastiaan van Stijn (cherry picked from commit bc66821abbcf50c721ce9b8f52b339fda102d389) Signed-off-by: Tibor Vass --- frontend/dockerfile/docs/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 2571511b6..502e41dfb 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -94,8 +94,8 @@ instructions. Whenever possible, Docker will re-use the intermediate images (cache), to accelerate the `docker build` process significantly. This is indicated by the `Using cache` message in the console output. -(For more information, see the [Build cache section](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/#/build-cache)) in the -`Dockerfile` best practices guide: +(For more information, see the [Build cache section](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/#build-cache) in the +`Dockerfile` best practices guide): $ docker build -t svendowideit/ambassador . Sending build context to Docker daemon 15.36 kB From 3c2a387c2ad96e89bc2db45116e5132b1e137f34 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 25 Apr 2017 10:18:16 -0700 Subject: [PATCH 093/152] Merge pull request #32735 from bhavin192/patch-1 Add note about host-dir in VOLUME (cherry picked from commit f2fff9d913a8ab0436dd56033189a7c3713a59a2) Signed-off-by: Sebastiaan van Stijn (cherry picked from commit 8fd6547fc3eb67e7efa7efb007ae6a4494cd2bb3) Signed-off-by: Tibor Vass --- frontend/dockerfile/docs/reference.md | 30 ++++++++++++++++++--------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 502e41dfb..f8ef9cf56 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1281,18 +1281,28 @@ This Dockerfile results in an image that causes `docker run`, to create a new mount point at `/myvol` and copy the `greeting` file into the newly created volume. -> **Note**: -> When using Windows-based containers, the destination of a volume inside the -> container must be one of: a non-existing or empty directory; or a drive other -> than C:. +### Notes about specifying volumes -> **Note**: -> If any build steps change the data within the volume after it has been -> declared, those changes will be discarded. +Keep the following things in mind about volumes in the `Dockerfile`. -> **Note**: -> The list is parsed as a JSON array, which means that -> you must use double-quotes (") around words not single-quotes ('). +- **Volumes on Windows-based containers**: When using Windows-based containers, + the destination of a volume inside the container must be one of: + + - a non-existing or empty directory + - a drive other than `C:` + +- **Changing the volume from within the Dockerfile**: If any build steps change the + data within the volume after it has been declared, those changes will be discarded. + +- **JSON formatting**: The list is parsed as a JSON array. + You must enclose words with double quotes (`"`)rather than single quotes (`'`). + +- **The host directory is declared at container run-time**: The host directory + (the mountpoint) is, by its nature, host-dependent. This is to preserve image + portability. since a given host directory can't be guaranteed to be available + on all hosts.For this reason, you can't mount a host directory from + within the Dockerfile. The `VOLUME` instruction does not support specifying a `host-dir` + parameter. You must specify the mountpoint when you create or run the container. ## USER From c25403fb88493b318cf178184e73eb500f2a214a Mon Sep 17 00:00:00 2001 From: Slava Semushin Date: Wed, 7 Jun 2017 18:50:16 +0200 Subject: [PATCH 094/152] docs/reference/builder.md: mention that USER directive also allows to specify the user group. Signed-off-by: Slava Semushin --- frontend/dockerfile/docs/reference.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index f8ef9cf56..9ab4ba4df 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1306,11 +1306,18 @@ Keep the following things in mind about volumes in the `Dockerfile`. ## USER - USER daemon + USER [:] +or + USER [:] + +The `USER` instruction sets the user name (or UID) and optionally the user +group (or GID) to use when running the image and for any `RUN`, `CMD` and +`ENTRYPOINT` instructions that follow it in the `Dockerfile`. + +> **Warning**: +> When the user does doesn't have a primary group then the image (or the next +> instructions) will be run with the `root` group. -The `USER` instruction sets the user name or UID to use when running the image -and for any `RUN`, `CMD` and `ENTRYPOINT` instructions that follow it in the -`Dockerfile`. ## WORKDIR From f7ec3e2c968198f5ff7ed089151394878d09a10e Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 26 Jun 2017 18:46:45 -0700 Subject: [PATCH 095/152] Some builder docs improvements Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 9ab4ba4df..d6274407e 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -30,13 +30,13 @@ Practices](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-pr ## Usage The [`docker build`](commandline/build.md) command builds an image from -a `Dockerfile` and a *context*. The build's context is the files at a specified -location `PATH` or `URL`. The `PATH` is a directory on your local filesystem. -The `URL` is a Git repository location. +a `Dockerfile` and a *context*. The build's context is the set of files at a +specified location `PATH` or `URL`. The `PATH` is a directory on your local +filesystem. The `URL` is a Git repository location. A context is processed recursively. So, a `PATH` includes any subdirectories and -the `URL` includes the repository and its submodules. A simple build command -that uses the current directory as context: +the `URL` includes the repository and its submodules. This example shows a +build command that uses the current directory as context: $ docker build . Sending build context to Docker daemon 6.51 MB @@ -1328,9 +1328,9 @@ The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`, If the `WORKDIR` doesn't exist, it will be created even if it's not used in any subsequent `Dockerfile` instruction. -It can be used multiple times in the one `Dockerfile`. If a relative path -is provided, it will be relative to the path of the previous `WORKDIR` -instruction. For example: +The `WORKDIR` instruction can be used multiple times in a `Dockerfile`. If a +relative path is provided, it will be relative to the path of the previous +`WORKDIR` instruction. For example: WORKDIR /a WORKDIR b From ef44ed84dc04840b0e0713f2be75f0ca69534224 Mon Sep 17 00:00:00 2001 From: Valentin Lorentz Date: Fri, 7 Jul 2017 13:17:15 +0200 Subject: [PATCH 096/152] Fix typo (proceed -> precede) Signed-off-by: Valentin Lorentz --- frontend/dockerfile/docs/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index d6274407e..65f6e05f0 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -138,7 +138,7 @@ be UPPERCASE to distinguish them from arguments more easily. Docker runs instructions in a `Dockerfile` in order. A `Dockerfile` **must start with a \`FROM\` instruction**. The `FROM` instruction specifies the [*Base Image*](glossary.md#base-image) from which you are building. `FROM` may only be -proceeded by one or more `ARG` instructions, which declare arguments that are used +preceded by one or more `ARG` instructions, which declare arguments that are used in `FROM` lines in the `Dockerfile`. Docker treats lines that *begin* with `#` as a comment, unless the line is @@ -499,7 +499,7 @@ valid `Dockerfile` must start with a `FROM` instruction. The image can be any valid image – it is especially easy to start by **pulling an image** from the [*Public Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/). -- `ARG` is the only instruction that may proceed `FROM` in the `Dockerfile`. +- `ARG` is the only instruction that may precede `FROM` in the `Dockerfile`. See [Understand how ARG and FROM interact](#understand-how-arg-and-from-interact). - `FROM` can appear multiple times within a single `Dockerfile` to From 9d5f49405a42b0eb5b21ebad143d5e422edf0a66 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Thu, 13 Jul 2017 12:30:38 -0400 Subject: [PATCH 097/152] Clarify docs about ARG in FROM Signed-off-by: Daniel Nephin --- frontend/dockerfile/docs/reference.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 65f6e05f0..b0e40010f 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -530,8 +530,10 @@ FROM extras:${CODE_VERSION} CMD /code/run-extras ``` -To use the default value of an `ARG` declared before the first `FROM` use an -`ARG` instruction without a value: +An `ARG` declared before a `FROM` is outside of a build stage, so it +can't be used in any instruction after a `FROM`. To use the default value of +an `ARG` declared before the first `FROM` use an `ARG` instruction without +a value inside of a build stage: ```Dockerfile ARG SETTINGS=default From 503fba33267b7aec1ae83c72be57afc25f120c26 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Thu, 13 Jul 2017 14:26:37 -0400 Subject: [PATCH 098/152] More about ARG and build stages. Signed-off-by: Daniel Nephin --- frontend/dockerfile/docs/reference.md | 47 +++++++++++++++++++-------- 1 file changed, 34 insertions(+), 13 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index b0e40010f..16c1b48d3 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -536,11 +536,10 @@ an `ARG` declared before the first `FROM` use an `ARG` instruction without a value inside of a build stage: ```Dockerfile -ARG SETTINGS=default - -FROM busybox -ARG SETTINGS - +ARG VERSION=latest +FROM busybox:$VERSION +ARG VERSION +RUN echo $VERSION > image_version ``` ## RUN @@ -1366,8 +1365,8 @@ defined in the Dockerfile, the build outputs a warning. [Warning] One or more build-args [foo] were not consumed. ``` -The Dockerfile author can define a single variable by specifying `ARG` once or many -variables by specifying `ARG` more than once. For example, a valid Dockerfile: +A Dockerfile may include one or more `ARG` instructions. For example, +the following is a valid Dockerfile: ``` FROM busybox @@ -1376,7 +1375,13 @@ ARG buildno ... ``` -A Dockerfile author may optionally specify a default value for an `ARG` instruction: +> **Warning:** It is not recommended to use build-time variables for +> passing secrets like github keys, user credentials etc. Build-time variable +> values are visible to any user of the image with the `docker history` command. + +### Default values + +An `ARG` instruction can optionally include a default value: ``` FROM busybox @@ -1385,8 +1390,10 @@ ARG buildno=1 ... ``` -If an `ARG` value has a default and if there is no value passed at build-time, the -builder uses the default. +If an `ARG` instruction has a default value and if there is no value passed +at build-time, the builder uses the default. + +### Scope An `ARG` variable definition comes into effect from the line on which it is defined in the `Dockerfile` not from the argument's use on the command-line or @@ -1410,9 +1417,21 @@ subsequent line 3. The `USER` at line 4 evaluates to `what_user` as `user` is defined and the `what_user` value was passed on the command line. Prior to its definition by an `ARG` instruction, any use of a variable results in an empty string. -> **Warning:** It is not recommended to use build-time variables for -> passing secrets like github keys, user credentials etc. Build-time variable -> values are visible to any user of the image with the `docker history` command. +An `ARG` instruction goes out of scope at the end of the build +stage where it was defined. To use an arg in multiple stages, each stage must +include the `ARG` instruction. + +``` +FROM busybox +ARG SETTINGS +RUN ./run/setup $SETTINGS + +FROM busybox +ARG SETTINGS +RUN ./run/other $SETTINGS +``` + +### Using ARG variables You can use an `ARG` or an `ENV` instruction to specify variables that are available to the `RUN` instruction. Environment variables defined using the @@ -1461,6 +1480,8 @@ from the command line and persist them in the final image by leveraging the `ENV` instruction. Variable expansion is only supported for [a limited set of Dockerfile instructions.](#environment-replacement) +### Predefined ARGs + Docker has a set of predefined `ARG` variables that you can use without a corresponding `ARG` instruction in the Dockerfile. From 6f44932d4a6416f8050c4aa7ff59c0a3d0cb6e00 Mon Sep 17 00:00:00 2001 From: Kir Kolyshkin Date: Fri, 28 Jul 2017 10:28:23 -0700 Subject: [PATCH 099/152] Fix repo references in docs Since CLI was moved to a separate repo, these references are incorrect. Fixed with the help of sed script, verified manually. Signed-off-by: Kir Kolyshkin --- frontend/dockerfile/docs/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 16c1b48d3..cf4f79fae 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -6,8 +6,8 @@ redirect_from: - /reference/builder/ --- - Running in a2c157f842f5 Volume in drive C has no label. Volume Serial Number is 7E6D-E0F7 - + Directory of c:\ - + 10/05/2016 05:04 PM 1,894 License.txt 10/05/2016 02:22 PM Program Files 10/05/2016 02:14 PM Program Files (x86) @@ -381,7 +381,7 @@ throughout the entire instruction. In other words, in this example: ENV ghi=$abc will result in `def` having a value of `hello`, not `bye`. However, -`ghi` will have a value of `bye` because it is not part of the same instruction +`ghi` will have a value of `bye` because it is not part of the same instruction that set `abc` to `bye`. ## .dockerignore file @@ -415,12 +415,12 @@ temp? This file causes the following build behavior: -| Rule | Behavior | -|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `# comment` | Ignored. | -| `*/temp*` | Exclude files and directories whose names start with `temp` in any immediate subdirectory of the root. For example, the plain file `/somedir/temporary.txt` is excluded, as is the directory `/somedir/temp`. | -| `*/*/temp*` | Exclude files and directories starting with `temp` from any subdirectory that is two levels below the root. For example, `/somedir/subdir/temporary.txt` is excluded. | -| `temp?` | Exclude files and directories in the root directory whose names are a one-character extension of `temp`. For example, `/tempa` and `/tempb` are excluded. +| Rule | Behavior | +|:------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `# comment` | Ignored. | +| `*/temp*` | Exclude files and directories whose names start with `temp` in any immediate subdirectory of the root. For example, the plain file `/somedir/temporary.txt` is excluded, as is the directory `/somedir/temp`. | +| `*/*/temp*` | Exclude files and directories starting with `temp` from any subdirectory that is two levels below the root. For example, `/somedir/subdir/temporary.txt` is excluded. | +| `temp?` | Exclude files and directories in the root directory whose names are a one-character extension of `temp`. For example, `/tempa` and `/tempb` are excluded. | Matching is done using Go's @@ -493,32 +493,32 @@ Or FROM [@] [AS ] -The `FROM` instruction initializes a new build stage and sets the -[*Base Image*](glossary.md#base-image) for subsequent instructions. As such, a +The `FROM` instruction initializes a new build stage and sets the +[*Base Image*](glossary.md#base-image) for subsequent instructions. As such, a valid `Dockerfile` must start with a `FROM` instruction. The image can be -any valid image – it is especially easy to start by **pulling an image** from +any valid image – it is especially easy to start by **pulling an image** from the [*Public Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/). - `ARG` is the only instruction that may precede `FROM` in the `Dockerfile`. See [Understand how ARG and FROM interact](#understand-how-arg-and-from-interact). -- `FROM` can appear multiple times within a single `Dockerfile` to +- `FROM` can appear multiple times within a single `Dockerfile` to create multiple images or use one build stage as a dependency for another. - Simply make a note of the last image ID output by the commit before each new + Simply make a note of the last image ID output by the commit before each new `FROM` instruction. Each `FROM` instruction clears any state created by previous instructions. -- Optionally a name can be given to a new build stage by adding `AS name` to the +- Optionally a name can be given to a new build stage by adding `AS name` to the `FROM` instruction. The name can be used in subsequent `FROM` and `COPY --from=` instructions to refer to the image built in this stage. -- The `tag` or `digest` values are optional. If you omit either of them, the +- The `tag` or `digest` values are optional. If you omit either of them, the builder assumes a `latest` tag by default. The builder returns an error if it cannot find the `tag` value. ### Understand how ARG and FROM interact -`FROM` instructions support variables that are declared by any `ARG` +`FROM` instructions support variables that are declared by any `ARG` instructions that occur before the first `FROM`. ```Dockerfile @@ -754,20 +754,26 @@ This will then be visible from `docker inspect` with the other labels. ## EXPOSE - EXPOSE [...] + EXPOSE [/...] The `EXPOSE` instruction informs Docker that the container listens on the -specified network ports at runtime. `EXPOSE` does not make the ports of the -container accessible to the host. To do that, you must use either the `-p` flag -to publish a range of ports or the `-P` flag to publish all of the exposed -ports. You can expose one port number and publish it externally under another -number. +specified network ports at runtime. You can specify whether the port listens on +TCP or UDP, and the default is TCP if the protocol is not specified. + +The `EXPOSE` instruction does not actually publish the port. It functions as a +type of documentation between the person who builds the image and the person who +runs the container, about which ports are intended to be published. To actually +publish the port when running the container, use the `-p` flag on `docker run` +to publish and map one or more ports, or the `-P` flag to publish all exposed +ports and map them to to high-order ports. To set up port redirection on the host system, see [using the -P -flag](run.md#expose-incoming-ports). The Docker network feature supports -creating networks without the need to expose ports within the network, for -detailed information see the [overview of this -feature](https://docs.docker.com/engine/userguide/networking/)). +flag](run.md#expose-incoming-ports). The `docker network` command supports +creating networks for communication among containers without the need to +expose or publish specific ports, because the containers connected to the +network can communicate with each other over any port. For detailed information, +see the +[overview of this feature](https://docs.docker.com/engine/userguide/networking/)). ## ENV @@ -976,9 +982,9 @@ All new files and directories are created with a UID and GID of 0. Optionally `COPY` accepts a flag `--from=` that can be used to set the source location to a previous build stage (created with `FROM .. AS `) -that will be used instead of a build context sent by the user. The flag also -accepts a numeric index assigned for all previous build stages started with -`FROM` instruction. In case a build stage with a specified name can't be found an +that will be used instead of a build context sent by the user. The flag also +accepts a numeric index assigned for all previous build stages started with +`FROM` instruction. In case a build stage with a specified name can't be found an image with the same name is attempted to be used instead. `COPY` obeys the following rules: @@ -1250,7 +1256,7 @@ or for executing an ad-hoc command in a container. The table below shows what command is executed for different `ENTRYPOINT` / `CMD` combinations: | | No ENTRYPOINT | ENTRYPOINT exec_entry p1_entry | ENTRYPOINT ["exec_entry", "p1_entry"] | -|--------------------------------|----------------------------|--------------------------------|------------------------------------------------| +|:-------------------------------|:---------------------------|:-------------------------------|:-----------------------------------------------| | **No CMD** | *error, not allowed* | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry | | **CMD ["exec_cmd", "p1_cmd"]** | exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry exec_cmd p1_cmd | | **CMD ["p1_cmd", "p2_cmd"]** | p1_cmd p2_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry p1_cmd p2_cmd | @@ -1288,7 +1294,7 @@ Keep the following things in mind about volumes in the `Dockerfile`. - **Volumes on Windows-based containers**: When using Windows-based containers, the destination of a volume inside the container must be one of: - + - a non-existing or empty directory - a drive other than `C:` @@ -1805,16 +1811,16 @@ Resulting in: Removing intermediate container 6fcdb6855ae2 Step 3/5 : RUN New-Item -ItemType Directory C:\Example ---> Running in d0eef8386e97 - - + + Directory: C:\ - - + + Mode LastWriteTime Length Name ---- ------------- ------ ---- d----- 10/28/2016 11:26 AM Example - - + + ---> 3f2fbf1395d9 Removing intermediate container d0eef8386e97 Step 4/5 : ADD Execute-MyCmdlet.ps1 c:\example\ From f469e32354fcab46946bf90d0eb9762fff981ca6 Mon Sep 17 00:00:00 2001 From: Frieder Bluemle Date: Thu, 5 Oct 2017 01:03:55 +0800 Subject: [PATCH 101/152] Fix GitHub spelling Signed-off-by: Frieder Bluemle --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index f7f717d24..652cdb688 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -6,7 +6,7 @@ redirect_from: - /reference/builder/ --- - -# Dockerfile reference Docker can build images automatically by reading the instructions from a `Dockerfile`. A `Dockerfile` is a text document that contains all the commands a From 87f0c7e5a8b598ef67aa9c6db8bf7cd5da6c7544 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sun, 19 Apr 2020 15:46:48 +0200 Subject: [PATCH 124/152] docs/builder: touch up markdown, and some minor rephrasing - add code-fences with code-hints so that the right hightlighting is applied - replace `*` for `-` in bullet-lists for consistency with other parts of the documentation. - reduced number of "notes", either by combining some, or by changing some to regular text. - removed "line numbers" from some examples, because there's only four lines, which should not need really need line numbers. - reformat some notes to our new format Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 1161 +++++++++++++++---------- 1 file changed, 690 insertions(+), 471 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 5f3a9578e..80ecdf80c 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -37,9 +37,12 @@ A context is processed recursively. So, a `PATH` includes any subdirectories and the `URL` includes the repository and its submodules. This example shows a build command that uses the current directory as context: - $ docker build . - Sending build context to Docker daemon 6.51 MB - ... +```bash +$ docker build . + +Sending build context to Docker daemon 6.51 MB +... +``` The build is run by the Docker daemon, not by the CLI. The first thing a build process does is send the entire context (recursively) to the daemon. In most @@ -47,9 +50,10 @@ cases, it's best to start with an empty directory as context and keep your Dockerfile in that directory. Add only the files needed for building the Dockerfile. ->**Warning**: Do not use your root directory, `/`, as the `PATH` as it causes ->the build to transfer the entire contents of your hard drive to the Docker ->daemon. +> **Warning** +> +> Do not use your root directory, `/`, as the `PATH` as it causes the build to +> transfer the entire contents of your hard drive to the Docker daemon. To use a file in the build context, the `Dockerfile` refers to the file specified in an instruction, for example, a `COPY` instruction. To increase the build's @@ -61,24 +65,33 @@ Traditionally, the `Dockerfile` is called `Dockerfile` and located in the root of the context. You use the `-f` flag with `docker build` to point to a Dockerfile anywhere in your file system. - $ docker build -f /path/to/a/Dockerfile . +```bash +$ docker build -f /path/to/a/Dockerfile . +``` You can specify a repository and tag at which to save the new image if the build succeeds: - $ docker build -t shykes/myapp . +```bash +$ docker build -t shykes/myapp . +``` To tag the image into multiple repositories after the build, add multiple `-t` parameters when you run the `build` command: - $ docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest . +```bash +$ docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest . +``` Before the Docker daemon runs the instructions in the `Dockerfile`, it performs a preliminary validation of the `Dockerfile` and returns an error if the syntax is incorrect: - $ docker build -t test/myapp . - Sending build context to Docker daemon 2.048 kB - Error response from daemon: Unknown instruction: RUNCMD +```bash +$ docker build -t test/myapp . + +Sending build context to Docker daemon 2.048 kB +Error response from daemon: Unknown instruction: RUNCMD +``` The Docker daemon runs the instructions in the `Dockerfile` one-by-one, committing the result of each instruction @@ -95,20 +108,23 @@ to accelerate the `docker build` process significantly. This is indicated by the `Using cache` message in the console output. (For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/): - $ docker build -t svendowideit/ambassador . - Sending build context to Docker daemon 15.36 kB - Step 1/4 : FROM alpine:3.2 - ---> 31f630c65071 - Step 2/4 : MAINTAINER SvenDowideit@home.org.au - ---> Using cache - ---> 2a1c91448f5f - Step 3/4 : RUN apk update && apk add socat && rm -r /var/cache/ - ---> Using cache - ---> 21ed6e7fbb73 - Step 4/4 : CMD env | grep _TCP= | (sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' && echo wait) | sh - ---> Using cache - ---> 7ea8aef582cc - Successfully built 7ea8aef582cc +```bash +$ docker build -t svendowideit/ambassador . + +Sending build context to Docker daemon 15.36 kB +Step 1/4 : FROM alpine:3.2 + ---> 31f630c65071 +Step 2/4 : MAINTAINER SvenDowideit@home.org.au + ---> Using cache + ---> 2a1c91448f5f +Step 3/4 : RUN apk update && apk add socat && rm -r /var/cache/ + ---> Using cache + ---> 21ed6e7fbb73 +Step 4/4 : CMD env | grep _TCP= | (sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' && echo wait) | sh + ---> Using cache + ---> 7ea8aef582cc +Successfully built 7ea8aef582cc +``` Build cache is only used from images that have a local parent chain. This means that these images were created by previous builds or the whole chain of images @@ -128,13 +144,13 @@ builds that is provided by the [moby/buildkit](https://github.com/moby/buildkit) project. The BuildKit backend provides many benefits compared to the old implementation. For example, BuildKit can: -* Detect and skip executing unused build stages -* Parallelize building independent build stages -* Incrementally transfer only the changed files in your build context between builds -* Detect and skip transferring unused files in your build context -* Use external Dockerfile implementations with many new features -* Avoid side-effects with rest of the API (intermediate images and containers) -* Prioritize your build cache for automatic pruning +- Detect and skip executing unused build stages +- Parallelize building independent build stages +- Incrementally transfer only the changed files in your build context between builds +- Detect and skip transferring unused files in your build context +- Use external Dockerfile implementations with many new features +- Avoid side-effects with rest of the API (intermediate images and containers) +- Prioritize your build cache for automatic pruning To use the BuildKit backend, you need to set an environment variable `DOCKER_BUILDKIT=1` on the CLI before invoking `docker build`. @@ -249,20 +265,24 @@ following lines are all treated identically: The following parser directives are supported: -* `syntax` -* `escape` +- `syntax` +- `escape` ## syntax - # syntax=[remote image reference] +```dockerfile +# syntax=[remote image reference] +``` For example: - # syntax=docker/dockerfile - # syntax=docker/dockerfile:1.0 - # syntax=docker.io/docker/dockerfile:1 - # syntax=docker/dockerfile:1.0.0-experimental - # syntax=example.com/user/repo:tag@sha256:abcdef... +```dockerfile +# syntax=docker/dockerfile +# syntax=docker/dockerfile:1.0 +# syntax=docker.io/docker/dockerfile:1 +# syntax=docker/dockerfile:1.0.0-experimental +# syntax=example.com/user/repo:tag@sha256:abcdef... +``` This feature is only enabled if the [BuildKit](#buildkit) backend is used. @@ -272,6 +292,7 @@ external implementations of builders that are distributed as Docker images and execute inside a container sandbox environment. Custom Dockerfile implementation allows you to: + - Automatically get bugfixes without updating the daemon - Make sure all users are using the same implementation to build your Dockerfile - Use the latest features without updating the daemon @@ -285,17 +306,17 @@ channels where new images are released: stable and experimental. Stable channel follows semantic versioning. For example: - - docker/dockerfile:1.0.0 - only allow immutable version 1.0.0 - - docker/dockerfile:1.0 - allow versions 1.0.* - - docker/dockerfile:1 - allow versions 1.*.* - - docker/dockerfile:latest - latest release on stable channel + - `docker/dockerfile:1.0.0` - only allow immutable version `1.0.0` + - `docker/dockerfile:1.0` - allow versions `1.0.*` + - `docker/dockerfile:1` - allow versions `1.*.*` + - `docker/dockerfile:latest` - latest release on stable channel The experimental channel uses incremental versioning with the major and minor component from the stable channel on the time of the release. For example: - - docker/dockerfile:1.0.1-experimental - only allow immutable version 1.0.1-experimental - - docker/dockerfile:1.0-experimental - latest experimental releases after 1.0 - - docker/dockerfile:experimental - latest release on experimental channel + - `docker/dockerfile:1.0.1-experimental` - only allow immutable version `1.0.1-experimental` + - `docker/dockerfile:1.0-experimental` - latest experimental releases after `1.0` + - `docker/dockerfile:experimental` - latest release on experimental channel You should choose a channel that best fits your needs. If you only want bugfixes, you should use `docker/dockerfile:1.0`. If you want to benefit from @@ -303,15 +324,20 @@ experimental features, you should use the experimental channel. If you are using the experimental channel, newer releases may not be backwards compatible, so it is recommended to use an immutable full version variant. -For master builds and nightly feature releases refer to the description in [the source repository](https://github.com/moby/buildkit/blob/master/README.md). +For master builds and nightly feature releases refer to the description in +[the source repository](https://github.com/moby/buildkit/blob/master/README.md). ## escape - # escape=\ (backslash) +```dockerfile +# escape=\ (backslash) +``` Or - # escape=` (backtick) +```dockerfile +# escape=` (backtick) +``` The `escape` directive sets the character used to escape characters in a `Dockerfile`. If not specified, the default escape character is `\`. @@ -342,13 +368,15 @@ RUN dir c:\ Results in: - PS C:\John> docker build -t cmd . - Sending build context to Docker daemon 3.072 kB - Step 1/2 : FROM microsoft/nanoserver - ---> 22738ff49c6d - Step 2/2 : COPY testfile.txt c:\RUN dir c: - GetFileAttributesEx c:RUN: The system cannot find the file specified. - PS C:\John> +```powershell +PS C:\John> docker build -t cmd . +Sending build context to Docker daemon 3.072 kB +Step 1/2 : FROM microsoft/nanoserver + ---> 22738ff49c6d +Step 2/2 : COPY testfile.txt c:\RUN dir c: +GetFileAttributesEx c:RUN: The system cannot find the file specified. +PS C:\John> +``` One solution to the above would be to use `/` as the target of both the `COPY` instruction, and `dir`. However, this syntax is, at best, confusing as it is not @@ -358,40 +386,44 @@ natural for paths on `Windows`, and at worst, error prone as not all commands on By adding the `escape` parser directive, the following `Dockerfile` succeeds as expected with the use of natural platform semantics for file paths on `Windows`: - # escape=` +```dockerfile +# escape=` - FROM microsoft/nanoserver - COPY testfile.txt c:\ - RUN dir c:\ +FROM microsoft/nanoserver +COPY testfile.txt c:\ +RUN dir c:\ +``` Results in: - PS C:\John> docker build -t succeeds --no-cache=true . - Sending build context to Docker daemon 3.072 kB - Step 1/3 : FROM microsoft/nanoserver - ---> 22738ff49c6d - Step 2/3 : COPY testfile.txt c:\ - ---> 96655de338de - Removing intermediate container 4db9acbb1682 - Step 3/3 : RUN dir c:\ - ---> Running in a2c157f842f5 - Volume in drive C has no label. - Volume Serial Number is 7E6D-E0F7 +```powershell +PS C:\John> docker build -t succeeds --no-cache=true . +Sending build context to Docker daemon 3.072 kB +Step 1/3 : FROM microsoft/nanoserver + ---> 22738ff49c6d +Step 2/3 : COPY testfile.txt c:\ + ---> 96655de338de +Removing intermediate container 4db9acbb1682 +Step 3/3 : RUN dir c:\ + ---> Running in a2c157f842f5 + Volume in drive C has no label. + Volume Serial Number is 7E6D-E0F7 - Directory of c:\ + Directory of c:\ - 10/05/2016 05:04 PM 1,894 License.txt - 10/05/2016 02:22 PM Program Files - 10/05/2016 02:14 PM Program Files (x86) - 10/28/2016 11:18 AM 62 testfile.txt - 10/28/2016 11:20 AM Users - 10/28/2016 11:20 AM Windows - 2 File(s) 1,956 bytes - 4 Dir(s) 21,259,096,064 bytes free - ---> 01c7f3bef04f - Removing intermediate container a2c157f842f5 - Successfully built 01c7f3bef04f - PS C:\John> +10/05/2016 05:04 PM 1,894 License.txt +10/05/2016 02:22 PM Program Files +10/05/2016 02:14 PM Program Files (x86) +10/28/2016 11:18 AM 62 testfile.txt +10/28/2016 11:20 AM Users +10/28/2016 11:20 AM Windows + 2 File(s) 1,956 bytes + 4 Dir(s) 21,259,096,064 bytes free + ---> 01c7f3bef04f +Removing intermediate container a2c157f842f5 +Successfully built 01c7f3bef04f +PS C:\John> +``` ## Environment replacement @@ -408,9 +440,9 @@ whitespace, like `${foo}_bar`. The `${variable_name}` syntax also supports a few of the standard `bash` modifiers as specified below: -* `${variable:-word}` indicates that if `variable` is set then the result +- `${variable:-word}` indicates that if `variable` is set then the result will be that value. If `variable` is not set then `word` will be the result. -* `${variable:+word}` indicates that if `variable` is set then `word` will be +- `${variable:+word}` indicates that if `variable` is set then `word` will be the result, otherwise the result is the empty string. In all cases, `word` can be any string, including additional environment @@ -421,40 +453,37 @@ for example, will translate to `$foo` and `${foo}` literals respectively. Example (parsed representation is displayed after the `#`): - FROM busybox - ENV foo /bar - WORKDIR ${foo} # WORKDIR /bar - ADD . $foo # ADD . /bar - COPY \$foo /quux # COPY $foo /quux +```dockerfile +FROM busybox +ENV foo /bar +WORKDIR ${foo} # WORKDIR /bar +ADD . $foo # ADD . /bar +COPY \$foo /quux # COPY $foo /quux +``` Environment variables are supported by the following list of instructions in the `Dockerfile`: -* `ADD` -* `COPY` -* `ENV` -* `EXPOSE` -* `FROM` -* `LABEL` -* `STOPSIGNAL` -* `USER` -* `VOLUME` -* `WORKDIR` - -as well as: - -* `ONBUILD` (when combined with one of the supported instructions above) - -> **Note**: -> prior to 1.4, `ONBUILD` instructions did **NOT** support environment -> variable, even when combined with any of the instructions listed above. +- `ADD` +- `COPY` +- `ENV` +- `EXPOSE` +- `FROM` +- `LABEL` +- `STOPSIGNAL` +- `USER` +- `VOLUME` +- `WORKDIR` +- `ONBUILD` (when combined with one of the supported instructions above) Environment variable substitution will use the same value for each variable throughout the entire instruction. In other words, in this example: - ENV abc=hello - ENV abc=bye def=$abc - ENV ghi=$abc +```dockerfile +ENV abc=hello +ENV abc=bye def=$abc +ENV ghi=$abc +``` will result in `def` having a value of `hello`, not `bye`. However, `ghi` will have a value of `bye` because it is not part of the same instruction @@ -482,7 +511,7 @@ considered as a comment and is ignored before interpreted by the CLI. Here is an example `.dockerignore` file: -``` +```gitignore # comment */temp* */*/temp* @@ -515,9 +544,9 @@ Lines starting with `!` (exclamation mark) can be used to make exceptions to exclusions. The following is an example `.dockerignore` file that uses this mechanism: -``` - *.md - !README.md +```gitignore +*.md +!README.md ``` All markdown files *except* `README.md` are excluded from the context. @@ -526,10 +555,10 @@ The placement of `!` exception rules influences the behavior: the last line of the `.dockerignore` that matches a particular file determines whether it is included or excluded. Consider the following example: -``` - *.md - !README*.md - README-secret.md +```gitignore +*.md +!README*.md +README-secret.md ``` No markdown files are included in the context except README files other than @@ -537,10 +566,10 @@ No markdown files are included in the context except README files other than Now consider this example: -``` - *.md - README-secret.md - !README*.md +```gitignore +*.md +README-secret.md +!README*.md ``` All of the README files are included. The middle line has no effect because @@ -555,19 +584,27 @@ Finally, you may want to specify which files to include in the context, rather than which to exclude. To achieve this, specify `*` as the first pattern, followed by one or more `!` exception patterns. -**Note**: For historical reasons, the pattern `.` is ignored. +> **Note** +> +> For historical reasons, the pattern `.` is ignored. ## FROM - FROM [--platform=] [AS ] +```dockerfile +FROM [--platform=] [AS ] +``` Or - FROM [--platform=] [:] [AS ] +```dockerfile +FROM [--platform=] [:] [AS ] +``` Or - FROM [--platform=] [@] [AS ] +```dockerfile +FROM [--platform=] [@] [AS ] +``` The `FROM` instruction initializes a new build stage and sets the [*Base Image*](../../glossary/#base-image) for subsequent instructions. As such, a @@ -648,43 +685,53 @@ command. In the *shell* form you can use a `\` (backslash) to continue a single RUN instruction onto the next line. For example, consider these two lines: -``` +```dockerfile RUN /bin/bash -c 'source $HOME/.bashrc; \ echo $HOME' ``` Together they are equivalent to this single line: -``` +```dockerfile RUN /bin/bash -c 'source $HOME/.bashrc; echo $HOME' ``` -> **Note**: -> To use a different shell, other than '/bin/sh', use the *exec* form -> passing in the desired shell. For example, -> `RUN ["/bin/bash", "-c", "echo hello"]` +To use a different shell, other than '/bin/sh', use the *exec* form passing in +the desired shell. For example: -> **Note**: +```dockerfile +RUN ["/bin/bash", "-c", "echo hello"] +``` + +> **Note** +> > The *exec* form is parsed as a JSON array, which means that > you must use double-quotes (") around words not single-quotes ('). -> **Note**: -> Unlike the *shell* form, the *exec* form does not invoke a command shell. -> This means that normal shell processing does not happen. For example, -> `RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. -> If you want shell processing then either use the *shell* form or execute -> a shell directly, for example: `RUN [ "sh", "-c", "echo $HOME" ]`. -> When using the exec form and executing a shell directly, as in the case for -> the shell form, it is the shell that is doing the environment variable -> expansion, not docker. +Unlike the *shell* form, the *exec* form does not invoke a command shell. +This means that normal shell processing does not happen. For example, +`RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. +If you want shell processing then either use the *shell* form or execute +a shell directly, for example: `RUN [ "sh", "-c", "echo $HOME" ]`. +When using the exec form and executing a shell directly, as in the case for +the shell form, it is the shell that is doing the environment variable +expansion, not docker. + +> **Note** > -> **Note**: > In the *JSON* form, it is necessary to escape backslashes. This is > particularly relevant on Windows where the backslash is the path separator. > The following line would otherwise be treated as *shell* form due to not > being valid JSON, and fail in an unexpected way: -> `RUN ["c:\windows\system32\tasklist.exe"]` +> +> ```dockerfile +> RUN ["c:\windows\system32\tasklist.exe"] +> ``` +> > The correct syntax for this example is: -> `RUN ["c:\\windows\\system32\\tasklist.exe"]` +> +> ```dockerfile +> RUN ["c:\\windows\\system32\\tasklist.exe"] +> ``` The cache for `RUN` instructions isn't invalidated automatically during the next build. The cache for an instruction like @@ -727,24 +774,23 @@ container.** These defaults can include an executable, or they can omit the executable, in which case you must specify an `ENTRYPOINT` instruction as well. -> **Note**: -> If `CMD` is used to provide default arguments for the `ENTRYPOINT` -> instruction, both the `CMD` and `ENTRYPOINT` instructions should be specified -> with the JSON array format. +If `CMD` is used to provide default arguments for the `ENTRYPOINT` instruction, +both the `CMD` and `ENTRYPOINT` instructions should be specified with the JSON +array format. -> **Note**: -> The *exec* form is parsed as a JSON array, which means that -> you must use double-quotes (") around words not single-quotes ('). +> **Note** +> +> The *exec* form is parsed as a JSON array, which means that you must use +> double-quotes (") around words not single-quotes ('). -> **Note**: -> Unlike the *shell* form, the *exec* form does not invoke a command shell. -> This means that normal shell processing does not happen. For example, -> `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. -> If you want shell processing then either use the *shell* form or execute -> a shell directly, for example: `CMD [ "sh", "-c", "echo $HOME" ]`. -> When using the exec form and executing a shell directly, as in the case for -> the shell form, it is the shell that is doing the environment variable -> expansion, not docker. +Unlike the *shell* form, the *exec* form does not invoke a command shell. +This means that normal shell processing does not happen. For example, +`CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. +If you want shell processing then either use the *shell* form or execute +a shell directly, for example: `CMD [ "sh", "-c", "echo $HOME" ]`. +When using the exec form and executing a shell directly, as in the case for +the shell form, it is the shell that is doing the environment variable +expansion, not docker. When used in the shell or exec formats, the `CMD` instruction sets the command to be executed when running the image. @@ -752,16 +798,20 @@ to be executed when running the image. If you use the *shell* form of the `CMD`, then the `` will execute in `/bin/sh -c`: - FROM ubuntu - CMD echo "This is a test." | wc - +```dockerfile +FROM ubuntu +CMD echo "This is a test." | wc - +``` If you want to **run your** `` **without a shell** then you must express the command as a JSON array and give the full path to the executable. **This array form is the preferred format of `CMD`.** Any additional parameters must be individually expressed as strings in the array: - FROM ubuntu - CMD ["/usr/bin/wc","--help"] +```dockerfile +FROM ubuntu +CMD ["/usr/bin/wc","--help"] +``` If you would like your container to run the same executable every time, then you should consider using `ENTRYPOINT` in combination with `CMD`. See @@ -770,35 +820,40 @@ you should consider using `ENTRYPOINT` in combination with `CMD`. See If the user specifies arguments to `docker run` then they will override the default specified in `CMD`. -> **Note**: -> Don't confuse `RUN` with `CMD`. `RUN` actually runs a command and commits +> **Note** +> +> Do not confuse `RUN` with `CMD`. `RUN` actually runs a command and commits > the result; `CMD` does not execute anything at build time, but specifies > the intended command for the image. ## LABEL - LABEL = = = ... +```dockerfile +LABEL = = = ... +``` The `LABEL` instruction adds metadata to an image. A `LABEL` is a key-value pair. To include spaces within a `LABEL` value, use quotes and backslashes as you would in command-line parsing. A few usage examples: - LABEL "com.example.vendor"="ACME Incorporated" - LABEL com.example.label-with-value="foo" - LABEL version="1.0" - LABEL description="This text illustrates \ - that label-values can span multiple lines." +```dockerfile +LABEL "com.example.vendor"="ACME Incorporated" +LABEL com.example.label-with-value="foo" +LABEL version="1.0" +LABEL description="This text illustrates \ +that label-values can span multiple lines." +``` An image can have more than one label. You can specify multiple labels on a single line. Prior to Docker 1.10, this decreased the size of the final image, but this is no longer the case. You may still choose to specify multiple labels in a single instruction, in one of the following two ways: -```none +```dockerfile LABEL multi.label1="value1" multi.label2="value2" other="value3" ``` -```none +```dockerfile LABEL multi.label1="value1" \ multi.label2="value2" \ other="value3" @@ -808,21 +863,29 @@ Labels included in base or parent images (images in the `FROM` line) are inherited by your image. If a label already exists but with a different value, the most-recently-applied value overrides any previously-set value. -To view an image's labels, use the `docker inspect` command. - - "Labels": { - "com.example.vendor": "ACME Incorporated" - "com.example.label-with-value": "foo", - "version": "1.0", - "description": "This text illustrates that label-values can span multiple lines.", - "multi.label1": "value1", - "multi.label2": "value2", - "other": "value3" - }, +To view an image's labels, use the `docker image inspect` command. You can use +the `--format` option to show just the labels; + +```bash +docker image inspect --format='{{json .Config.Labels}}' myimage +``` +```json +{ + "com.example.vendor": "ACME Incorporated", + "com.example.label-with-value": "foo", + "version": "1.0", + "description": "This text illustrates that label-values can span multiple lines.", + "multi.label1": "value1", + "multi.label2": "value2", + "other": "value3" +} +``` ## MAINTAINER (deprecated) - MAINTAINER +```dockerfile +MAINTAINER +``` The `MAINTAINER` instruction sets the *Author* field of the generated images. The `LABEL` instruction is a much more flexible version of this and you should use @@ -830,13 +893,17 @@ it instead, as it enables setting any metadata you require, and can be viewed easily, for example with `docker inspect`. To set a label corresponding to the `MAINTAINER` field you could use: - LABEL maintainer="SvenDowideit@home.org.au" +```dockerfile +LABEL maintainer="SvenDowideit@home.org.au" +``` This will then be visible from `docker inspect` with the other labels. ## EXPOSE - EXPOSE [/...] +```dockerfile +EXPOSE [/...] +``` The `EXPOSE` instruction informs Docker that the container listens on the specified network ports at runtime. You can specify whether the port listens on @@ -883,8 +950,10 @@ see the ## ENV - ENV - ENV = ... +```dockerfile +ENV +ENV = ... +``` The `ENV` instruction sets the environment variable `` to the value ``. This value will be in the environment for all subsequent instructions @@ -904,14 +973,18 @@ quotes and backslashes can be used to include spaces within values. For example: - ENV myName="John Doe" myDog=Rex\ The\ Dog \ - myCat=fluffy +```dockerfile +ENV myName="John Doe" myDog=Rex\ The\ Dog \ + myCat=fluffy +``` and - ENV myName John Doe - ENV myDog Rex The Dog - ENV myCat fluffy +```dockerfile +ENV myName John Doe +ENV myDog Rex The Dog +ENV myCat fluffy +``` will yield the same net results in the final image. @@ -919,7 +992,8 @@ The environment variables set using `ENV` will persist when a container is run from the resulting image. You can view the values using `docker inspect`, and change them using `docker run --env =`. -> **Note**: +> **Note** +> > Environment persistence can cause unexpected side effects. For example, > setting `ENV DEBIAN_FRONTEND noninteractive` may confuse apt-get > users on a Debian-based image. To set a value for a single command, use @@ -929,11 +1003,15 @@ change them using `docker run --env =`. ADD has two forms: -- `ADD [--chown=:] ... ` -- `ADD [--chown=:] ["",... ""]` (this form is required for paths containing -whitespace) +```dockerfile +ADD [--chown=:] ... +ADD [--chown=:] ["",... ""] +``` -> **Note**: +The latter form is required for paths containing whitespace. + +> **Note** +> > The `--chown` feature is only supported on Dockerfiles used to build Linux containers, > and will not work on Windows containers. Since user and group ownership concepts do > not translate between Linux and Windows, the use of `/etc/passwd` and `/etc/group` for @@ -950,21 +1028,41 @@ the context of the build. Each `` may contain wildcards and matching will be done using Go's [filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: - ADD hom* /mydir/ # adds all files starting with "hom" - ADD hom?.txt /mydir/ # ? is replaced with any single character, e.g., "home.txt" +To add all files starting with "hom": + +```dockerfile +ADD hom* /mydir/ +``` + +In the example below, `?` is replaced with any single character, e.g., "home.txt". + +```dockerfile +ADD hom?.txt /mydir/ +``` The `` is an absolute path, or a path relative to `WORKDIR`, into which the source will be copied inside the destination container. - ADD test relativeDir/ # adds "test" to `WORKDIR`/relativeDir/ - ADD test /absoluteDir/ # adds "test" to /absoluteDir/ +The example below uses a relative path, and adds "test.txt" to `/relativeDir/`: + +```dockerfile +ADD test.txt relativeDir/ +``` + +Whereas this example uses an absolute path, and adds "test.txt" to `/absoluteDir/` + +```dockerfile +ADD test.txt /absoluteDir/ +``` When adding files or directories that contain special characters (such as `[` and `]`), you need to escape those paths following the Golang rules to prevent them from being treated as a matching pattern. For example, to add a file named `arr[0].txt`, use the following; - ADD arr[[]0].txt /mydir/ # copy a file named "arr[0].txt" to /mydir/ +```dockerfile +ADD arr[[]0].txt /mydir/ +``` All new files and directories are created with a UID and GID of 0, unless the @@ -978,10 +1076,12 @@ username or groupname is provided, the container's root filesystem from name to integer UID or GID respectively. The following examples show valid definitions for the `--chown` flag: - ADD --chown=55:mygroup files* /somedir/ - ADD --chown=bin files* /somedir/ - ADD --chown=1 files* /somedir/ - ADD --chown=10:11 files* /somedir/ +```dockerfile +ADD --chown=55:mygroup files* /somedir/ +ADD --chown=bin files* /somedir/ +ADD --chown=1 files* /somedir/ +ADD --chown=10:11 files* /somedir/ +``` If the container root filesystem does not contain either `/etc/passwd` or `/etc/group` files and either user or group names are used in the `--chown` @@ -995,7 +1095,8 @@ to set the `mtime` on the destination file. However, like any other file processed during an `ADD`, `mtime` will not be included in the determination of whether or not the file has changed and the cache should be updated. -> **Note**: +> **Note** +> > If you build by passing a `Dockerfile` through STDIN (`docker > build - < somefile`), there is no build context, so the `Dockerfile` > can only contain a URL based `ADD` instruction. You can also pass a @@ -1003,18 +1104,18 @@ of whether or not the file has changed and the cache should be updated. > the `Dockerfile` at the root of the archive and the rest of the > archive will be used as the context of the build. -> **Note**: -> If your URL files are protected using authentication, you -> will need to use `RUN wget`, `RUN curl` or use another tool from -> within the container as the `ADD` instruction does not support -> authentication. +If your URL files are protected using authentication, you need to use `RUN wget`, +`RUN curl` or use another tool from within the container as the `ADD` instruction +does not support authentication. -> **Note**: +> **Note** +> > The first encountered `ADD` instruction will invalidate the cache for all > following instructions from the Dockerfile if the contents of `` have > changed. This includes invalidating the cache for `RUN` instructions. > See the [`Dockerfile` Best Practices -guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/) for more information. +guide](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) +> for more information. `ADD` obeys the following rules: @@ -1037,7 +1138,8 @@ guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practi - If `` is a directory, the entire contents of the directory are copied, including filesystem metadata. -> **Note**: +> **Note** +> > The directory itself is not copied, just its contents. - If `` is a *local* tar archive in a recognized compression format @@ -1049,7 +1151,8 @@ guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practi 2. The contents of the source tree, with conflicts resolved in favor of "2." on a file-by-file basis. - > **Note**: + > **Note** + > > Whether a file is identified as a recognized compression format or not > is done solely based on the contents of the file, not the name of the file. > For example, if an empty file happens to end with `.tar.gz` this will not @@ -1076,11 +1179,15 @@ guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practi COPY has two forms: -- `COPY [--chown=:] ... ` -- `COPY [--chown=:] ["",... ""]` (this form is required for paths containing -whitespace) +```dockerfile +COPY [--chown=:] ... +COPY [--chown=:] ["",... ""] +``` -> **Note**: +This latter form is required for paths containing whitespace + +> **Note** +> > The `--chown` feature is only supported on Dockerfiles used to build Linux containers, > and will not work on Windows containers. Since user and group ownership concepts do > not translate between Linux and Windows, the use of `/etc/passwd` and `/etc/group` for @@ -1097,22 +1204,41 @@ of the build. Each `` may contain wildcards and matching will be done using Go's [filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: - COPY hom* /mydir/ # adds all files starting with "hom" - COPY hom?.txt /mydir/ # ? is replaced with any single character, e.g., "home.txt" +To add all files starting with "hom": + +```dockerfile +COPY hom* /mydir/ +``` + +In the example below, `?` is replaced with any single character, e.g., "home.txt". + +```dockerfile +COPY hom?.txt /mydir/ +``` The `` is an absolute path, or a path relative to `WORKDIR`, into which the source will be copied inside the destination container. - COPY test relativeDir/ # adds "test" to `WORKDIR`/relativeDir/ - COPY test /absoluteDir/ # adds "test" to /absoluteDir/ +The example below uses a relative path, and adds "test.txt" to `/relativeDir/`: +```dockerfile +COPY test.txt relativeDir/ +``` + +Whereas this example uses an absolute path, and adds "test.txt" to `/absoluteDir/` + +```dockerfile +COPY test.txt /absoluteDir/ +``` When copying files or directories that contain special characters (such as `[` and `]`), you need to escape those paths following the Golang rules to prevent -them from being treated as a matching pattern. For example, to copy a file +them from being treated as a matching pattern. For example, to add a file named `arr[0].txt`, use the following; - COPY arr[[]0].txt /mydir/ # copy a file named "arr[0].txt" to /mydir/ +```dockerfile +ADD arr[[]0].txt /mydir/ +``` All new files and directories are created with a UID and GID of 0, unless the optional `--chown` flag specifies a given username, groupname, or UID/GID @@ -1125,17 +1251,20 @@ username or groupname is provided, the container's root filesystem from name to integer UID or GID respectively. The following examples show valid definitions for the `--chown` flag: - COPY --chown=55:mygroup files* /somedir/ - COPY --chown=bin files* /somedir/ - COPY --chown=1 files* /somedir/ - COPY --chown=10:11 files* /somedir/ +```dockerfile +COPY --chown=55:mygroup files* /somedir/ +COPY --chown=bin files* /somedir/ +COPY --chown=1 files* /somedir/ +COPY --chown=10:11 files* /somedir/ +``` If the container root filesystem does not contain either `/etc/passwd` or `/etc/group` files and either user or group names are used in the `--chown` flag, the build will fail on the `COPY` operation. Using numeric IDs requires -no lookup and will not depend on container root filesystem content. +no lookup and does not depend on container root filesystem content. -> **Note**: +> **Note** +> > If you build using STDIN (`docker build - < somefile`), there is no > build context, so `COPY` can't be used. @@ -1156,7 +1285,8 @@ image with the same name is attempted to be used instead. - If `` is a directory, the entire contents of the directory are copied, including filesystem metadata. -> **Note**: +> **Note** +> > The directory itself is not copied, just its contents. - If `` is any other kind of file, it is copied individually along with @@ -1178,17 +1308,26 @@ image with the same name is attempted to be used instead. ENTRYPOINT has two forms: -- `ENTRYPOINT ["executable", "param1", "param2"]` - (*exec* form, preferred) -- `ENTRYPOINT command param1 param2` - (*shell* form) +The *exec* form, which is the preferred form: + +```dockerfile +ENTRYPOINT ["executable", "param1", "param2"] +``` + +The *shell* form: + +```dockerfile +ENTRYPOINT command param1 param2 +``` An `ENTRYPOINT` allows you to configure a container that will run as an executable. -For example, the following will start nginx with its default content, listening +For example, the following starts nginx with its default content, listening on port 80: - docker run -i -t --rm -p 80:80 nginx +```bash +$ docker run -i -t --rm -p 80:80 nginx +``` Command line arguments to `docker run ` will be appended after all elements in an *exec* form `ENTRYPOINT`, and will override all elements specified @@ -1213,35 +1352,43 @@ You can use the *exec* form of `ENTRYPOINT` to set fairly stable default command and arguments and then use either form of `CMD` to set additional defaults that are more likely to be changed. - FROM ubuntu - ENTRYPOINT ["top", "-b"] - CMD ["-c"] +```dockerfile +FROM ubuntu +ENTRYPOINT ["top", "-b"] +CMD ["-c"] +``` When you run the container, you can see that `top` is the only process: - $ docker run -it --rm --name test top -H - top - 08:25:00 up 7:27, 0 users, load average: 0.00, 0.01, 0.05 - Threads: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie - %Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.7 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st - KiB Mem: 2056668 total, 1616832 used, 439836 free, 99352 buffers - KiB Swap: 1441840 total, 0 used, 1441840 free. 1324440 cached Mem +```bash +$ docker run -it --rm --name test top -H - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 1 root 20 0 19744 2336 2080 R 0.0 0.1 0:00.04 top +top - 08:25:00 up 7:27, 0 users, load average: 0.00, 0.01, 0.05 +Threads: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie +%Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.7 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st +KiB Mem: 2056668 total, 1616832 used, 439836 free, 99352 buffers +KiB Swap: 1441840 total, 0 used, 1441840 free. 1324440 cached Mem + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 19744 2336 2080 R 0.0 0.1 0:00.04 top +``` To examine the result further, you can use `docker exec`: - $ docker exec -it test ps aux - USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND - root 1 2.6 0.1 19752 2352 ? Ss+ 08:24 0:00 top -b -H - root 7 0.0 0.1 15572 2164 ? R+ 08:25 0:00 ps aux +```bash +$ docker exec -it test ps aux + +USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND +root 1 2.6 0.1 19752 2352 ? Ss+ 08:24 0:00 top -b -H +root 7 0.0 0.1 15572 2164 ? R+ 08:25 0:00 ps aux +``` And you can gracefully request `top` to shut down using `docker stop test`. The following `Dockerfile` shows using the `ENTRYPOINT` to run Apache in the foreground (i.e., as `PID 1`): -``` +```dockerfile FROM debian:stable RUN apt-get update && apt-get install -y --force-yes apache2 EXPOSE 80 443 @@ -1275,7 +1422,7 @@ on shutdown, or are co-ordinating more than one executable, you may need to ensu that the `ENTRYPOINT` script receives the Unix signals, passes them on, and then does some more work: -``` +```bash #!/bin/sh # Note: I've written this using sh so it works in the busybox container too @@ -1302,41 +1449,48 @@ and then ask the script to stop Apache: ```bash $ docker exec -it test ps aux + USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND root 1 0.1 0.0 4448 692 ? Ss+ 00:42 0:00 /bin/sh /run.sh 123 cmd cmd2 root 19 0.0 0.2 71304 4440 ? Ss 00:42 0:00 /usr/sbin/apache2 -k start www-data 20 0.2 0.2 360468 6004 ? Sl 00:42 0:00 /usr/sbin/apache2 -k start www-data 21 0.2 0.2 360468 6000 ? Sl 00:42 0:00 /usr/sbin/apache2 -k start root 81 0.0 0.1 15572 2140 ? R+ 00:44 0:00 ps aux + $ docker top test + PID USER COMMAND 10035 root {run.sh} /bin/sh /run.sh 123 cmd cmd2 10054 root /usr/sbin/apache2 -k start 10055 33 /usr/sbin/apache2 -k start 10056 33 /usr/sbin/apache2 -k start + $ /usr/bin/time docker stop test + test real 0m 0.27s user 0m 0.03s sys 0m 0.03s ``` -> **Note:** you can override the `ENTRYPOINT` setting using `--entrypoint`, +> **Note** +> +> You can override the `ENTRYPOINT` setting using `--entrypoint`, > but this can only set the binary to *exec* (no `sh -c` will be used). -> **Note**: +> **Note** +> > The *exec* form is parsed as a JSON array, which means that > you must use double-quotes (") around words not single-quotes ('). -> **Note**: -> Unlike the *shell* form, the *exec* form does not invoke a command shell. -> This means that normal shell processing does not happen. For example, -> `ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. -> If you want shell processing then either use the *shell* form or execute -> a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo $HOME" ]`. -> When using the exec form and executing a shell directly, as in the case for -> the shell form, it is the shell that is doing the environment variable -> expansion, not docker. +Unlike the *shell* form, the *exec* form does not invoke a command shell. +This means that normal shell processing does not happen. For example, +`ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. +If you want shell processing then either use the *shell* form or execute +a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo $HOME" ]`. +When using the exec form and executing a shell directly, as in the case for +the shell form, it is the shell that is doing the environment variable +expansion, not docker. ### Shell form ENTRYPOINT example @@ -1346,57 +1500,75 @@ and will ignore any `CMD` or `docker run` command line arguments. To ensure that `docker stop` will signal any long running `ENTRYPOINT` executable correctly, you need to remember to start it with `exec`: - FROM ubuntu - ENTRYPOINT exec top -b +```dockerfile +FROM ubuntu +ENTRYPOINT exec top -b +``` When you run this image, you'll see the single `PID 1` process: - $ docker run -it --rm --name test top - Mem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cached - CPU: 5% usr 0% sys 0% nic 94% idle 0% io 0% irq 0% sirq - Load average: 0.08 0.03 0.05 2/98 6 - PID PPID USER STAT VSZ %VSZ %CPU COMMAND - 1 0 root R 3164 0% 0% top -b +```bash +$ docker run -it --rm --name test top -Which will exit cleanly on `docker stop`: +Mem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cached +CPU: 5% usr 0% sys 0% nic 94% idle 0% io 0% irq 0% sirq +Load average: 0.08 0.03 0.05 2/98 6 + PID PPID USER STAT VSZ %VSZ %CPU COMMAND + 1 0 root R 3164 0% 0% top -b +``` - $ /usr/bin/time docker stop test - test - real 0m 0.20s - user 0m 0.02s - sys 0m 0.04s +Which exits cleanly on `docker stop`: + +```bash +$ /usr/bin/time docker stop test + +test +real 0m 0.20s +user 0m 0.02s +sys 0m 0.04s +``` If you forget to add `exec` to the beginning of your `ENTRYPOINT`: - FROM ubuntu - ENTRYPOINT top -b - CMD --ignored-param1 +```dockerfile +FROM ubuntu +ENTRYPOINT top -b +CMD --ignored-param1 +``` You can then run it (giving it a name for the next step): - $ docker run -it --name test top --ignored-param2 - Mem: 1704184K used, 352484K free, 0K shrd, 0K buff, 140621524238337K cached - CPU: 9% usr 2% sys 0% nic 88% idle 0% io 0% irq 0% sirq - Load average: 0.01 0.02 0.05 2/101 7 - PID PPID USER STAT VSZ %VSZ %CPU COMMAND - 1 0 root S 3168 0% 0% /bin/sh -c top -b cmd cmd2 - 7 1 root R 3164 0% 0% top -b +```bash +$ docker run -it --name test top --ignored-param2 + +Mem: 1704184K used, 352484K free, 0K shrd, 0K buff, 140621524238337K cached +CPU: 9% usr 2% sys 0% nic 88% idle 0% io 0% irq 0% sirq +Load average: 0.01 0.02 0.05 2/101 7 + PID PPID USER STAT VSZ %VSZ %CPU COMMAND + 1 0 root S 3168 0% 0% /bin/sh -c top -b cmd cmd2 + 7 1 root R 3164 0% 0% top -b +``` You can see from the output of `top` that the specified `ENTRYPOINT` is not `PID 1`. If you then run `docker stop test`, the container will not exit cleanly - the `stop` command will be forced to send a `SIGKILL` after the timeout: - $ docker exec -it test ps aux - PID USER COMMAND - 1 root /bin/sh -c top -b cmd cmd2 - 7 root top -b - 8 root ps aux - $ /usr/bin/time docker stop test - test - real 0m 10.19s - user 0m 0.04s - sys 0m 0.03s +```bash +$ docker exec -it test ps aux + +PID USER COMMAND + 1 root /bin/sh -c top -b cmd cmd2 + 7 root top -b + 8 root ps aux + +$ /usr/bin/time docker stop test + +test +real 0m 10.19s +user 0m 0.04s +sys 0m 0.03s +``` ### Understand how CMD and ENTRYPOINT interact @@ -1421,13 +1593,17 @@ The table below shows what command is executed for different `ENTRYPOINT` / `CMD | **CMD ["p1_cmd", "p2_cmd"]** | p1_cmd p2_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry p1_cmd p2_cmd | | **CMD exec_cmd p1_cmd** | /bin/sh -c exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry /bin/sh -c exec_cmd p1_cmd | -> **Note**: If `CMD` is defined from the base image, setting `ENTRYPOINT` will +> **Note** +> +> If `CMD` is defined from the base image, setting `ENTRYPOINT` will > reset `CMD` to an empty value. In this scenario, `CMD` must be defined in the > current image to have a value. ## VOLUME - VOLUME ["/data"] +```dockerfile +VOLUME ["/data"] +``` The `VOLUME` instruction creates a mount point with the specified name and marks it as holding externally mounted volumes from native host or other @@ -1435,17 +1611,19 @@ containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log /var/db`. For more information/examples and mounting instructions via the Docker client, refer to -[*Share Directories via Volumes*](https://docs.docker.com/engine/tutorials/dockervolumes/) +[*Share Directories via Volumes*](https://docs.docker.com/storage/volumes/) documentation. The `docker run` command initializes the newly created volume with any data that exists at the specified location within the base image. For example, consider the following Dockerfile snippet: - FROM ubuntu - RUN mkdir /myvol - RUN echo "hello world" > /myvol/greeting - VOLUME /myvol +```dockerfile +FROM ubuntu +RUN mkdir /myvol +RUN echo "hello world" > /myvol/greeting +VOLUME /myvol +``` This Dockerfile results in an image that causes `docker run` to create a new mount point at `/myvol` and copy the `greeting` file @@ -1476,9 +1654,15 @@ Keep the following things in mind about volumes in the `Dockerfile`. ## USER - USER [:] +```dockerfile +USER [:] +``` + or - USER [:] + +```dockerfile +USER [:] +``` The `USER` instruction sets the user name (or UID) and optionally the user group (or GID) to use when running the image and for any `RUN`, `CMD` and @@ -1487,25 +1671,28 @@ group (or GID) to use when running the image and for any `RUN`, `CMD` and > Note that when specifying a group for the user, the user will have _only_ the > specified group membership. Any other configured group memberships will be ignored. -> **Warning**: +> **Warning** +> > When the user doesn't have a primary group then the image (or the next > instructions) will be run with the `root` group. - +> > On Windows, the user must be created first if it's not a built-in account. > This can be done with the `net user` command called as part of a Dockerfile. ```dockerfile - FROM microsoft/windowsservercore - # Create Windows user in the container - RUN net user /add patrick - # Set it for subsequent commands - USER patrick +FROM microsoft/windowsservercore +# Create Windows user in the container +RUN net user /add patrick +# Set it for subsequent commands +USER patrick ``` ## WORKDIR - WORKDIR /path/to/workdir +```dockerfile +WORKDIR /path/to/workdir +``` The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY` and `ADD` instructions that follow it in the `Dockerfile`. @@ -1516,61 +1703,71 @@ The `WORKDIR` instruction can be used multiple times in a `Dockerfile`. If a relative path is provided, it will be relative to the path of the previous `WORKDIR` instruction. For example: - WORKDIR /a - WORKDIR b - WORKDIR c - RUN pwd +```dockerfile +WORKDIR /a +WORKDIR b +WORKDIR c +RUN pwd +``` -The output of the final `pwd` command in this `Dockerfile` would be -`/a/b/c`. +The output of the final `pwd` command in this `Dockerfile` would be `/a/b/c`. The `WORKDIR` instruction can resolve environment variables previously set using `ENV`. You can only use environment variables explicitly set in the `Dockerfile`. For example: - ENV DIRPATH /path - WORKDIR $DIRPATH/$DIRNAME - RUN pwd +```dockerfile +ENV DIRPATH /path +WORKDIR $DIRPATH/$DIRNAME +RUN pwd +``` The output of the final `pwd` command in this `Dockerfile` would be `/path/$DIRNAME` ## ARG - ARG [=] +```dockerfile +ARG [=] +``` The `ARG` instruction defines a variable that users can pass at build-time to the builder with the `docker build` command using the `--build-arg =` flag. If a user specifies a build argument that was not defined in the Dockerfile, the build outputs a warning. -``` +```console [Warning] One or more build-args [foo] were not consumed. ``` A Dockerfile may include one or more `ARG` instructions. For example, the following is a valid Dockerfile: -``` +```dockerfile FROM busybox ARG user1 ARG buildno -... +# ... ``` -> **Warning:** It is not recommended to use build-time variables for -> passing secrets like github keys, user credentials etc. Build-time variable -> values are visible to any user of the image with the `docker history` command. +> **Warning:** +> +> It is not recommended to use build-time variables for passing secrets like +> github keys, user credentials etc. Build-time variable values are visible to +> any user of the image with the `docker history` command. +> +> Refer to the ["build images with BuildKit"](https://docs.docker.com/develop/develop-images/build_enhancements/#new-docker-build-secret-information) +> section to learn about secure ways to use secrets when building images. ### Default values An `ARG` instruction can optionally include a default value: -``` +```dockerfile FROM busybox ARG user1=someuser ARG buildno=1 -... +# ... ``` If an `ARG` instruction has a default value and if there is no value passed @@ -1582,16 +1779,16 @@ An `ARG` variable definition comes into effect from the line on which it is defined in the `Dockerfile` not from the argument's use on the command-line or elsewhere. For example, consider this Dockerfile: -``` -1 FROM busybox -2 USER ${user:-some_user} -3 ARG user -4 USER $user -... +```dockerfile +FROM busybox +USER ${user:-some_user} +ARG user +USER $user +# ... ``` A user builds this file by calling: -``` +```bash $ docker build --build-arg user=what_user . ``` @@ -1604,7 +1801,7 @@ An `ARG` instruction goes out of scope at the end of the build stage where it was defined. To use an arg in multiple stages, each stage must include the `ARG` instruction. -``` +```dockerfile FROM busybox ARG SETTINGS RUN ./run/setup $SETTINGS @@ -1621,15 +1818,16 @@ available to the `RUN` instruction. Environment variables defined using the `ENV` instruction always override an `ARG` instruction of the same name. Consider this Dockerfile with an `ENV` and `ARG` instruction. +```dockerfile +FROM ubuntu +ARG CONT_IMG_VER +ENV CONT_IMG_VER v1.0.0 +RUN echo $CONT_IMG_VER ``` -1 FROM ubuntu -2 ARG CONT_IMG_VER -3 ENV CONT_IMG_VER v1.0.0 -4 RUN echo $CONT_IMG_VER -``` + Then, assume this image is built with this command: -``` +```bash $ docker build --build-arg CONT_IMG_VER=v2.0.1 . ``` @@ -1641,17 +1839,17 @@ arguments or inherited from environment, from its point of definition. Using the example above but a different `ENV` specification you can create more useful interactions between `ARG` and `ENV` instructions: -``` -1 FROM ubuntu -2 ARG CONT_IMG_VER -3 ENV CONT_IMG_VER ${CONT_IMG_VER:-v1.0.0} -4 RUN echo $CONT_IMG_VER +```dockerfile +FROM ubuntu +ARG CONT_IMG_VER +ENV CONT_IMG_VER ${CONT_IMG_VER:-v1.0.0} +RUN echo $CONT_IMG_VER ``` Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. Consider a docker build without the `--build-arg` flag: -``` +```bash $ docker build . ``` @@ -1668,18 +1866,18 @@ Dockerfile instructions.](#environment-replacement) Docker has a set of predefined `ARG` variables that you can use without a corresponding `ARG` instruction in the Dockerfile. -* `HTTP_PROXY` -* `http_proxy` -* `HTTPS_PROXY` -* `https_proxy` -* `FTP_PROXY` -* `ftp_proxy` -* `NO_PROXY` -* `no_proxy` +- `HTTP_PROXY` +- `http_proxy` +- `HTTPS_PROXY` +- `https_proxy` +- `FTP_PROXY` +- `ftp_proxy` +- `NO_PROXY` +- `no_proxy` To use these, simply pass them on the command line using the flag: -``` +```bash --build-arg = ``` @@ -1690,7 +1888,7 @@ sensitive authentication information in an `HTTP_PROXY` variable. For example, consider building the following Dockerfile using `--build-arg HTTP_PROXY=http://user:pass@proxy.lon.example.com` -``` Dockerfile +```dockerfile FROM ubuntu RUN echo "Hello World" ``` @@ -1703,7 +1901,7 @@ build does not result in a cache miss. If you need to override this behaviour then you may do so by adding an `ARG` statement in the Dockerfile as follows: -``` Dockerfile +```dockerfile FROM ubuntu ARG HTTP_PROXY RUN echo "Hello World" @@ -1723,14 +1921,14 @@ the `--platform` flag on `docker build`. The following `ARG` variables are set automatically: -* `TARGETPLATFORM` - platform of the build result. Eg `linux/amd64`, `linux/arm/v7`, `windows/amd64`. -* `TARGETOS` - OS component of TARGETPLATFORM -* `TARGETARCH` - architecture component of TARGETPLATFORM -* `TARGETVARIANT` - variant component of TARGETPLATFORM -* `BUILDPLATFORM` - platform of the node performing the build. -* `BUILDOS` - OS component of BUILDPLATFORM -* `BUILDARCH` - architecture component of BUILDPLATFORM -* `BUILDVARIANT` - variant component of BUILDPLATFORM +- `TARGETPLATFORM` - platform of the build result. Eg `linux/amd64`, `linux/arm/v7`, `windows/amd64`. +- `TARGETOS` - OS component of TARGETPLATFORM +- `TARGETARCH` - architecture component of TARGETPLATFORM +- `TARGETVARIANT` - variant component of TARGETPLATFORM +- `BUILDPLATFORM` - platform of the node performing the build. +- `BUILDOS` - OS component of BUILDPLATFORM +- `BUILDARCH` - architecture component of BUILDPLATFORM +- `BUILDVARIANT` - variant component of BUILDPLATFORM These arguments are defined in the global scope so are not automatically available inside build stages or for your `RUN` commands. To expose one of @@ -1757,16 +1955,16 @@ matching `ARG` statement in the `Dockerfile`. For example, consider these two Dockerfile: -``` -1 FROM ubuntu -2 ARG CONT_IMG_VER -3 RUN echo $CONT_IMG_VER +```dockerfile +FROM ubuntu +ARG CONT_IMG_VER +RUN echo $CONT_IMG_VER ``` -``` -1 FROM ubuntu -2 ARG CONT_IMG_VER -3 RUN echo hello +```dockerfile +FROM ubuntu +ARG CONT_IMG_VER +RUN echo hello ``` If you specify `--build-arg CONT_IMG_VER=` on the command line, in both @@ -1777,12 +1975,13 @@ changes, we get a cache miss. Consider another example under the same command line: +```dockerfile +FROM ubuntu +ARG CONT_IMG_VER +ENV CONT_IMG_VER $CONT_IMG_VER +RUN echo $CONT_IMG_VER ``` -1 FROM ubuntu -2 ARG CONT_IMG_VER -3 ENV CONT_IMG_VER $CONT_IMG_VER -4 RUN echo $CONT_IMG_VER -``` + In this example, the cache miss occurs on line 3. The miss happens because the variable's value in the `ENV` references the `ARG` variable and that variable is changed through the command line. In this example, the `ENV` @@ -1791,11 +1990,11 @@ command causes the image to include the value. If an `ENV` instruction overrides an `ARG` instruction of the same name, like this Dockerfile: -``` -1 FROM ubuntu -2 ARG CONT_IMG_VER -3 ENV CONT_IMG_VER hello -4 RUN echo $CONT_IMG_VER +```dockerfile +FROM ubuntu +ARG CONT_IMG_VER +ENV CONT_IMG_VER hello +RUN echo $CONT_IMG_VER ``` Line 3 does not cause a cache miss because the value of `CONT_IMG_VER` is a @@ -1804,7 +2003,9 @@ the `RUN` (line 4) doesn't change between builds. ## ONBUILD - ONBUILD [INSTRUCTION] +```dockerfile +ONBUILD +``` The `ONBUILD` instruction adds to the image a *trigger* instruction to be executed at a later time, when the image is used as the base for @@ -1851,18 +2052,24 @@ Here's how it works: For example you might add something like this: - [...] - ONBUILD ADD . /app/src - ONBUILD RUN /usr/local/bin/python-build --dir /app/src - [...] +```dockerfile +ONBUILD ADD . /app/src +ONBUILD RUN /usr/local/bin/python-build --dir /app/src +``` -> **Warning**: Chaining `ONBUILD` instructions using `ONBUILD ONBUILD` isn't allowed. +> **Warning** +> +> Chaining `ONBUILD` instructions using `ONBUILD ONBUILD` isn't allowed. -> **Warning**: The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions. +> **Warning** +> +> The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions. ## STOPSIGNAL - STOPSIGNAL signal +```dockerfile +STOPSIGNAL signal +``` The `STOPSIGNAL` instruction sets the system call signal that will be sent to the container to exit. This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, @@ -1872,8 +2079,8 @@ or a signal name in the format SIGNAME, for instance SIGKILL. The `HEALTHCHECK` instruction has two forms: -* `HEALTHCHECK [OPTIONS] CMD command` (check container health by running a command inside the container) -* `HEALTHCHECK NONE` (disable any healthcheck inherited from the base image) +- `HEALTHCHECK [OPTIONS] CMD command` (check container health by running a command inside the container) +- `HEALTHCHECK NONE` (disable any healthcheck inherited from the base image) The `HEALTHCHECK` instruction tells Docker how to test a container to check that it is still working. This can detect cases such as a web server that is stuck in @@ -1887,10 +2094,10 @@ After a certain number of consecutive failures, it becomes `unhealthy`. The options that can appear before `CMD` are: -* `--interval=DURATION` (default: `30s`) -* `--timeout=DURATION` (default: `30s`) -* `--start-period=DURATION` (default: `0s`) -* `--retries=N` (default: `3`) +- `--interval=DURATION` (default: `30s`) +- `--timeout=DURATION` (default: `30s`) +- `--start-period=DURATION` (default: `0s`) +- `--retries=N` (default: `3`) The health check will first run **interval** seconds after the container is started, and then again **interval** seconds after each previous check completes. @@ -1923,8 +2130,10 @@ The possible values are: For example, to check every five minutes or so that a web-server is able to serve the site's main page within three seconds: - HEALTHCHECK --interval=5m --timeout=3s \ - CMD curl -f http://localhost/ || exit 1 +```dockerfile +HEALTHCHECK --interval=5m --timeout=3s \ + CMD curl -f http://localhost/ || exit 1 +``` To help debug failing probes, any output text (UTF-8 encoded) that the command writes on stdout or stderr will be stored in the health status and can be queried with @@ -1939,7 +2148,9 @@ The `HEALTHCHECK` feature was added in Docker 1.12. ## SHELL - SHELL ["executable", "parameters"] +```dockerfile +SHELL ["executable", "parameters"] +``` The `SHELL` instruction allows the default shell used for the *shell* form of commands to be overridden. The default shell on Linux is `["/bin/sh", "-c"]`, and on @@ -1953,21 +2164,23 @@ well as alternate shells available including `sh`. The `SHELL` instruction can appear multiple times. Each `SHELL` instruction overrides all previous `SHELL` instructions, and affects all subsequent instructions. For example: - FROM microsoft/windowsservercore +```dockerfile +FROM microsoft/windowsservercore - # Executed as cmd /S /C echo default - RUN echo default +# Executed as cmd /S /C echo default +RUN echo default - # Executed as cmd /S /C powershell -command Write-Host default - RUN powershell -command Write-Host default +# Executed as cmd /S /C powershell -command Write-Host default +RUN powershell -command Write-Host default - # Executed as powershell -command Write-Host hello - SHELL ["powershell", "-command"] - RUN Write-Host hello +# Executed as powershell -command Write-Host hello +SHELL ["powershell", "-command"] +RUN Write-Host hello - # Executed as cmd /S /C echo hello - SHELL ["cmd", "/S", "/C"] - RUN echo hello +# Executed as cmd /S /C echo hello +SHELL ["cmd", "/S", "/C"] +RUN echo hello +``` The following instructions can be affected by the `SHELL` instruction when the *shell* form of them is used in a Dockerfile: `RUN`, `CMD` and `ENTRYPOINT`. @@ -1975,13 +2188,15 @@ The following instructions can be affected by the `SHELL` instruction when the The following example is a common pattern found on Windows which can be streamlined by using the `SHELL` instruction: - ... - RUN powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" - ... +```dockerfile +RUN powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" +``` The command invoked by docker will be: - cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" +```powershell +cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" +``` This is inefficient for two reasons. First, there is an un-necessary cmd.exe command processor (aka shell) being invoked. Second, each `RUN` instruction in the *shell* @@ -1990,9 +2205,9 @@ form requires an extra `powershell -command` prefixing the command. To make this more efficient, one of two mechanisms can be employed. One is to use the JSON form of the RUN command such as: - ... - RUN ["powershell", "-command", "Execute-MyCmdlet", "-param1 \"c:\\foo.txt\""] - ... +```dockerfile +RUN ["powershell", "-command", "Execute-MyCmdlet", "-param1 \"c:\\foo.txt\""] +``` While the JSON form is unambiguous and does not use the un-necessary cmd.exe, it does require more verbosity through double-quoting and escaping. The alternate @@ -2000,48 +2215,52 @@ mechanism is to use the `SHELL` instruction and the *shell* form, making a more natural syntax for Windows users, especially when combined with the `escape` parser directive: - # escape=` +```dockerfile +# escape=` - FROM microsoft/nanoserver - SHELL ["powershell","-command"] - RUN New-Item -ItemType Directory C:\Example - ADD Execute-MyCmdlet.ps1 c:\example\ - RUN c:\example\Execute-MyCmdlet -sample 'hello world' +FROM microsoft/nanoserver +SHELL ["powershell","-command"] +RUN New-Item -ItemType Directory C:\Example +ADD Execute-MyCmdlet.ps1 c:\example\ +RUN c:\example\Execute-MyCmdlet -sample 'hello world' +``` Resulting in: - PS E:\docker\build\shell> docker build -t shell . - Sending build context to Docker daemon 4.096 kB - Step 1/5 : FROM microsoft/nanoserver - ---> 22738ff49c6d - Step 2/5 : SHELL powershell -command - ---> Running in 6fcdb6855ae2 - ---> 6331462d4300 - Removing intermediate container 6fcdb6855ae2 - Step 3/5 : RUN New-Item -ItemType Directory C:\Example - ---> Running in d0eef8386e97 +```powershell +PS E:\docker\build\shell> docker build -t shell . +Sending build context to Docker daemon 4.096 kB +Step 1/5 : FROM microsoft/nanoserver + ---> 22738ff49c6d +Step 2/5 : SHELL powershell -command + ---> Running in 6fcdb6855ae2 + ---> 6331462d4300 +Removing intermediate container 6fcdb6855ae2 +Step 3/5 : RUN New-Item -ItemType Directory C:\Example + ---> Running in d0eef8386e97 - Directory: C:\ + Directory: C:\ - Mode LastWriteTime Length Name - ---- ------------- ------ ---- - d----- 10/28/2016 11:26 AM Example +Mode LastWriteTime Length Name +---- ------------- ------ ---- +d----- 10/28/2016 11:26 AM Example - ---> 3f2fbf1395d9 - Removing intermediate container d0eef8386e97 - Step 4/5 : ADD Execute-MyCmdlet.ps1 c:\example\ - ---> a955b2621c31 - Removing intermediate container b825593d39fc - Step 5/5 : RUN c:\example\Execute-MyCmdlet 'hello world' - ---> Running in be6d8e63fe75 - hello world - ---> 8e559e9bf424 - Removing intermediate container be6d8e63fe75 - Successfully built 8e559e9bf424 - PS E:\docker\build\shell> + ---> 3f2fbf1395d9 +Removing intermediate container d0eef8386e97 +Step 4/5 : ADD Execute-MyCmdlet.ps1 c:\example\ + ---> a955b2621c31 +Removing intermediate container b825593d39fc +Step 5/5 : RUN c:\example\Execute-MyCmdlet 'hello world' + ---> Running in be6d8e63fe75 +hello world + ---> 8e559e9bf424 +Removing intermediate container be6d8e63fe75 +Successfully built 8e559e9bf424 +PS E:\docker\build\shell> +``` The `SHELL` instruction could also be used to modify the way in which a shell operates. For example, using `SHELL cmd /S /C /V:ON|OFF` on Windows, delayed @@ -2064,7 +2283,7 @@ builder with a syntax directive. To learn about these features, [refer to the do Below you can see some examples of Dockerfile syntax. -``` +```dockerfile # Nginx # # VERSION 0.0.1 @@ -2074,7 +2293,7 @@ LABEL Description="This image is used to start the foobar executable" Vendor="AC RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server ``` -``` +```dockerfile # Firefox over VNC # # VERSION 0.3 @@ -2093,7 +2312,7 @@ EXPOSE 5900 CMD ["x11vnc", "-forever", "-usepw", "-create"] ``` -``` +```dockerfile # Multiple images example # # VERSION 0.1 From 1444b57fcaee78a86abe400ce6edabaa852d85bd Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 30 Apr 2020 00:17:28 +0200 Subject: [PATCH 125/152] docs: fix links, and minor markdown touch-ups Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 80ecdf80c..b998ea3a7 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -54,6 +54,7 @@ Dockerfile. > > Do not use your root directory, `/`, as the `PATH` as it causes the build to > transfer the entire contents of your hard drive to the Docker daemon. +{:.warning} To use a file in the build context, the `Dockerfile` refers to the file specified in an instruction, for example, a `COPY` instruction. To increase the build's @@ -175,9 +176,9 @@ Docker runs instructions in a `Dockerfile` in order. A `Dockerfile` **must begin with a \`FROM\` instruction**. This may be after [parser directives](#parser-directives), [comments](#format), and globally scoped [ARGs](#arg). The `FROM` instruction specifies the [*Parent -Image*](glossary.md#parent-image) from which you are building. `FROM` -may only be preceded by one or more `ARG` instructions, which declare arguments -that are used in `FROM` lines in the `Dockerfile`. +Image*](https://docs.docker.com/glossary/#parent_image) from which you are +building. `FROM` may only be preceded by one or more `ARG` instructions, which +declare arguments that are used in `FROM` lines in the `Dockerfile`. Docker treats lines that *begin* with `#` as a comment, unless the line is a valid [parser directive](#parser-directives). A `#` marker anywhere @@ -1758,6 +1759,7 @@ ARG buildno > > Refer to the ["build images with BuildKit"](https://docs.docker.com/develop/develop-images/build_enhancements/#new-docker-build-secret-information) > section to learn about secure ways to use secrets when building images. +{:.warning} ### Default values @@ -2277,7 +2279,8 @@ This feature is only available when using the [BuildKit](#buildkit) backend. Docker build supports experimental features like cache mounts, build secrets and ssh forwarding that are enabled by using an external implementation of the -builder with a syntax directive. To learn about these features, [refer to the documentation in BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md). +builder with a syntax directive. To learn about these features, +[refer to the documentation in BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md). ## Dockerfile examples From 78cf519ab6832e1dc8f3fa85b8fa3959113b5dd7 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 30 Apr 2020 21:46:11 +0200 Subject: [PATCH 126/152] builder: fix broken link This link was broken when generating the documentation (due to a bug in Jekyll not converting wrapped internal links) Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index b998ea3a7..c7364748c 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -941,13 +941,12 @@ the `-p` flag. For example docker run -p 80:80/tcp -p 80:80/udp ... ``` -To set up port redirection on the host system, see [using the -P -flag](run.md#expose-incoming-ports). The `docker network` command supports -creating networks for communication among containers without the need to -expose or publish specific ports, because the containers connected to the -network can communicate with each other over any port. For detailed information, -see the -[overview of this feature](https://docs.docker.com/engine/userguide/networking/)). +To set up port redirection on the host system, see [using the -P flag](run.md#expose-incoming-ports). +The `docker network` command supports creating networks for communication among +containers without the need to expose or publish specific ports, because the +containers connected to the network can communicate with each other over any +port. For detailed information, see the +[overview of this feature](https://docs.docker.com/engine/userguide/networking/). ## ENV From c02b383eed9d99a2fed1964336f88baf66c8b59c Mon Sep 17 00:00:00 2001 From: Maciej Kalisz Date: Mon, 11 Nov 2019 20:56:31 +0100 Subject: [PATCH 127/152] Update dead link and add missing info on COPY 1. Fix dead URL to [Dockerfile best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#leverage-build-cache). 2. Add missing information about cache invalidation by `COPY`. It works in the same way as in the case of `ADD`. Informing only about the `ADD`s behavior is misleading as one can infer that these two directives differ in this regard. 3. Add missing info on RUN cache invalidation by COPY Signed-off-by: Maciej Kalisz --- frontend/dockerfile/docs/reference.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index c7364748c..7ee8b10be 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -743,8 +743,7 @@ flag, for example `docker build --no-cache`. See the [`Dockerfile` Best Practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/) for more information. -The cache for `RUN` instructions can be invalidated by `ADD` instructions. See -[below](#add) for details. +The cache for `RUN` instructions can be invalidated by [`ADD`](#add) and [`COPY`](#copy) instructions. ### Known issues (RUN) @@ -1114,7 +1113,7 @@ does not support authentication. > following instructions from the Dockerfile if the contents of `` have > changed. This includes invalidating the cache for `RUN` instructions. > See the [`Dockerfile` Best Practices -guide](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) +guide – Leverage build cache](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#leverage-build-cache) > for more information. @@ -1303,6 +1302,15 @@ image with the same name is attempted to be used instead. - If `` doesn't exist, it is created along with all missing directories in its path. + +> **Note** +> +> The first encountered `COPY` instruction will invalidate the cache for all +> following instructions from the Dockerfile if the contents of `` have +> changed. This includes invalidating the cache for `RUN` instructions. +> See the [`Dockerfile` Best Practices +guide – Leverage build cache](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#leverage-build-cache) +> for more information. ## ENTRYPOINT From 7017d6821cdb3d08af74c556b214a821d682d380 Mon Sep 17 00:00:00 2001 From: dito Date: Tue, 16 Jun 2020 10:17:58 +0900 Subject: [PATCH 128/152] Fix broken link Signed-off-by: Daisuke Ito --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 7ee8b10be..b8dca249a 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -608,7 +608,7 @@ FROM [--platform=] [@] [AS ] ``` The `FROM` instruction initializes a new build stage and sets the -[*Base Image*](../../glossary/#base-image) for subsequent instructions. As such, a +[*Base Image*](https://docs.docker.com/glossary/#base_image) for subsequent instructions. As such, a valid `Dockerfile` must start with a `FROM` instruction. The image can be any valid image – it is especially easy to start by **pulling an image** from the [*Public Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/). From 4a357285a18b6e398b0bde3a9beea45a33af49f6 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 1 Jul 2020 15:26:06 +0200 Subject: [PATCH 129/152] docs/builder: add note about handling of leading whitespace Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 46 ++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index b8dca249a..417ffb5ba 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -173,7 +173,7 @@ be UPPERCASE to distinguish them from arguments more easily. Docker runs instructions in a `Dockerfile` in order. A `Dockerfile` **must -begin with a \`FROM\` instruction**. This may be after [parser +begin with a `FROM` instruction**. This may be after [parser directives](#parser-directives), [comments](#format), and globally scoped [ARGs](#arg). The `FROM` instruction specifies the [*Parent Image*](https://docs.docker.com/glossary/#parent_image) from which you are @@ -189,8 +189,52 @@ else in a line is treated as an argument. This allows statements like: RUN echo 'we are running some # of cool things' ``` +Comment lines are removed before the Dockerfile instructions are executed, which +means that the comment in the following example is not handled by the shell +executing the `echo` command, and both examples below are equivalent: + +```dockerfile +RUN echo hello \ +# comment +world +``` + +```dockerfile +RUN echo hello \ +world +``` + Line continuation characters are not supported in comments. +> **Note on whitespace** +> +> For backward compatibility, leading whitespace before comments (`#`) and +> instructions (such as `RUN`) are ignored, but discouraged. Leading whitespace +> is not preserved in these cases, and the following examples are therefore +> equivalent: +> +> ```dockerfile +> # this is a comment-line +> RUN echo hello +> RUN echo world +> ``` +> +> ```dockerfile +> # this is a comment-line +> RUN echo hello +> RUN echo world +> ``` +> +> Note however, that whitespace in instruction _arguments_, such as the commands +> following `RUN`, are preserved, so the following example prints ` hello world` +> with leading whitespace as specified: +> +> ```dockerfile +> RUN echo "\ +> hello\ +> world" +> ``` + ## Parser directives Parser directives are optional, and affect the way in which subsequent lines From ad2278b77c3a4e55495a0b8a263af7420b583220 Mon Sep 17 00:00:00 2001 From: Tonis Tiigi Date: Mon, 27 Jul 2020 15:56:23 -0700 Subject: [PATCH 130/152] =?UTF-8?q?docs:=20remove=20docs=20for=20=E2=80=94?= =?UTF-8?q?-from=3Dindex?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Naming stages is the preferred method for using multi-stage builds. Signed-off-by: Tonis Tiigi --- frontend/dockerfile/docs/reference.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 417ffb5ba..d5a44c382 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -666,7 +666,7 @@ the [*Public Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos instructions. - Optionally a name can be given to a new build stage by adding `AS name` to the `FROM` instruction. The name can be used in subsequent `FROM` and - `COPY --from=` instructions to refer to the image built in this stage. + `COPY --from=` instructions to refer to the image built in this stage. - The `tag` or `digest` values are optional. If you omit either of them, the builder assumes a `latest` tag by default. The builder returns an error if it cannot find the `tag` value. @@ -1311,12 +1311,11 @@ no lookup and does not depend on container root filesystem content. > If you build using STDIN (`docker build - < somefile`), there is no > build context, so `COPY` can't be used. -Optionally `COPY` accepts a flag `--from=` that can be used to set +Optionally `COPY` accepts a flag `--from=` that can be used to set the source location to a previous build stage (created with `FROM .. AS `) -that will be used instead of a build context sent by the user. The flag also -accepts a numeric index assigned for all previous build stages started with -`FROM` instruction. In case a build stage with a specified name can't be found an -image with the same name is attempted to be used instead. +that will be used instead of a build context sent by the user. In case a build +stage with a specified name can't be found an image with the same name is +attempted to be used instead. `COPY` obeys the following rules: From 96d9235765a5dce5a0b16ee7050e22cfc525e88a Mon Sep 17 00:00:00 2001 From: eyherabh Date: Fri, 17 Jul 2020 22:18:02 +0300 Subject: [PATCH 131/152] Replaces ADD with COPY in the COPY section Possibly a typo from reusing text from the ADD section. Signed-off-by: Hugo Gabriel Eyherabide --- frontend/dockerfile/docs/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index d5a44c382..0b025f15c 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1276,11 +1276,11 @@ COPY test.txt /absoluteDir/ When copying files or directories that contain special characters (such as `[` and `]`), you need to escape those paths following the Golang rules to prevent -them from being treated as a matching pattern. For example, to add a file +them from being treated as a matching pattern. For example, to copy a file named `arr[0].txt`, use the following; ```dockerfile -ADD arr[[]0].txt /mydir/ +COPY arr[[]0].txt /mydir/ ``` All new files and directories are created with a UID and GID of 0, unless the From 669d2585a594ba254f26c75dfcca60d13ac55cb0 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 23 Sep 2020 12:42:17 +0200 Subject: [PATCH 132/152] builder: rephrase ENV section, remove examples for ENV key value without '=' The `ENV key value` form can be ambiguous, for example, the following defines a single env-variable (`ONE`) with value `"TWO= THREE=world"`: ENV ONE TWO= THREE=world While we cannot deprecate/remove that syntax (as it would break existing Dockerfiles), we should reduce exposure of the format in our examples. Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 71 ++++++++++++++------------- 1 file changed, 37 insertions(+), 34 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 0b025f15c..ab3c9e33d 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -500,10 +500,10 @@ Example (parsed representation is displayed after the `#`): ```dockerfile FROM busybox -ENV foo /bar -WORKDIR ${foo} # WORKDIR /bar -ADD . $foo # ADD . /bar -COPY \$foo /quux # COPY $foo /quux +ENV FOO=/bar +WORKDIR ${FOO} # WORKDIR /bar +ADD . $FOO # ADD . /bar +COPY \$FOO /quux # COPY $FOO /quux ``` Environment variables are supported by the following list of instructions in @@ -994,53 +994,56 @@ port. For detailed information, see the ## ENV ```dockerfile -ENV ENV = ... ``` The `ENV` instruction sets the environment variable `` to the value ``. This value will be in the environment for all subsequent instructions in the build stage and can be [replaced inline](#environment-replacement) in -many as well. - -The `ENV` instruction has two forms. The first form, `ENV `, -will set a single variable to a value. The entire string after the first -space will be treated as the `` - including whitespace characters. The -value will be interpreted for other environment variables, so quote characters -will be removed if they are not escaped. - -The second form, `ENV = ...`, allows for multiple variables to -be set at one time. Notice that the second form uses the equals sign (=) -in the syntax, while the first form does not. Like command line parsing, +many as well. The value will be interpreted for other environment variables, so +quote characters will be removed if they are not escaped. Like command line parsing, quotes and backslashes can be used to include spaces within values. -For example: +Example: ```dockerfile -ENV myName="John Doe" myDog=Rex\ The\ Dog \ - myCat=fluffy +ENV MY_NAME="John Doe" +ENV MY_DOG=Rex\ The\ Dog +ENV MY_CAT=fluffy ``` -and +The `ENV` instruction allows for multiple `= ...` variables to be set +at one time, and the example below will yield the same net results in the final +image: ```dockerfile -ENV myName John Doe -ENV myDog Rex The Dog -ENV myCat fluffy +ENV MY_NAME="John Doe" MY_DOG=Rex\ The\ Dog \ + MY_CAT=fluffy ``` -will yield the same net results in the final image. - The environment variables set using `ENV` will persist when a container is run from the resulting image. You can view the values using `docker inspect`, and change them using `docker run --env =`. > **Note** > -> Environment persistence can cause unexpected side effects. For example, -> setting `ENV DEBIAN_FRONTEND noninteractive` may confuse apt-get -> users on a Debian-based image. To set a value for a single command, use -> `RUN = `. +> Environment variable persistence can cause unexpected side effects. For example, +> setting `ENV DEBIAN_FRONTEND=noninteractive` changes the behavior of `apt-get`, +> and may confuse users of your image. +> +> If an environment variable is only needed during build, and not in the final +> image, consider setting a value for a single command instead: +> +> ```dockerfile +> RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y ... +> ``` +> +> Or using [`ARG`](#arg), which is not persisted in the final image: +> +> ```dockerfile +> ARG DEBIAN_FRONTEND=noninteractive +> RUN apt-get update && apt-get install -y ... +> ``` ## ADD @@ -1768,7 +1771,7 @@ The `WORKDIR` instruction can resolve environment variables previously set using For example: ```dockerfile -ENV DIRPATH /path +ENV DIRPATH=/path WORKDIR $DIRPATH/$DIRNAME RUN pwd ``` @@ -1873,7 +1876,7 @@ this Dockerfile with an `ENV` and `ARG` instruction. ```dockerfile FROM ubuntu ARG CONT_IMG_VER -ENV CONT_IMG_VER v1.0.0 +ENV CONT_IMG_VER=v1.0.0 RUN echo $CONT_IMG_VER ``` @@ -1894,7 +1897,7 @@ useful interactions between `ARG` and `ENV` instructions: ```dockerfile FROM ubuntu ARG CONT_IMG_VER -ENV CONT_IMG_VER ${CONT_IMG_VER:-v1.0.0} +ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0} RUN echo $CONT_IMG_VER ``` @@ -2030,7 +2033,7 @@ Consider another example under the same command line: ```dockerfile FROM ubuntu ARG CONT_IMG_VER -ENV CONT_IMG_VER $CONT_IMG_VER +ENV CONT_IMG_VER=$CONT_IMG_VER RUN echo $CONT_IMG_VER ``` @@ -2045,7 +2048,7 @@ this Dockerfile: ```dockerfile FROM ubuntu ARG CONT_IMG_VER -ENV CONT_IMG_VER hello +ENV CONT_IMG_VER=hello RUN echo $CONT_IMG_VER ``` From dec7a2a053bcab00f9df956dbb80f24e6396fd7c Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 23 Sep 2020 13:05:00 +0200 Subject: [PATCH 133/152] builder: add note about alternative syntax Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 40 +++++++++++++++++++-------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index ab3c9e33d..bbaa010bb 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1025,25 +1025,43 @@ The environment variables set using `ENV` will persist when a container is run from the resulting image. You can view the values using `docker inspect`, and change them using `docker run --env =`. -> **Note** +Environment variable persistence can cause unexpected side effects. For example, +setting `ENV DEBIAN_FRONTEND=noninteractive` changes the behavior of `apt-get`, +and may confuse users of your image. + +If an environment variable is only needed during build, and not in the final +image, consider setting a value for a single command instead: + +```dockerfile +RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y ... +``` + +Or using [`ARG`](#arg), which is not persisted in the final image: + +```dockerfile +ARG DEBIAN_FRONTEND=noninteractive +RUN apt-get update && apt-get install -y ... +``` + +> **Alternative syntax** > -> Environment variable persistence can cause unexpected side effects. For example, -> setting `ENV DEBIAN_FRONTEND=noninteractive` changes the behavior of `apt-get`, -> and may confuse users of your image. -> -> If an environment variable is only needed during build, and not in the final -> image, consider setting a value for a single command instead: +> The `ENV` instruction also allows an alternative syntax `ENV `, +> omitting the `=`. For example: > > ```dockerfile -> RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y ... +> ENV MY_VAR my-value > ``` > -> Or using [`ARG`](#arg), which is not persisted in the final image: +> This syntax does not allow for multiple environment-variables to be set in a +> single `ENV` instruction, and can be confusing. For example, the following +> sets a single environment variable (`ONE`) with value `"TWO= THREE=world"`: > > ```dockerfile -> ARG DEBIAN_FRONTEND=noninteractive -> RUN apt-get update && apt-get install -y ... +> ENV ONE TWO= THREE=world > ``` +> +> The alternative syntax is supported for backward compatibility, but discouraged +> for the reasons outlined above, and may be removed in a future release. ## ADD From ad3cd32ea215a18b38ba679ef8586b8992aefb71 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 26 Oct 2020 18:30:01 +0100 Subject: [PATCH 134/152] docs: remove some references to obsolete docker versions Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index bbaa010bb..2093a7070 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -2216,8 +2216,6 @@ are stored currently). When the health status of a container changes, a `health_status` event is generated with the new status. -The `HEALTHCHECK` feature was added in Docker 1.12. - ## SHELL @@ -2342,8 +2340,6 @@ environment variable expansion semantics could be modified. The `SHELL` instruction can also be used on Linux should an alternate shell be required such as `zsh`, `csh`, `tcsh` and others. -The `SHELL` feature was added in Docker 1.12. - ## External implementation features This feature is only available when using the [BuildKit](#buildkit) backend. From 95e7f34ce482ef43e56c050eb43f720ba661424a Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Sun, 1 Nov 2020 18:08:36 +0100 Subject: [PATCH 135/152] docs/builder: fix typo Signed-off-by: Eric Engestrom --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 2093a7070..510eab89c 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -2043,7 +2043,7 @@ RUN echo hello If you specify `--build-arg CONT_IMG_VER=` on the command line, in both cases, the specification on line 2 does not cause a cache miss; line 3 does cause a cache miss.`ARG CONT_IMG_VER` causes the RUN line to be identified -as the same as running `CONT_IMG_VER=` echo hello, so if the `` +as the same as running `CONT_IMG_VER= echo hello`, so if the `` changes, we get a cache miss. Consider another example under the same command line: From bd8247506d5a6026f766fadee2814f02a7284230 Mon Sep 17 00:00:00 2001 From: Kyle Date: Sat, 7 Nov 2020 08:29:39 -0500 Subject: [PATCH 136/152] docs/builder: fix broken link Signed-off-by: kylemit --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 510eab89c..4ebe6ae6d 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -655,7 +655,7 @@ The `FROM` instruction initializes a new build stage and sets the [*Base Image*](https://docs.docker.com/glossary/#base_image) for subsequent instructions. As such, a valid `Dockerfile` must start with a `FROM` instruction. The image can be any valid image – it is especially easy to start by **pulling an image** from -the [*Public Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/). +the [*Public Repositories*](https://docs.docker.com/docker-hub/repos/). - `ARG` is the only instruction that may precede `FROM` in the `Dockerfile`. See [Understand how ARG and FROM interact](#understand-how-arg-and-from-interact). From b80bae0c1c00b37f12a8f015aa56b33b1e545449 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 20 Apr 2021 11:03:34 +0200 Subject: [PATCH 137/152] docs/reference/builder: touch-up code-hints and some minor changes - use "console" for code-hints, to make process output distinguishable from the commands that are executed - use a consistent prompt for powershell examples - minor changes in wording around "build context" to reduce confusion with `docker context` Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 75 ++++++++++++++------------- 1 file changed, 40 insertions(+), 35 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 4ebe6ae6d..38c4d8276 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -33,11 +33,11 @@ a `Dockerfile` and a *context*. The build's context is the set of files at a specified location `PATH` or `URL`. The `PATH` is a directory on your local filesystem. The `URL` is a Git repository location. -A context is processed recursively. So, a `PATH` includes any subdirectories and -the `URL` includes the repository and its submodules. This example shows a -build command that uses the current directory as context: +The build context is processed recursively. So, a `PATH` includes any subdirectories +and the `URL` includes the repository and its submodules. This example shows a +build command that uses the current directory (`.`) as build context: -```bash +```console $ docker build . Sending build context to Docker daemon 6.51 MB @@ -52,8 +52,9 @@ Dockerfile. > **Warning** > -> Do not use your root directory, `/`, as the `PATH` as it causes the build to -> transfer the entire contents of your hard drive to the Docker daemon. +> Do not use your root directory, `/`, as the `PATH` for your build context, as +> it causes the build to transfer the entire contents of your hard drive to the +> Docker daemon. {:.warning} To use a file in the build context, the `Dockerfile` refers to the file specified @@ -66,28 +67,28 @@ Traditionally, the `Dockerfile` is called `Dockerfile` and located in the root of the context. You use the `-f` flag with `docker build` to point to a Dockerfile anywhere in your file system. -```bash +```console $ docker build -f /path/to/a/Dockerfile . ``` You can specify a repository and tag at which to save the new image if the build succeeds: -```bash +```console $ docker build -t shykes/myapp . ``` To tag the image into multiple repositories after the build, add multiple `-t` parameters when you run the `build` command: -```bash +```console $ docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest . ``` Before the Docker daemon runs the instructions in the `Dockerfile`, it performs a preliminary validation of the `Dockerfile` and returns an error if the syntax is incorrect: -```bash +```console $ docker build -t test/myapp . Sending build context to Docker daemon 2.048 kB @@ -109,7 +110,7 @@ to accelerate the `docker build` process significantly. This is indicated by the `Using cache` message in the console output. (For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/): -```bash +```console $ docker build -t svendowideit/ambassador . Sending build context to Docker daemon 15.36 kB @@ -413,14 +414,15 @@ RUN dir c:\ Results in: -```powershell -PS C:\John> docker build -t cmd . +```console +PS E:\myproject> docker build -t cmd . + Sending build context to Docker daemon 3.072 kB Step 1/2 : FROM microsoft/nanoserver ---> 22738ff49c6d Step 2/2 : COPY testfile.txt c:\RUN dir c: GetFileAttributesEx c:RUN: The system cannot find the file specified. -PS C:\John> +PS E:\myproject> ``` One solution to the above would be to use `/` as the target of both the `COPY` @@ -441,8 +443,9 @@ RUN dir c:\ Results in: -```powershell -PS C:\John> docker build -t succeeds --no-cache=true . +```console +PS E:\myproject> docker build -t succeeds --no-cache=true . + Sending build context to Docker daemon 3.072 kB Step 1/3 : FROM microsoft/nanoserver ---> 22738ff49c6d @@ -467,7 +470,7 @@ Step 3/3 : RUN dir c:\ ---> 01c7f3bef04f Removing intermediate container a2c157f842f5 Successfully built 01c7f3bef04f -PS C:\John> +PS E:\myproject> ``` ## Environment replacement @@ -910,8 +913,8 @@ the most-recently-applied value overrides any previously-set value. To view an image's labels, use the `docker image inspect` command. You can use the `--format` option to show just the labels; -```bash -docker image inspect --format='{{json .Config.Labels}}' myimage +```console +$ docker image inspect --format='{{json .Config.Labels}}' myimage ``` ```json { @@ -980,8 +983,8 @@ port on the host, so the port will not be the same for TCP and UDP. Regardless of the `EXPOSE` settings, you can override them at runtime by using the `-p` flag. For example -```bash -docker run -p 80:80/tcp -p 80:80/udp ... +```console +$ docker run -p 80:80/tcp -p 80:80/udp ... ``` To set up port redirection on the host system, see [using the -P flag](run.md#expose-incoming-ports). @@ -1397,7 +1400,7 @@ An `ENTRYPOINT` allows you to configure a container that will run as an executab For example, the following starts nginx with its default content, listening on port 80: -```bash +```console $ docker run -i -t --rm -p 80:80 nginx ``` @@ -1432,7 +1435,7 @@ CMD ["-c"] When you run the container, you can see that `top` is the only process: -```bash +```console $ docker run -it --rm --name test top -H top - 08:25:00 up 7:27, 0 users, load average: 0.00, 0.01, 0.05 @@ -1447,7 +1450,7 @@ KiB Swap: 1441840 total, 0 used, 1441840 free. 1324440 cached Mem To examine the result further, you can use `docker exec`: -```bash +```console $ docker exec -it test ps aux USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND @@ -1519,7 +1522,7 @@ If you run this image with `docker run -it --rm -p 80:80 --name test apache`, you can then examine the container's processes with `docker exec`, or `docker top`, and then ask the script to stop Apache: -```bash +```console $ docker exec -it test ps aux USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND @@ -1579,7 +1582,7 @@ ENTRYPOINT exec top -b When you run this image, you'll see the single `PID 1` process: -```bash +```console $ docker run -it --rm --name test top Mem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cached @@ -1591,7 +1594,7 @@ Load average: 0.08 0.03 0.05 2/98 6 Which exits cleanly on `docker stop`: -```bash +```console $ /usr/bin/time docker stop test test @@ -1610,7 +1613,7 @@ CMD --ignored-param1 You can then run it (giving it a name for the next step): -```bash +```console $ docker run -it --name test top --ignored-param2 Mem: 1704184K used, 352484K free, 0K shrd, 0K buff, 140621524238337K cached @@ -1626,7 +1629,7 @@ You can see from the output of `top` that the specified `ENTRYPOINT` is not `PID If you then run `docker stop test`, the container will not exit cleanly - the `stop` command will be forced to send a `SIGKILL` after the timeout: -```bash +```console $ docker exec -it test ps aux PID USER COMMAND @@ -1859,9 +1862,10 @@ ARG user USER $user # ... ``` + A user builds this file by calling: -```bash +```console $ docker build --build-arg user=what_user . ``` @@ -1900,7 +1904,7 @@ RUN echo $CONT_IMG_VER Then, assume this image is built with this command: -```bash +```console $ docker build --build-arg CONT_IMG_VER=v2.0.1 . ``` @@ -1922,7 +1926,7 @@ RUN echo $CONT_IMG_VER Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. Consider a docker build without the `--build-arg` flag: -```bash +```console $ docker build . ``` @@ -2298,8 +2302,9 @@ RUN c:\example\Execute-MyCmdlet -sample 'hello world' Resulting in: -```powershell -PS E:\docker\build\shell> docker build -t shell . +```console +PS E:\myproject> docker build -t shell . + Sending build context to Docker daemon 4.096 kB Step 1/5 : FROM microsoft/nanoserver ---> 22738ff49c6d @@ -2330,7 +2335,7 @@ hello world ---> 8e559e9bf424 Removing intermediate container be6d8e63fe75 Successfully built 8e559e9bf424 -PS E:\docker\build\shell> +PS E:\myproject> ``` The `SHELL` instruction could also be used to modify the way in which From 928bd28890bb21de4f8d84eaa41e40132adb96f3 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 21 Apr 2021 11:45:35 +0200 Subject: [PATCH 138/152] docs/reference/builder: remove outdated example Dockerfiles These examples were really outdated, so linking to other sections in the documentation instead. Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 50 +++------------------------ 1 file changed, 4 insertions(+), 46 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 38c4d8276..2c4ebe803 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -2356,50 +2356,8 @@ builder with a syntax directive. To learn about these features, ## Dockerfile examples -Below you can see some examples of Dockerfile syntax. +For examples of Dockerfiles, refer to: -```dockerfile -# Nginx -# -# VERSION 0.0.1 - -FROM ubuntu -LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products" Version="1.0" -RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server -``` - -```dockerfile -# Firefox over VNC -# -# VERSION 0.3 - -FROM ubuntu - -# Install vnc, xvfb in order to create a 'fake' display and firefox -RUN apt-get update && apt-get install -y x11vnc xvfb firefox -RUN mkdir ~/.vnc -# Setup a password -RUN x11vnc -storepasswd 1234 ~/.vnc/passwd -# Autostart firefox (might not be the best way, but it does the trick) -RUN bash -c 'echo "firefox" >> /.bashrc' - -EXPOSE 5900 -CMD ["x11vnc", "-forever", "-usepw", "-create"] -``` - -```dockerfile -# Multiple images example -# -# VERSION 0.1 - -FROM ubuntu -RUN echo foo > bar -# Will output something like ===> 907ad6c2736f - -FROM ubuntu -RUN echo moo > oink -# Will output something like ===> 695d7793cbe4 - -# You'll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with -# /oink. -``` +- The ["build images" section](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) +- The ["get started](https://docs.docker.com/get-started/) +- The [language-specific getting started guides](https://docs.docker.com/language/) From 9b713d21ed5e62b1284bc17030de7cb264f2e7f0 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 21 Apr 2021 11:47:31 +0200 Subject: [PATCH 139/152] docs/reference/builder: update example output, and some rephrasing - update some examples to show the BuildKit output - remove some wording about "images" being used for the build cache - add a link to the `--cache-from` section - added a link to "scanning your image with `docker scan`" - updated link to "push your image" Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 62 ++++++++++++++------------- 1 file changed, 32 insertions(+), 30 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 2c4ebe803..7b19d9723 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -91,8 +91,13 @@ a preliminary validation of the `Dockerfile` and returns an error if the syntax ```console $ docker build -t test/myapp . -Sending build context to Docker daemon 2.048 kB -Error response from daemon: Unknown instruction: RUNCMD +[+] Building 0.3s (2/2) FINISHED + => [internal] load build definition from Dockerfile 0.1s + => => transferring dockerfile: 60B 0.0s + => [internal] load .dockerignore 0.1s + => => transferring context: 2B 0.0s +error: failed to solve: rpc error: code = Unknown desc = failed to solve with frontend dockerfile.v0: failed to create LLB definition: +dockerfile parse error line 2: unknown instruction: RUNCMD ``` The Docker daemon runs the instructions in the `Dockerfile` one-by-one, @@ -105,38 +110,35 @@ Note that each instruction is run independently, and causes a new image to be created - so `RUN cd /tmp` will not have any effect on the next instructions. -Whenever possible, Docker will re-use the intermediate images (cache), -to accelerate the `docker build` process significantly. This is indicated by -the `Using cache` message in the console output. -(For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/): +Whenever possible, Docker uses a build-cache to accelerate the `docker build` +process significantly. This is indicated by the `CACHED` message in the console +output. (For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/): ```console $ docker build -t svendowideit/ambassador . -Sending build context to Docker daemon 15.36 kB -Step 1/4 : FROM alpine:3.2 - ---> 31f630c65071 -Step 2/4 : MAINTAINER SvenDowideit@home.org.au - ---> Using cache - ---> 2a1c91448f5f -Step 3/4 : RUN apk update && apk add socat && rm -r /var/cache/ - ---> Using cache - ---> 21ed6e7fbb73 -Step 4/4 : CMD env | grep _TCP= | (sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' && echo wait) | sh - ---> Using cache - ---> 7ea8aef582cc -Successfully built 7ea8aef582cc +[+] Building 0.7s (6/6) FINISHED + => [internal] load build definition from Dockerfile 0.1s + => => transferring dockerfile: 286B 0.0s + => [internal] load .dockerignore 0.1s + => => transferring context: 2B 0.0s + => [internal] load metadata for docker.io/library/alpine:3.2 0.4s + => CACHED [1/2] FROM docker.io/library/alpine:3.2@sha256:e9a2035f9d0d7ce 0.0s + => CACHED [2/2] RUN apk add --no-cache socat 0.0s + => exporting to image 0.0s + => => exporting layers 0.0s + => => writing image sha256:1affb80ca37018ac12067fa2af38cc5bcc2a8f09963de 0.0s + => => naming to docker.io/library/mysocatimage 0.0s ``` -Build cache is only used from images that have a local parent chain. This means -that these images were created by previous builds or the whole chain of images -was loaded with `docker load`. If you wish to use build cache of a specific -image you can specify it with `--cache-from` option. Images specified with -`--cache-from` do not need to have a parent chain and may be pulled from other -registries. +By default, the build cache is based results from previous builds on the machine +on which you are building. The `--cache-from` option also allows you to use a +build-cache that's distributed through an image registry refer to the +[specifying external cache sources](commandline/build.md#specifying-external-cache-sources) +section in the `docker build` command reference. -When you're done with your build, you're ready to look into [*Pushing a -repository to its registry*](https://docs.docker.com/engine/tutorials/dockerrepos/#/contributing-to-docker-hub). +When you're done with your build, you're ready to look into [scanning your image with `docker scan`](https://docs.docker.com/engine/scan/), +and [pushing your image to Docker Hub](https://docs.docker.com/docker-hub/repos/). ## BuildKit @@ -2319,9 +2321,9 @@ Step 3/5 : RUN New-Item -ItemType Directory C:\Example Directory: C:\ -Mode LastWriteTime Length Name ----- ------------- ------ ---- -d----- 10/28/2016 11:26 AM Example +Mode LastWriteTime Length Name +---- ------------- ------ ---- +d----- 10/28/2016 11:26 AM Example ---> 3f2fbf1395d9 From d569fcca1776f70dd5c5e07b8ee1fcd01056acb0 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 21 Apr 2021 22:36:16 +0200 Subject: [PATCH 140/152] docs/reference/builder: update "syntax" section - rename "experimental" to "labs" - rephrase recommendation for picking a version - clarify that the "labs" channel provides a superset of the "stable" channel. - remove "External implementation features" section, because it overlapped with the "syntax" section. - removed `:latest` from the "stable" channel (generally not recommended) Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 91 +++++++++++++++------------ 1 file changed, 51 insertions(+), 40 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 7b19d9723..bc6c74677 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -128,10 +128,10 @@ $ docker build -t svendowideit/ambassador . => exporting to image 0.0s => => exporting layers 0.0s => => writing image sha256:1affb80ca37018ac12067fa2af38cc5bcc2a8f09963de 0.0s - => => naming to docker.io/library/mysocatimage 0.0s + => => naming to docker.io/svendowideit/ambassador 0.0s ``` -By default, the build cache is based results from previous builds on the machine +By default, the build cache is based on results from previous builds on the machine on which you are building. The `--cache-from` option also allows you to use a build-cache that's distributed through an image registry refer to the [specifying external cache sources](commandline/build.md#specifying-external-cache-sources) @@ -318,6 +318,8 @@ The following parser directives are supported: ## syntax + + ```dockerfile # syntax=[remote image reference] ``` @@ -325,55 +327,73 @@ The following parser directives are supported: For example: ```dockerfile -# syntax=docker/dockerfile -# syntax=docker/dockerfile:1.0 +# syntax=docker/dockerfile:1 # syntax=docker.io/docker/dockerfile:1 -# syntax=docker/dockerfile:1.0.0-experimental # syntax=example.com/user/repo:tag@sha256:abcdef... ``` -This feature is only enabled if the [BuildKit](#buildkit) backend is used. +This feature is only available when using the [BuildKit](#buildkit) backend, and +is ignored when using the classic builder backend. -The syntax directive defines the location of the Dockerfile builder that is used for -building the current Dockerfile. The BuildKit backend allows to seamlessly use -external implementations of builders that are distributed as Docker images and -execute inside a container sandbox environment. +The syntax directive defines the location of the Dockerfile syntax that is used +to build the Dockerfile. The BuildKit backend allows to seamlessly use external +implementations that are distributed as Docker images and execute inside a +container sandbox environment. -Custom Dockerfile implementation allows you to: +Custom Dockerfile implementations allows you to: - - Automatically get bugfixes without updating the daemon + - Automatically get bugfixes without updating the Docker daemon - Make sure all users are using the same implementation to build your Dockerfile - - Use the latest features without updating the daemon - - Try out new experimental or third-party features + - Use the latest features without updating the Docker daemon + - Try out new features or third-party features before they are integrated in the Docker daemon + - Use [alternative build definitions, or create your own](https://github.com/moby/buildkit#exploring-llb) ### Official releases Docker distributes official versions of the images that can be used for building Dockerfiles under `docker/dockerfile` repository on Docker Hub. There are two -channels where new images are released: stable and experimental. +channels where new images are released: `stable` and `labs`. -Stable channel follows semantic versioning. For example: +Stable channel follows [semantic versioning](https://semver.org). For example: - - `docker/dockerfile:1.0.0` - only allow immutable version `1.0.0` - - `docker/dockerfile:1.0` - allow versions `1.0.*` - - `docker/dockerfile:1` - allow versions `1.*.*` - - `docker/dockerfile:latest` - latest release on stable channel + - `docker/dockerfile:1` - kept updated with the latest `1.x.x` minor _and_ patch release + - `docker/dockerfile:1.2` - kept updated with the latest `1.2.x` patch release, + and stops receiving updates once version `1.3.0` is released. + - `docker/dockerfile:1.2.1` - immutable: never updated -The experimental channel uses incremental versioning with the major and minor -component from the stable channel on the time of the release. For example: +We recommend using `docker/dockerfile:1`, which always points to the latest stable +release of the version 1 syntax, and receives both "minor" and "patch" updates +for the version 1 release cycle. BuildKit automatically checks for updates of the +syntax when performing a build, making sure you are using the most current version. - - `docker/dockerfile:1.0.1-experimental` - only allow immutable version `1.0.1-experimental` - - `docker/dockerfile:1.0-experimental` - latest experimental releases after `1.0` - - `docker/dockerfile:experimental` - latest release on experimental channel +If a specific version is used, such as `1.2` or `1.2.1`, the Dockerfile needs to +be updated manually to continue receiving bugfixes and new features. Old versions +of the Dockerfile remain compatible with the new versions of the builder. -You should choose a channel that best fits your needs. If you only want -bugfixes, you should use `docker/dockerfile:1.0`. If you want to benefit from -experimental features, you should use the experimental channel. If you are using -the experimental channel, newer releases may not be backwards compatible, so it +**labs channel** + +The "labs" channel provides early access to Dockerfile features that are not yet +available in the stable channel. Labs channel images are released in conjunction +with the stable releases, and follow the same versioning with the `-labs` suffix, +for example: + + - `docker/dockerfile:labs` - latest release on labs channel + - `docker/dockerfile:1-labs` - same as `dockerfile:1` in the stable channel, with labs features enabled + - `docker/dockerfile:1.2-labs` - same as `dockerfile:1.2` in the stable channel, with labs features enabled + - `docker/dockerfile:1.2.1-labs` - immutable: never updated. Same as `dockerfile:1.2.1` in the stable channel, with labs features enabled + +Choose a channel that best fits your needs; if you want to benefit from +new features, use the labs channel. Images in the labs channel provide a superset +of the features in the stable channel; note that `stable` features in the labs +channel images follow [semantic versioning](https://semver.org), but "labs" +features do not, and newer releases may not be backwards compatible, so it is recommended to use an immutable full version variant. -For master builds and nightly feature releases refer to the description in -[the source repository](https://github.com/moby/buildkit/blob/master/README.md). +For documentation on "labs" features, master builds, and nightly feature releases, +refer to the description in [the BuildKit source repository on GitHub](https://github.com/moby/buildkit/blob/master/README.md). +For a full list of available images, visit the [image repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile), +and the [docker/dockerfile-upstream image repository](https://hub.docker.com/r/docker/dockerfile-upstream) +for development builds. ## escape @@ -2347,15 +2367,6 @@ environment variable expansion semantics could be modified. The `SHELL` instruction can also be used on Linux should an alternate shell be required such as `zsh`, `csh`, `tcsh` and others. -## External implementation features - -This feature is only available when using the [BuildKit](#buildkit) backend. - -Docker build supports experimental features like cache mounts, build secrets and -ssh forwarding that are enabled by using an external implementation of the -builder with a syntax directive. To learn about these features, -[refer to the documentation in BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md). - ## Dockerfile examples For examples of Dockerfiles, refer to: From c8853bc28eef372204df5aa319c990798f8faa50 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Fri, 30 Apr 2021 12:08:28 +0200 Subject: [PATCH 141/152] docs: update some examples for proxy configuration Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index bc6c74677..07e6e241c 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1974,10 +1974,11 @@ corresponding `ARG` instruction in the Dockerfile. - `NO_PROXY` - `no_proxy` -To use these, simply pass them on the command line using the flag: +To use these, pass them on the command line using the `--build-arg` flag, for +example: -```bash ---build-arg = +```console +$ docker build --build-arg HTTPS_PROXY=https://my-proxy.example.com . ``` By default, these pre-defined variables are excluded from the output of From 1df1b404d9e2d5d29755d8e31e74ceabb954438b Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Tue, 4 May 2021 09:45:10 -0700 Subject: [PATCH 142/152] Swap "LABEL maintainer" for the OCI pre-defined "org.opencontainers.image.authors" https://github.com/opencontainers/image-spec/blob/v1.0.1/annotations.md#pre-defined-annotation-keys Signed-off-by: Tianon Gravi --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 07e6e241c..d5651db8e 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -963,7 +963,7 @@ easily, for example with `docker inspect`. To set a label corresponding to the `MAINTAINER` field you could use: ```dockerfile -LABEL maintainer="SvenDowideit@home.org.au" +LABEL org.opencontainers.image.authors="SvenDowideit@home.org.au" ``` This will then be visible from `docker inspect` with the other labels. From 92f671534672672c68a41b5a6d409c438bf03a2c Mon Sep 17 00:00:00 2001 From: Govind Rai Date: Wed, 16 Jun 2021 16:47:28 -0700 Subject: [PATCH 143/152] Update WORKDIR command information Signed-off-by: Govind Rai --- frontend/dockerfile/docs/reference.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index d5651db8e..1e7684ea2 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1822,6 +1822,11 @@ RUN pwd The output of the final `pwd` command in this `Dockerfile` would be `/path/$DIRNAME` +If not specified, the default working directory is `/`. In practice, if you aren't building a Dockerfile from scratch (`FROM scratch`), +the `WORKDIR` may likely be set by the base image you're using. + +Therefore, to avoid unintended operations in unknown directories, it is best practice to set your `WORKDIR` explicitly. + ## ARG ```dockerfile From b013cdd1e5f4626d554fd8280d8fa496d4e81276 Mon Sep 17 00:00:00 2001 From: Takuya Noguchi Date: Mon, 28 Jun 2021 06:03:28 +0000 Subject: [PATCH 144/152] Fix the (dead) link for docs for Dockerfile syntax reference This change will update the docs at https://docs.docker.com/engine/reference/builder/#buildkit This change is required by https://github.com/moby/buildkit/pull/1884 Signed-off-by: Takuya Noguchi --- frontend/dockerfile/docs/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index d5651db8e..640c5a423 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -159,8 +159,8 @@ implementation. For example, BuildKit can: To use the BuildKit backend, you need to set an environment variable `DOCKER_BUILDKIT=1` on the CLI before invoking `docker build`. -To learn about the experimental Dockerfile syntax available to BuildKit-based -builds [refer to the documentation in the BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md). +To learn about the Dockerfile syntax available to BuildKit-based +builds [refer to the documentation in the BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md). ## Format From 1c2a7fce5a7a9d79f45cef65cfa09194e30422cb Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Fri, 30 Apr 2021 11:53:53 +0200 Subject: [PATCH 145/152] Add support for ALL_PROXY Support for ALL_PROXY as default build-arg was added recently in buildkit and the classic builder. This patch adds the `ALL_PROXY` environment variable to the list of configurable proxy variables, and updates the documentation. Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index d5651db8e..d243535ed 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1973,6 +1973,8 @@ corresponding `ARG` instruction in the Dockerfile. - `ftp_proxy` - `NO_PROXY` - `no_proxy` +- `ALL_PROXY` +- `all_proxy` To use these, pass them on the command line using the `--build-arg` flag, for example: From 9e07392d8e57ed88f733c2a92f250664467fbcfa Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 21 Aug 2021 13:50:05 +0200 Subject: [PATCH 146/152] docs: rewrite reference docs for --stop-signal and --stop-timeout Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index d243535ed..cae532a01 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -2173,9 +2173,14 @@ ONBUILD RUN /usr/local/bin/python-build --dir /app/src STOPSIGNAL signal ``` -The `STOPSIGNAL` instruction sets the system call signal that will be sent to the container to exit. -This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, -or a signal name in the format SIGNAME, for instance SIGKILL. +The `STOPSIGNAL` instruction sets the system call signal that will be sent to the +container to exit. This signal can be a signal name in the format `SIG`, +for instance `SIGKILL`, or an unsigned number that matches a position in the +kernel's syscall table, for instance `9`. The default is `SIGTERM` if not +defined. + +The image's default stopsignal can be overridden per container, using the +`--stop-signal` flag on `docker run` and `docker create`. ## HEALTHCHECK From 01bbd49bfe857a50e1e19071bc0f02021882af28 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 21 Aug 2021 14:54:14 +0200 Subject: [PATCH 147/152] docs: use "console" code-hint for shell examples This replaces the use of bash where suitable, to allow easier copy/pasting of shell examples without copying the prompt or process output. Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index cae532a01..f08ea5cd4 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -759,6 +759,7 @@ RUN instruction onto the next line. For example, consider these two lines: RUN /bin/bash -c 'source $HOME/.bashrc; \ echo $HOME' ``` + Together they are equivalent to this single line: ```dockerfile @@ -938,6 +939,7 @@ the `--format` option to show just the labels; ```console $ docker image inspect --format='{{json .Config.Labels}}' myimage ``` + ```json { "com.example.vendor": "ACME Incorporated", From ae64f89e3f6a612f88c9caab4edc77504e591ddd Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 13 Sep 2021 16:20:09 +0200 Subject: [PATCH 148/152] docs: fix some broken anchors Signed-off-by: Sebastiaan van Stijn --- frontend/dockerfile/docs/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index f08ea5cd4..533c635d7 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -179,7 +179,7 @@ Docker runs instructions in a `Dockerfile` in order. A `Dockerfile` **must begin with a `FROM` instruction**. This may be after [parser directives](#parser-directives), [comments](#format), and globally scoped [ARGs](#arg). The `FROM` instruction specifies the [*Parent -Image*](https://docs.docker.com/glossary/#parent_image) from which you are +Image*](https://docs.docker.com/glossary/#parent-image) from which you are building. `FROM` may only be preceded by one or more `ARG` instructions, which declare arguments that are used in `FROM` lines in the `Dockerfile`. @@ -677,7 +677,7 @@ FROM [--platform=] [@] [AS ] ``` The `FROM` instruction initializes a new build stage and sets the -[*Base Image*](https://docs.docker.com/glossary/#base_image) for subsequent instructions. As such, a +[*Base Image*](https://docs.docker.com/glossary/#base-image) for subsequent instructions. As such, a valid `Dockerfile` must start with a `FROM` instruction. The image can be any valid image – it is especially easy to start by **pulling an image** from the [*Public Repositories*](https://docs.docker.com/docker-hub/repos/). From 119e894d0962f5e9be1c1d8fc78e41e78d214d4c Mon Sep 17 00:00:00 2001 From: Peter Dave Hello Date: Fri, 15 Oct 2021 06:04:36 +0800 Subject: [PATCH 149/152] Update most links in docs to use https by default cc @thaJeztah docker/docker.github.io#13680 Signed-off-by: Peter Dave Hello --- frontend/dockerfile/docs/reference.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 533c635d7..b3fca493c 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -599,10 +599,10 @@ This file causes the following build behavior: Matching is done using Go's -[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. A +[filepath.Match](https://golang.org/pkg/path/filepath#Match) rules. A preprocessing step removes leading and trailing whitespace and eliminates `.` and `..` elements using Go's -[filepath.Clean](http://golang.org/pkg/path/filepath/#Clean). Lines +[filepath.Clean](https://golang.org/pkg/path/filepath/#Clean). Lines that are blank after preprocessing are ignored. Beyond Go's filepath.Match rules, Docker also supports a special @@ -1117,7 +1117,7 @@ directories, their paths are interpreted as relative to the source of the context of the build. Each `` may contain wildcards and matching will be done using Go's -[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: +[filepath.Match](https://golang.org/pkg/path/filepath#Match) rules. For example: To add all files starting with "hom": @@ -1293,7 +1293,7 @@ directories will be interpreted as relative to the source of the context of the build. Each `` may contain wildcards and matching will be done using Go's -[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: +[filepath.Match](https://golang.org/pkg/path/filepath#Match) rules. For example: To add all files starting with "hom": From 144e9385a9f0491148ab16fed6551879d4933194 Mon Sep 17 00:00:00 2001 From: jlecordier Date: Wed, 8 Dec 2021 18:02:45 +0100 Subject: [PATCH 150/152] added missing closing parenthese Signed-off-by: jlecordier --- frontend/dockerfile/docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index b3fca493c..d47ba7151 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -112,7 +112,7 @@ instructions. Whenever possible, Docker uses a build-cache to accelerate the `docker build` process significantly. This is indicated by the `CACHED` message in the console -output. (For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/): +output. (For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/)): ```console $ docker build -t svendowideit/ambassador . From 847f6d0731b6a92eee16a43405b98932d5701925 Mon Sep 17 00:00:00 2001 From: Stefan Scherer Date: Thu, 3 Sep 2020 16:21:22 +0200 Subject: [PATCH 151/152] Fix CMD --ignored-param1 example Co-authored-by: Sebastiaan van Stijn Signed-off-by: Stefan Scherer --- frontend/dockerfile/docs/reference.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 570589ac6..125fd1b53 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1632,7 +1632,7 @@ If you forget to add `exec` to the beginning of your `ENTRYPOINT`: ```dockerfile FROM ubuntu ENTRYPOINT top -b -CMD --ignored-param1 +CMD -- --ignored-param1 ``` You can then run it (giving it a name for the next step): @@ -1640,12 +1640,15 @@ You can then run it (giving it a name for the next step): ```console $ docker run -it --name test top --ignored-param2 -Mem: 1704184K used, 352484K free, 0K shrd, 0K buff, 140621524238337K cached -CPU: 9% usr 2% sys 0% nic 88% idle 0% io 0% irq 0% sirq -Load average: 0.01 0.02 0.05 2/101 7 - PID PPID USER STAT VSZ %VSZ %CPU COMMAND - 1 0 root S 3168 0% 0% /bin/sh -c top -b cmd cmd2 - 7 1 root R 3164 0% 0% top -b +top - 13:58:24 up 17 min, 0 users, load average: 0.00, 0.00, 0.00 +Tasks: 2 total, 1 running, 1 sleeping, 0 stopped, 0 zombie +%Cpu(s): 16.7 us, 33.3 sy, 0.0 ni, 50.0 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st +MiB Mem : 1990.8 total, 1354.6 free, 231.4 used, 404.7 buff/cache +MiB Swap: 1024.0 total, 1024.0 free, 0.0 used. 1639.8 avail Mem + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 2612 604 536 S 0.0 0.0 0:00.02 sh + 6 root 20 0 5956 3188 2768 R 0.0 0.2 0:00.00 top ``` You can see from the output of `top` that the specified `ENTRYPOINT` is not `PID 1`. @@ -1654,12 +1657,12 @@ If you then run `docker stop test`, the container will not exit cleanly - the `stop` command will be forced to send a `SIGKILL` after the timeout: ```console -$ docker exec -it test ps aux +$ docker exec -it test ps waux -PID USER COMMAND - 1 root /bin/sh -c top -b cmd cmd2 - 7 root top -b - 8 root ps aux +USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND +root 1 0.4 0.0 2612 604 pts/0 Ss+ 13:58 0:00 /bin/sh -c top -b --ignored-param2 +root 6 0.0 0.1 5956 3188 pts/0 S+ 13:58 0:00 top -b +root 7 0.0 0.1 5884 2816 pts/1 Rs+ 13:58 0:00 ps waux $ /usr/bin/time docker stop test From ccd4802295d67a1e34c0dc73bf02af6a46b6d964 Mon Sep 17 00:00:00 2001 From: CrazyMax Date: Wed, 22 Jun 2022 14:32:35 +0200 Subject: [PATCH 152/152] docs(dockerfile): fix links Signed-off-by: CrazyMax --- frontend/dockerfile/docs/reference.md | 24 +++++++----------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md index 125fd1b53..b03a038d9 100644 --- a/frontend/dockerfile/docs/reference.md +++ b/frontend/dockerfile/docs/reference.md @@ -1,21 +1,11 @@ --- title: Dockerfile reference description: "Dockerfiles use a simple DSL which allows you to automate the steps you would normally manually take to create an image." -keywords: "builder, docker, Dockerfile, automation, image creation" +keywords: "build, dockerfile, reference" redirect_from: - /reference/builder/ --- - - - Docker can build images automatically by reading the instructions from a `Dockerfile`. A `Dockerfile` is a text document that contains all the commands a user could call on the command line to assemble an image. Using `docker build` @@ -28,10 +18,10 @@ Practices](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-pr ## Usage -The [docker build](commandline/build.md) command builds an image from -a `Dockerfile` and a *context*. The build's context is the set of files at a -specified location `PATH` or `URL`. The `PATH` is a directory on your local -filesystem. The `URL` is a Git repository location. +The [docker build](https://docs.docker.com/engine/reference/commandline/build/) +command builds an image from a `Dockerfile` and a *context*. The build's context +is the set of files at a specified location `PATH` or `URL`. The `PATH` is a +directory on your local filesystem. The `URL` is a Git repository location. The build context is processed recursively. So, a `PATH` includes any subdirectories and the `URL` includes the repository and its submodules. This example shows a @@ -134,7 +124,7 @@ $ docker build -t svendowideit/ambassador . By default, the build cache is based on results from previous builds on the machine on which you are building. The `--cache-from` option also allows you to use a build-cache that's distributed through an image registry refer to the -[specifying external cache sources](commandline/build.md#specifying-external-cache-sources) +[specifying external cache sources](https://docs.docker.com/engine/reference/commandline/build/#specifying-external-cache-sources) section in the `docker build` command reference. When you're done with your build, you're ready to look into [scanning your image with `docker scan`](https://docs.docker.com/engine/scan/), @@ -1011,7 +1001,7 @@ the `-p` flag. For example $ docker run -p 80:80/tcp -p 80:80/udp ... ``` -To set up port redirection on the host system, see [using the -P flag](run.md#expose-incoming-ports). +To set up port redirection on the host system, see [using the -P flag](https://docs.docker.com/engine/reference/run/#expose-incoming-ports). The `docker network` command supports creating networks for communication among containers without the need to expose or publish specific ports, because the containers connected to the network can communicate with each other over any