Add note about host-dir in VOLUME
(cherry picked from commit f2fff9d913a8ab0436dd56033189a7c3713a59a2)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
(cherry picked from commit 8fd6547fc3eb67e7efa7efb007ae6a4494cd2bb3)
Signed-off-by: Tibor Vass <tibor@docker.com>
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 <dnephin@docker.com>
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 <dt@docker.com>
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 <remy.suen@gmail.com>
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 <admwiggin@gmail.com>
Signed-off-by: John Howard <jhoward@microsoft.com>
Working directory processing was handled differently for Hyper-V and Windows-Server containers, as annotated in the builder documentation (updated in this PR). For Hyper-V containers, the working directory set by WORKDIR was not created. This PR makes Hyper-V containers work the same as Windows Server containers (and the same as Linux).
Example (only applies to Hyper-V containers, so not reproducible under CI environment)
Dockerfile:
FROM microsoft/nanoserver
WORKDIR c:\installer
ENV GOROOT=c:\installer
ADD go.exe .
RUN go --help
Running on Windows Server 2016, using docker master without this change, but with daemon set to --exec-opt isolation=hyperv as it would be for Client operating systems.
PS E:\go\src\github.com\docker\docker> dockerd -g c:\control --exec-opt isolation=hyperv
time="2017-02-01T15:48:09.657286100-08:00" level=info msg="Windows default isolation mode: hyperv"
time="2017-02-01T15:48:09.662720900-08:00" level=info msg="[graphdriver] using prior storage driver: windowsfilter"
time="2017-02-01T15:48:10.011588000-08:00" level=info msg="Graph migration to content-addressability took 0.00 seconds"
time="2017-02-01T15:48:10.016655800-08:00" level=info msg="Loading containers: start."
time="2017-02-01T15:48:10.460820000-08:00" level=info msg="Loading containers: done."
time="2017-02-01T15:48:10.509859600-08:00" level=info msg="Daemon has completed initialization"
time="2017-02-01T15:48:10.509859600-08:00" level=info msg="Docker daemon" commit=3c64061 graphdriver=windowsfilter version=1.14.0-dev
First with no explicit isolation:
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
---> 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>
PR 24978 adds hint of of progress to the output of `docker build`
for 1.13, in the format of
```
Step 1/5 ...
...
Step 2/5 ...
...
```
Though some of the docs hasn't been updated.
This fix did a grep in docs and updated the related places.
Signed-off-by: Yong Tang <yong.tang.github@outlook.com>
Some frontmatter such as the weights, menu stuff, etc is no longer used
'draft=true' becomes 'published: false'
Signed-off-by: Misty Stanley-Jones <misty@docker.com>
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 <yong.tang.github@outlook.com>
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 <dooling@gmail.com>
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 <justin.cormack@docker.com>
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 <yong.tang.github@outlook.com>
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 <dooling@gmail.com>
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 <dooling@gmail.com>
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 <tibor@docker.com>
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 <github@gone.nl>
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.
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 <serhat+signoff@equil.nl>
fixing links after moving surfacing tutorials
fixing more links for the newly located tutorials
Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>
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 <yong.tang.github@outlook.com>
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 <thomas.leonard@docker.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
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 <kevin.m.meredith@gmail.com>
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 <riccardi@systran.fr>
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 <mary@docker.com>
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 <mary@docker.com>
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 <mary@docker.com>
- 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 <madhav.puri@gmail.com>
- 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 <mary@docker.com>
* 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 <charleswhchan@users.noreply.github.com>
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 <tim.wraight@tangentlabs.co.uk>
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 <mary@docker.com>
Sebastiaan van Stijn
Slava Semushin
Sebastiaan van Stijn
Tõnis Tiigi
Daniel Nephin
Elias Faxö
Foysal Iqbal
John Maguire
Dave Tucker
Remy Suen
Tianon Gravi
John Howard
John Mulhausen
jroenf
Michael Friis
Victor Vieux
liwenqi
Yong Tang
Gaetan de Villele
Addam Hardy
Qiang Huang
lixiaobing10051267
Misty Stanley-Jones
Ding Fei
David Dooling
Justin Cormack
Kris-Mikael Krister
Mihai Borobocea
Tibor Vass
Dave Henderson
Otto Kekäläinen
Serhat Gülçiçek
Victoria Bialas
Kevin Burke
Thomas Leonard
Charles Law
kevinmeredith
Thomas Riccardi
mikelinjie
Sven Dowideit
Tomasz Kopczynski
Bastiaan Bakker
Victor Vieux
Prayag Verma
Mary Anthony
Doug Davis
Aidan Hobson Sayers
Shijiang Wei
Mike Brown
Grant Reaber
Charles Chan
Tim Waugh
Madhav Puri
Amen Belayneh
David Calavera
bin liu
Morgan Bauer
Patrick Hemmer
Dharmit Shah
Ankush Agarwal
John Tims
jgeiger
Tim Wraight
Chris McKinnel