From d03923732f36628f1897c03d5cba7653f156c5c2 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Mon, 13 Jul 2015 13:11:36 +0200 Subject: [PATCH] Fixes TOC in dockerfile_best_practices.md Decided to put the link in a reference word. Closes #14573 Signed-off-by: Vincent Demeester --- docs/articles/dockerfile_best-practices.md | 51 ++++++++++++++++------ 1 file changed, 37 insertions(+), 14 deletions(-) diff --git a/docs/articles/dockerfile_best-practices.md b/docs/articles/dockerfile_best-practices.md index 19d4fc41c8..d97d280a6a 100644 --- a/docs/articles/dockerfile_best-practices.md +++ b/docs/articles/dockerfile_best-practices.md @@ -126,14 +126,18 @@ generate new images and the cache will not be used. Below you'll find recommendations for the best way to write the various instructions available for use in a `Dockerfile`. -### [`FROM`](https://docs.docker.com/reference/builder/#from) +### FROM + +[Dockerfile reference for the FROM instruction](https://docs.docker.com/reference/builder/#from) Whenever possible, use current Official Repositories as the basis for your image. We recommend the [Debian image](https://registry.hub.docker.com/_/debian/) since it’s very tightly controlled and kept extremely minimal (currently under 100 mb), while still being a full distribution. -### [`RUN`](https://docs.docker.com/reference/builder/#run) +### RUN + +[Dockerfile reference for the RUN instruction](https://docs.docker.com/reference/builder/#run) As always, to make your `Dockerfile` more readable, understandable, and maintainable, put long or complex `RUN` statements on multiple lines separated @@ -199,8 +203,10 @@ Writing the instruction this way also helps you avoid potential duplication of a given package because it is much easier to read than an instruction like: RUN apt-get install -y package-foo && apt-get install -y package-bar - -### [`CMD`](https://docs.docker.com/reference/builder/#cmd) + +### CMD + +[Dockerfile reference for the CMD instruction](https://docs.docker.com/reference/builder/#cmd) The `CMD` instruction should be used to run the software contained by your image, along with any arguments. `CMD` should almost always be used in the @@ -218,7 +224,9 @@ conjunction with [`ENTRYPOINT`](https://docs.docker.com/reference/builder/#entry you and your expected users are already quite familiar with how `ENTRYPOINT` works. -### [`EXPOSE`](https://docs.docker.com/reference/builder/#expose) +### EXPOSE + +[Dockerfile reference for the EXPOSE instruction](https://docs.docker.com/reference/builder/#expose) The `EXPOSE` instruction indicates the ports on which a container will listen for connections. Consequently, you should use the common, traditional port for @@ -231,7 +239,9 @@ how to map the specified port to the port of their choice. For container linking, Docker provides environment variables for the path from the recipient container back to the source (ie, `MYSQL_PORT_3306_TCP`). -### [`ENV`](https://docs.docker.com/reference/builder/#env) +### ENV + +[Dockerfile reference for the ENV instruction](https://docs.docker.com/reference/builder/#env) In order to make new software easier to run, you can use `ENV` to update the `PATH` environment variable for the software your container installs. For @@ -254,7 +264,10 @@ Similar to having constant variables in a program (as opposed to hard-coding values), this approach lets you change a single `ENV` instruction to auto-magically bump the version of the software in your container. -### [`ADD`](https://docs.docker.com/reference/builder/#add) or [`COPY`](https://docs.docker.com/reference/builder/#copy) +### ADD or COPY + +[Dockerfile reference for the ADD instruction](https://docs.docker.com/reference/builder/#add)
+[Dockerfile reference for the COPY instruction](https://docs.docker.com/reference/builder/#copy) Although `ADD` and `COPY` are functionally similar, generally speaking, `COPY` is preferred. That’s because it’s more transparent than `ADD`. `COPY` only @@ -297,7 +310,9 @@ And instead, do something like: For other items (files, directories) that do not require `ADD`’s tar auto-extraction capability, you should always use `COPY`. -### [`ENTRYPOINT`](https://docs.docker.com/reference/builder/#entrypoint) +### ENTRYPOINT + +[Dockerfile reference for the ENTRYPOINT instruction](https://docs.docker.com/reference/builder/#entrypoint) The best use for `ENTRYPOINT` is to set the image's main command, allowing that image to be run as though it was that command (and then use `CMD` as the @@ -347,7 +362,7 @@ exec "$@" > This script uses [the `exec` Bash command](http://wiki.bash-hackers.org/commands/builtin/exec) > so that the final running application becomes the container's PID 1. This allows > the application to receive any Unix signals sent to the container. -> See the [`ENTRYPOINT`](https://docs.docker.com/reference/builder/#ENTRYPOINT) +> See the [`ENTRYPOINT`](https://docs.docker.com/reference/builder/#entrypoint) > help for more details. @@ -371,14 +386,18 @@ Lastly, it could also be used to start a totally different tool, such Bash: $ docker run --rm -it postgres bash -### [`VOLUME`](https://docs.docker.com/reference/builder/#volume) +### VOLUME + +[Dockerfile reference for the VOLUME instruction](https://docs.docker.com/reference/builder/#volume) The `VOLUME` instruction should be used to expose any database storage area, configuration storage, or files/folders created by your docker container. You are strongly encouraged to use `VOLUME` for any mutable and/or user-serviceable parts of your image. -### [`USER`](https://docs.docker.com/reference/builder/#user) +### USER + +[Dockerfile reference for the USER instruction](https://docs.docker.com/reference/builder/#user) If a service can run without privileges, use `USER` to change to a non-root user. Start by creating the user and group in the `Dockerfile` with something @@ -397,14 +416,18 @@ daemon as root but running it as non-root), you may be able to use Lastly, to reduce layers and complexity, avoid switching `USER` back and forth frequently. -### [`WORKDIR`](https://docs.docker.com/reference/builder/#workdir) +### WORKDIR + +[Dockerfile reference for the WORKDIR instruction](https://docs.docker.com/reference/builder/#workdir) For clarity and reliability, you should always use absolute paths for your `WORKDIR`. Also, you should use `WORKDIR` instead of proliferating instructions like `RUN cd … && do-something`, which are hard to read, troubleshoot, and maintain. -### [`ONBUILD`](https://docs.docker.com/reference/builder/#onbuild) +### ONBUILD + +[Dockerfile reference for the ONBUILD instruction](https://docs.docker.com/reference/builder/#onbuild) An `ONBUILD` command executes after the current `Dockerfile` build completes. `ONBUILD` executes in any child image derived `FROM` the current image. Think @@ -438,7 +461,7 @@ These Official Repositories have exemplary `Dockerfile`s: ## Additional resources: -* [Dockerfile Reference](https://docs.docker.com/reference/builder/#onbuild) +* [Dockerfile Reference](https://docs.docker.com/reference/builder/) * [More about Base Images](https://docs.docker.com/articles/baseimages/) * [More about Automated Builds](https://docs.docker.com/docker-hub/builds/) * [Guidelines for Creating Official