Commit Graph

114 Commits

Author SHA1 Message Date
Tõnis Tiigi 1a8bdcd36f Implement build cache based on history array
Based on work by KJ Tsanaktsidis

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>
Signed-off-by: KJ Tsanaktsidis <kjtsanaktsidis@gmail.com>
2017-06-02 00:10:11 +00:00
Yong Tang 4785157d54 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 <yong.tang.github@outlook.com>
2017-06-02 00:10:11 +00:00
David Dooling e1a8e15e8d 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 <dooling@gmail.com>
2017-06-02 00:10:09 +00:00
Justin Cormack 62f35ffbdc 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 <justin.cormack@docker.com>
2017-06-02 00:10:09 +00:00
Yong Tang 98043e3f79 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 <yong.tang.github@outlook.com>
2017-06-02 00:10:09 +00:00
Kris-Mikael Krister 8918ff39e2 Fix typo in builder.md
Signed-off-by: Kris-Mikael Krister <krismikael@protonmail.com>
2017-06-02 00:10:07 +00:00
David Dooling e6c152e5ee 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 <dooling@gmail.com>
2017-06-02 00:10:06 +00:00
David Dooling 2b84c776d0 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 <dooling@gmail.com>
2017-06-02 00:10:06 +00:00
Mihai Borobocea 6132c35c04 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 <MihaiBorob@gmail.com>
2017-06-02 00:10:06 +00:00
Tibor Vass fa9465f093 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 <tibor@docker.com>
2017-06-02 00:10:02 +00:00
Sebastiaan van Stijn b41c0c8696 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 <github@gone.nl>
2017-06-02 00:07:50 +00:00
Dave Henderson e8b87f53ec Clarify warning against using build-time variables for secrets
Signed-off-by: Dave Henderson <dhenderson@gmail.com>
2017-06-02 00:07:49 +00:00
Otto Kekäläinen 8e2c3efc58 Fix spelling in comments, strings and documentation
Signed-off-by: Otto Kekäläinen <otto@seravo.fi>
2017-06-02 00:07:48 +00:00
Serhat Gülçiçek beb09f42d6 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.

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>
2017-06-02 00:07:47 +00:00
Victoria Bialas d3b7a2779e 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 <victoria.bialas@docker.com>
2017-06-02 00:07:43 +00:00
Kevin Burke 26fdf31cf8 typo in builder.md: its => it's
Signed-off-by: Kevin Burke <kev@inburke.com>
2017-06-02 00:07:43 +00:00
John Howard 0cb3440a21 Builder default shell
Signed-off-by: John Howard <jhoward@microsoft.com>
2017-06-02 00:07:41 +00:00
Sebastiaan van Stijn 7e00f19c4f Healthcheck: set default retries to 3
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2017-06-02 00:07:41 +00:00
Yong Tang 1a22098ae2 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 <yong.tang.github@outlook.com>
2017-06-02 00:07:41 +00:00
Thomas Leonard 51ddea93a2 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 <thomas.leonard@docker.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2017-06-02 00:07:41 +00:00
John Howard 1bc54f3466 Support platform file paths through escape
Signed-off-by: John Howard <jhoward@microsoft.com>
2017-06-02 00:07:40 +00:00
John Howard 560134b63a Docs: JSON vs Shell clarification
Signed-off-by: John Howard <jhoward@microsoft.com>
2017-06-02 00:07:39 +00:00
Charles Law cf70da5d08 Fix error for env variables example in docker reference
Signed-off-by: Charles Law <claw@conduce.com>
2017-06-02 00:07:38 +00:00
kevinmeredith a8e16c0079 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 <kevin.m.meredith@gmail.com>
2017-06-02 00:07:38 +00:00
Thomas Riccardi 6ded7e8279 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 <riccardi@systran.fr>
2017-06-02 00:07:36 +00:00
mikelinjie bc060f1f19 make the cache miss clear
Signed-off-by: mikelinjie <294893458@qq.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2017-06-02 00:07:35 +00:00
Sven Dowideit 80f5ed58a5 WORKDIR is like calling mkdir - but we've not told people
Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au>
2017-06-02 00:07:33 +00:00
Tomasz Kopczynski a429c0e84f Docs: add note about CMD and ENTRYPOINT commands
Signed-off-by: Tomasz Kopczynski <tomek@kopczynski.net.pl>
2017-06-02 00:07:30 +00:00
Bastiaan Bakker e56ee5769c add missing trailing slash in ADD and COPY /absoluteDir examples. According to the specs they are mandatory.
Signed-off-by: Bastiaan Bakker <bbakker@xebia.com>
2017-06-02 00:07:29 +00:00
Victor Vieux c30d9d2fff fix common misspell
Signed-off-by: Victor Vieux <vieux@docker.com>
2017-06-02 00:07:28 +00:00
Prayag Verma 6f24713ba0 Fix typo
Signed-off-by: Prayag Verma <prayag.verma@gmail.com>
2017-06-02 00:07:27 +00:00
Mary Anthony 7910f01804 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 <mary@docker.com>
2017-06-02 00:07:26 +00:00
Doug Davis fc57c3a419 Add some helper text for magical ADD
Closes: #15777

Signed-off-by: Doug Davis <dug@us.ibm.com>
2017-06-02 00:07:25 +00:00
Aidan Hobson Sayers 5142d3a669 Fix ambassador script based on SvenDowideit/dockerfiles#37
Signed-off-by: Aidan Hobson Sayers <aidanhs@cantab.net>
2017-06-02 00:07:23 +00:00
Doug Davis ec3aa7ede2 Add some docs about build-arg's impact on the cache
Closes #18017

Signed-off-by: Doug Davis <dug@us.ibm.com>
2017-06-02 00:07:18 +00:00
Sven Dowideit d63c19c4ea Fixes found by docs validation tool
Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au>
2017-06-02 00:07:18 +00:00
Doug Davis 4978171903 Support multi-dir wildcards in .dockerignore
Closes #13113

Signed-off-by: Doug Davis <dug@us.ibm.com>
2017-06-02 00:07:17 +00:00
Mary Anthony 02a859b9f3 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 <mary@docker.com>
2017-06-02 00:07:15 +00:00
Shijiang Wei 9d9976ae3a Add ability to add multiple tags with docker build
Signed-off-by: Shijiang Wei <mountkin@gmail.com>
2017-06-02 00:07:14 +00:00
Aidan Hobson Sayers edbb82c900 Update ambassador image, use the socat -t option
Signed-off-by: Aidan Hobson Sayers <aidanhs@cantab.net>
2017-06-02 00:07:14 +00:00
Mike Brown d83594a46d updating docs for EXPOSE option on run command; fixes #16634
Signed-off-by: Mike Brown <brownwm@us.ibm.com>
2017-06-02 00:07:12 +00:00
Mary Anthony e641a0f363 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 <mary@docker.com>
2017-06-02 00:07:12 +00:00
Grant Reaber 42fe72228d clarify dockerignore semantics
Signed-off-by: Grant Reaber <grant.reaber@gmail.com>
2017-06-02 00:07:11 +00:00
Aidan Hobson Sayers d86cfdfb84 Mention more realistic examples are available
Signed-off-by: Aidan Hobson Sayers <aidanhs@cantab.net>
2017-06-02 00:07:11 +00:00
Aidan Hobson Sayers 090ad2bb8a Don't put dockerfiles in one continuous code block
Signed-off-by: Aidan Hobson Sayers <aidanhs@cantab.net>
2017-06-02 00:07:11 +00:00
Charles Chan 0039e46e3e 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 <charleswhchan@users.noreply.github.com>
2017-06-02 00:07:10 +00:00
Tim Waugh a8db81a89a Add documentation note that LABEL allows environment replacement
Signed-off-by: Tim Waugh <twaugh@redhat.com>
2017-06-02 00:07:10 +00:00
Madhav Puri 9fab23902f incorporate doc review comments
Signed-off-by: Madhav Puri <madhav.puri@gmail.com>
2017-06-02 00:07:09 +00:00
Madhav Puri 40a2dac738 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 <madhav.puri@gmail.com>
2017-06-02 00:07:09 +00:00
Amen Belayneh 8ff51d3827 update documentation styling as per suggestions
Signed-off-by: Amen Belayneh <amenbelayneh@gmail.com>
2017-06-02 00:07:09 +00:00
Amen Belayneh 0ece7ed9d4 add a documentation note on backslash usage in shell form of RUN
Signed-off-by: Amen Belayneh <amenbelayneh@gmail.com>
2017-06-02 00:07:09 +00:00
David Calavera f5b80326a1 Add `STOPSIGNAL` instruction to dockerfiles.
This way, images creators can set the exit signal their programs use.

Signed-off-by: David Calavera <david.calavera@gmail.com>
2017-06-02 00:07:08 +00:00
bin liu 08481e81ca add missing instruction
Signed-off-by: bin liu <liubin0329@gmail.com>
2017-06-02 00:07:06 +00:00
Morgan Bauer e0d42a679c 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 <mary@docker.com>
2017-06-02 00:07:06 +00:00
Mary Anthony 58a37fe8cf Updating hashcode links to commands
Signed-off-by: Mary Anthony <mary@docker.com>
2017-06-02 00:07:06 +00:00
Patrick Hemmer d3dae7f652 add documentation clarifying behavior of VOLUME instruction
Signed-off-by: Patrick Hemmer <patrick.hemmer@gmail.com>
2017-06-02 00:07:05 +00:00
Dharmit Shah 56632110e0 Fixing docs to remove references to links under terms/
Removed terms/ directory

Signed-off-by: Dharmit Shah <shahdharmit@gmail.com>
2017-06-02 00:07:05 +00:00
Ankush Agarwal 66516a7ec3 Remove note from docker version 1.3 on Env variables
Fixes #14734

Signed-off-by: Ankush Agarwal <ankushagarwal11@gmail.com>
2017-06-02 00:07:05 +00:00
Charles Chan 8a1164778d 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 <charleswhchan@users.noreply.github.com>
2017-06-02 00:07:03 +00:00
John Tims ec19c839c6 Fix typo
Signed-off-by: John Tims <john.k.tims@gmail.com>
2017-06-02 00:07:03 +00:00
jgeiger 21ba115188 Fix typo in builder.mb .dockerignore example
Signed-off-by: jgeiger <jgeiger@gmail.com>
2017-06-02 00:07:02 +00:00
Tim Wraight 85ff60eb74 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 <tim.wraight@tangentlabs.co.uk>
2017-06-02 00:07:00 +00:00
Chris McKinnel c4541d3793 Fix a broken anchor tag on the CLI builder page
Signed-off-by: Chris McKinnel <chrismckinnel@gmail.com>
2017-06-02 00:07:00 +00:00
Mary Anthony d1d033701e 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 <mary@docker.com>
2017-06-02 00:06:58 +00:00
Renamed from docs/sources/reference/builder.md (Browse further)