From 950eccab4ad4d79a5afa154849567ddfdf8dc7eb Mon Sep 17 00:00:00 2001 From: Fred Lifton Date: Tue, 23 Sep 2014 18:26:02 -0700 Subject: [PATCH] Revisions and edits based on feedback. Docker-DCO-1.1-Signed-off-by: Fred Lifton (github: fredlf) --- .../articles/dockerfile_best-practices.md | 63 ++++++++++--------- docs/sources/docker-hub/official_repos.md | 14 +++-- 2 files changed, 44 insertions(+), 33 deletions(-) diff --git a/docs/sources/articles/dockerfile_best-practices.md b/docs/sources/articles/dockerfile_best-practices.md index 85bc5edff7..a837d1e002 100644 --- a/docs/sources/articles/dockerfile_best-practices.md +++ b/docs/sources/articles/dockerfile_best-practices.md @@ -14,9 +14,9 @@ specific set of instructions. You can learn the basics on the you’re new to writing `Dockerfile`s, you should start there. This document covers the best practices and methods recommended by Docker, -Inc., for creating easy-to-use, effective `Dockerfile`s. We strongly suggest -you follow these recommendations (in fact, if you’re creating an Official -Image, you *must* adhere to these practices). +Inc. and the Docker Community for creating easy-to-use, effective +`Dockerfile`s. We strongly suggest you follow these recommendations (in fact, +if you’re creating an Official Image, you *must* adhere to these practices). You can see many of these practices and recommendations in action in the [buildpack-deps `Dockerfile`](https://github.com/docker-library/buildpack-deps/blob/master/jessie/Dockerfile). @@ -34,10 +34,11 @@ set-up and configuration. ### Use a [`.dockerignore` file](https://docs.docker.com/reference/builder/#the-dockerignore-file) -For faster uploading and efficiency, you should make use of a `.dockerignore` -file to exclude files or directories from the build context. For example, unless -`.git` is needed by your build process or scripts, you should add it to -`.dockerignore`, which can save many megabytes worth of upload time. +For faster uploading and efficiency during `docker build`, you should make use +of a `.dockerignore` file to exclude files or directories from the build +context and final image. For example, unless`.git` is needed by your build +process or scripts, you should add it to `.dockerignore`, which can save many +megabytes worth of upload time. ### Avoid installing unnecessary packages @@ -95,14 +96,18 @@ backslashes. Probably the most common use-case for `RUN` is an application of `apt-get`. When using `apt-get`, here a few things to keep in mind: -* Don’t do simply `RUN apt-get update` on a single line. This will cause +* Don’t do `RUN apt-get update` on a single line. This will cause caching issues if the referenced archive gets updated, which will make your subsequent `apt-get install` fail without comment. * For the most part, to keep your code more readable and maintainable, avoid `RUN apt-get install -y package-foo && apt-get install -y package-bar`. -* Avoid `RUN apt-get upgrade` or `dist-upgrade`, since many of the “essential” packages from the base images will fail to upgrade inside an unprivileged container. If a base package is out of date, you should contact its maintainers. If you know there’s a particular package, `foo`, that needs to be updated, use `apt-get install -y foo` and it will update automatically. +* Avoid `RUN apt-get upgrade` or `dist-upgrade`, since many of the “essential” +packages from the base images will fail to upgrade inside an unprivileged +container. If a base package is out of date, you should contact its +maintainers. If you know there’s a particular package, `foo`, that needs to be +updated, use `apt-get install -y foo` and it will update automatically. * Do use `RUN apt-get update && apt-get install -y package-bar package-foo package-baz`. Writing the instruction this way not only makes it easier to read @@ -111,7 +116,7 @@ will naturally be busted and the latest versions will be installed with no further coding or manual intervention required. * Further natural cache-busting can be realized by version-pinning packages -(e.g., `package-foo=1.3.*`) since it will force retrieval of that version +(e.g., `package-foo=1.3.*`). This will force retrieval of that version regardless of what’s in the cache. Forming your `apt-get` code this way will greatly ease maintenance and reduce failures due to unanticipated changes in required packages. @@ -120,8 +125,9 @@ failures due to unanticipated changes in required packages. Below is a well-formed `RUN` instruction that demonstrates the above recommendations. Note that the last package, `s3cmd`, specifies a version -`1.1.0*`, which will bust the `apt-get` cache and force the installation of -that version (which in this case had a new, required feature). +`1.1.0*`. If the image previously used an older version, specifying the new one +will cause a cache bust of `apt-get update` and ensure the installation of +the new version (which in this case had a new, required feature). RUN apt-get update && apt-get install -y \ aufs-tools \ @@ -146,14 +152,14 @@ that version (which in this case had a new, required feature). ### [`CMD`](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 +image, along with any arguments. `CMD` should almost always be used in the form of `CMD [“executable”, “param1”, “param2”…]`. Thus, if the image is for a service (Apache, Rails, etc.), you would run something like `CMD ["apache2","-DFOREGROUND"]`. Indeed, this form of the instruction is recommended for any service-based image. In most other cases, `CMD` should be given an interactive shell (bash, python, -perl, etc). For example, `CMD ["perl", "-de0"]`, `CMD ["python"]`, or +perl, etc), for example, `CMD ["perl", "-de0"]`, `CMD ["python"]`, or `CMD [“php”, “-a”]`. Using this form means that when you execute something like `docker run -it python`, you’ll get dropped into a usable shell, ready to go. `CMD` should rarely be used in the manner of `CMD [“param”, “param”]` in @@ -163,11 +169,11 @@ works. ### [`EXPOSE`](https://docs.docker.com/reference/builder/#expose) -The `EXPOSE` instruction is the way you tell the users of your image where to -connect. Consequently, you should use the common, traditional port for your -application. For example, an image containing the Apache web server would use -`EXPOSE 80` while an image containing MongoDB would use `EXPOSE 27017` and so -on. +The `EXPOSE` instruction indicates the ports on which a container will listen +for connections. Consequently, you should use the common, traditional port for +your application. For example, an image containing the Apache web server would +use `EXPOSE 80`, while an image containing MongoDB would use `EXPOSE 27017` and +so on. For external access, your users can execute `docker run` with a flag indicating how to map the specified port to the port of their choice. @@ -207,9 +213,10 @@ not immediately obvious. Consequently, the best use for `ADD` is local tar file auto-extraction into the image, as in `ADD rootfs.tar.xz /`. Because image size matters, using `ADD` to fetch packages from remote URLs is -strongly discouraged; you should use `curl` or `wget` instead. That way you can, where possible, delete the files you no longer need after they’ve been -extracted without having to add another layer in your image. For example, you -should avoid doing things like: +strongly discouraged; you should use `curl` or `wget` instead. That way you can +delete the files you no longer need after they’ve been extracted and you won't +have to add another layer in your image. For example, you should avoid doing +things like: ADD http://example.com/big.tar.xz /usr/src/things/ RUN tar -xJf /usr/src/things/big.tar.xz -C /usr/src/things @@ -218,9 +225,9 @@ should avoid doing things like: And instead, do something like: RUN mdkir -p /usr/src/things \ - && curl -SL http://example.com/big.tar.gz \ - | tar -xJC /usr/src/things \ - && make -C /usr/src/things all + && curl -SL http://example.com/big.tar.gz \ + | tar -xJC /usr/src/things \ + && make -C /usr/src/things all For other items (files, directories) that do not require `ADD`’s tar auto-extraction capability, you should always use `COPY`. @@ -311,9 +318,9 @@ Images built from `ONBUILD` should get a separate tag, for example: `ruby:1.9-onbuild` or `ruby:2.0-onbuild`. Be careful when putting `ADD` or `COPY` in `ONBUILD`. The “onbuild” image will -fail catastrophically if it is missing the the resource being added. Adding a -separate tag, as recommended above, will help mitigate this by allowing the -`Dockerfile` author to make a choice. +fail catastrophically if the new build's context is missing the resource being +added. Adding a separate tag, as recommended above, will help mitigate this by +allowing the `Dockerfile` author to make a choice. ## Examples For Official Repositories diff --git a/docs/sources/docker-hub/official_repos.md b/docs/sources/docker-hub/official_repos.md index a6ed809f8e..b2ae9da9f1 100644 --- a/docs/sources/docker-hub/official_repos.md +++ b/docs/sources/docker-hub/official_repos.md @@ -8,7 +8,7 @@ page_keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub You’ve been given the job of creating an image for an Official Repository hosted on [Docker Hub Registry](https://registry.hub.docker.com/). These are -Docker, Inc.’s guidelines for getting that task done. Even if you’re not +our guidelines for getting that task done. Even if you’re not planning to create an Official Repo, you can think of these guidelines as best practices for image creation generally. @@ -91,11 +91,15 @@ In terms of content, the long description must include the following sections: * Issues & Contribution Info #### Overview & links -A section providing (a) an overview of the software contained in the image, -similar to the introduction in a Wikipedia entry and (b) a selection of links -to outside resources that help to describe the software. -This section *must* also include a link to the `Dockerfile`. +This section should provide: + +* an overview of the software contained in the image, similar to the +introduction in a Wikipedia entry, + +* a selection of links to outside resources that help to describe the software, + +* a *mandatory* link to the `Dockerfile`. #### How-to/usage A section that describes how to run and use the image, including common use