From 58e89878374d12c916fa9e2b5436f5e042bc6978 Mon Sep 17 00:00:00 2001 From: Fred Lifton Date: Thu, 4 Sep 2014 18:09:00 -0700 Subject: [PATCH 01/10] Adding first draft of Official Repo Guidelines Docker-DCO-1.1-Signed-off-by: Fred Lifton (github: fredlf) --- docs/mkdocs.yml | 1 + docs/sources/docker-hub/official_repos.md | 175 ++++++++++++++++++++++ 2 files changed, 176 insertions(+) create mode 100644 docs/sources/docker-hub/official_repos.md diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 491f00c35f..f620030713 100755 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -65,6 +65,7 @@ pages: - ['docker-hub/accounts.md', 'Docker Hub', 'Accounts'] - ['docker-hub/repos.md', 'Docker Hub', 'Repositories'] - ['docker-hub/builds.md', 'Docker Hub', 'Automated Builds'] +- ['docker-hub/official_repos.md', 'Docker Hub', 'Official Repo Guidelines'] # Examples: - ['examples/index.md', '**HIDDEN**'] diff --git a/docs/sources/docker-hub/official_repos.md b/docs/sources/docker-hub/official_repos.md new file mode 100644 index 0000000000..07e584cc23 --- /dev/null +++ b/docs/sources/docker-hub/official_repos.md @@ -0,0 +1,175 @@ +page_title: Guidelines for Official Repositories on Docker Hub +page_description: Guidelines for Official Repositories on Docker Hub +page_keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, official, image, documentation + +## Introduction + +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 planning to create an Official +Repo, you can think of these guidelines as best practices for image creation generally. + +This document consists of three major sections: +* Expected files, resources and supporting items for your image +* Examples embodying those practices +* Instructions for submitting your work + +## Expected Files & Resources + +### A Git repository + +Your image needs to live in a Git repository, preferably on GitHub. (If you’d like to use +a different provider, please [contact us](TODO: link) directly.) Docker **strongly** +recommends that this repo be publicly accessible. + +If the repo is private or has otherwise limited access, you must provide a means of at +least “read-only” access for both general users and for the docker-library maintainers, +who need access for review and building purposes. + +### A `Dockerfile` + +Complete information on `Dockerfile`s can be found in the [Reference section](https://docs.docker.com/reference/builder/). +We also have a page discussing best practices for writing `Dockerfile`s (TODO: link). +Your `Dockerfile` should adhere to the following: + +* It must be written either by using `FROM scratch` or be based on another, established +Official Image. +* It must follow `Dockerfile` best practices. These are discussed in the [Best Practices +document](TODO: link). In addition, Docker, Inc. engineer Michael Crosby has a good +discussion of Dockerfiles in this [blog post](http://crosbymichael.com/dockerfile-best-practices-take-2.html). + +While [ONBUILD triggers](https://docs.docker.com/reference/builder/#onbuild) are not +required, if you choose to use them you should: +* Build both `ONBUILD` and non-`ONBUILD` images, with the `ONBUILD` image built `FROM` +the non-`ONBUILD` image. +* The `ONBUILD` image should be specifically tagged, for example, `ruby:latest` and +`ruby:onbuild`, or `ruby:2` and `ruby:2-onbuild`. + +### A short description + +Include a brief description of your image (in plaintext). Only one description is +required; you don’t need additional descriptions for each tag. The file should also: + +* Be named `README-short.txt` +* Reside in the repo for the “latest” tag +* Not exceed 200 characters. + +### A logo + +Include a logo of your company or the product (png format preferred). Only one logo is +required; you don’t need additional logo files for each tag. The logo file should have +the following characteristics: + +* Be named `logo.png` +* Should reside in the repo for the “latest” tag +* Should be 200px min. in one dimension, 200px max. in the other. +* Square or wide (landscape) is preferred over tall (portrait), but exceptions can be +made based on the logo needed. + +### A long description + +Include a comprehensive description of your image (in markdown format). Only one +description is required; you don’t need additional descriptions for each tag. The file +should also: + +* Be named `README.md` +* Reside in the repo for the “latest” tag +* Be no longer than absolutely necessary, while still addressing all the content +requirements. + +In terms of content, the long description must include the following sections: + +* Overview & Links +* How-to/Usage +* User Feedback +* License + +#### 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. + +#### How-to/usage + +A section that describes how to run and use the image, including common use cases and +example `Dockerfile`s (if applicable). Try to provide clear, step-by-step instructions +wherever possible. + +#### User Feedback + +This section should have two parts, one explaining how users can contribute to the repo +and one explaining how to report issues with the repo. + +##### Contributing + +In this part, point users to any resources that can help them contribute to the project. +Include contribution guidelines and any specific instructions related to your development +practices. Include a link to [Docker’s resources for contributors](https://docs.docker.com/contributing/contributing/). +Be sure to include contact info, handles, etc. for official maintainers. + +##### Issues + +Include a brief section letting users know where they can go for help and how they can +file issues with the repo. Point them to any specific IRC channels, issue trackers, +contacts, additional “how-to” information or other resources. + +#### License + +Include a copy of any applicable license. Docker recommends using the license of the +software contained in the image, provided it allows Docker, Inc. to legally build and +distribute the image. Otherwise Docker recommends adopting the [Apache license](https://github.com/docker/docker/blob/master/LICENSE). + +## Example + +Below are sample short and long description files for an imaginary image containing +Ruby on Rails. + +### Short description + +> **README-short.txt** +> +> Ruby on Rails is an open-source application framework written in Ruby. It emphasizes best +>practices such as convention over configuration, active record pattern, and the model- +>view-controller pattern. + +### Long description + +> **README.md** +> # What is Ruby on Rails +> +> Ruby on Rails, often simply referred to as Rails, is an open source web application +> framework which runs via the Ruby programming language. It is a full-stack framework: +> it allows creating pages and applications that gather information from the web server, +> talk to or query the database, and render templates out of the box. As a result, Rails +>features a routing system that is independent of the web server. +> +> [wikipedia.org/wiki/Ruby_on_Rails](https://en.wikipedia.org/wiki/Ruby_on_Rails) +> +#### How to use this image + +> 1. create a `Dockerfile` in your rails app project + + FROM rails:onbuild +> +> Put this file in the root of your app, next to the `Gemfile`. + +> This image includes multiple `ONBUILD` triggers so that should be all that you need for +> most applications. The build will `ADD . /usr/src/app`, `RUN bundle install`, +>`EXPOSE 3000`, and set the default command to `rails server`. +> +> 2. build the rails app image +> +> docker build -t my-rails-app . + +> 3. start the rails app container +> +> docker run --name some-rails-app -d my-rails-app +> +> Then go to `http://container-ip:3000` in a browser. On the other hand, if you need access +> outside the host on port 8080: +> +> docker run --name some-rails-app -p 8080:3000 -d my-rails-app +> +> Then go to `http://localhost:8080` or `http://host-ip:8080` in a browser. + From eb8d0c1ccffe612f2c017871d5b8b39320256c6f Mon Sep 17 00:00:00 2001 From: Fred Lifton Date: Mon, 8 Sep 2014 11:43:09 -0700 Subject: [PATCH 02/10] Revisions based on feedback. Docker-DCO-1.1-Signed-off-by: Fred Lifton (github: fredlf) --- docs/sources/docker-hub/official_repos.md | 122 +++++++++++----------- 1 file changed, 62 insertions(+), 60 deletions(-) diff --git a/docs/sources/docker-hub/official_repos.md b/docs/sources/docker-hub/official_repos.md index 07e584cc23..a8ee135e01 100644 --- a/docs/sources/docker-hub/official_repos.md +++ b/docs/sources/docker-hub/official_repos.md @@ -2,7 +2,7 @@ page_title: Guidelines for Official Repositories on Docker Hub page_description: Guidelines for Official Repositories on Docker Hub page_keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, official, image, documentation -## Introduction +# Introduction 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 @@ -10,13 +10,14 @@ guidelines for getting that task done. Even if you’re not planning to create a Repo, you can think of these guidelines as best practices for image creation generally. This document consists of three major sections: + * Expected files, resources and supporting items for your image * Examples embodying those practices -* Instructions for submitting your work +* Instructions for submitting contributions and reporting issues -## Expected Files & Resources +# Expected Files & Resources -### A Git repository +## A Git repository Your image needs to live in a Git repository, preferably on GitHub. (If you’d like to use a different provider, please [contact us](TODO: link) directly.) Docker **strongly** @@ -26,7 +27,7 @@ If the repo is private or has otherwise limited access, you must provide a means least “read-only” access for both general users and for the docker-library maintainers, who need access for review and building purposes. -### A `Dockerfile` +## A `Dockerfile` Complete information on `Dockerfile`s can be found in the [Reference section](https://docs.docker.com/reference/builder/). We also have a page discussing best practices for writing `Dockerfile`s (TODO: link). @@ -45,7 +46,7 @@ the non-`ONBUILD` image. * The `ONBUILD` image should be specifically tagged, for example, `ruby:latest` and `ruby:onbuild`, or `ruby:2` and `ruby:2-onbuild`. -### A short description +## A short description Include a brief description of your image (in plaintext). Only one description is required; you don’t need additional descriptions for each tag. The file should also: @@ -54,7 +55,7 @@ required; you don’t need additional descriptions for each tag. The file should * Reside in the repo for the “latest” tag * Not exceed 200 characters. -### A logo +## A logo Include a logo of your company or the product (png format preferred). Only one logo is required; you don’t need additional logo files for each tag. The logo file should have @@ -66,7 +67,7 @@ the following characteristics: * Square or wide (landscape) is preferred over tall (portrait), but exceptions can be made based on the logo needed. -### A long description +## A long description Include a comprehensive description of your image (in markdown format). Only one description is required; you don’t need additional descriptions for each tag. The file @@ -84,92 +85,93 @@ In terms of content, the long description must include the following sections: * User Feedback * License -#### Overview & links +### 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. -#### How-to/usage +### How-to/usage A section that describes how to run and use the image, including common use cases and example `Dockerfile`s (if applicable). Try to provide clear, step-by-step instructions wherever possible. -#### User Feedback +### User Feedback This section should have two parts, one explaining how users can contribute to the repo and one explaining how to report issues with the repo. -##### Contributing +#### Contributing In this part, point users to any resources that can help them contribute to the project. Include contribution guidelines and any specific instructions related to your development practices. Include a link to [Docker’s resources for contributors](https://docs.docker.com/contributing/contributing/). Be sure to include contact info, handles, etc. for official maintainers. -##### Issues +#### Issues Include a brief section letting users know where they can go for help and how they can file issues with the repo. Point them to any specific IRC channels, issue trackers, contacts, additional “how-to” information or other resources. -#### License +## License -Include a copy of any applicable license. Docker recommends using the license of the -software contained in the image, provided it allows Docker, Inc. to legally build and -distribute the image. Otherwise Docker recommends adopting the [Apache license](https://github.com/docker/docker/blob/master/LICENSE). +Include a file, (`LICENSE`), of any applicable license. Docker recommends using the +license of the software contained in the image, provided it allows Docker, Inc. to +legally build and distribute the image. Otherwise Docker recommends adopting the +[Expat license]((http://directory.fsf.org/wiki/License:Expat). -## Example +# Examples Below are sample short and long description files for an imaginary image containing Ruby on Rails. -### Short description +## Short description -> **README-short.txt** -> -> Ruby on Rails is an open-source application framework written in Ruby. It emphasizes best ->practices such as convention over configuration, active record pattern, and the model- ->view-controller pattern. + **README-short.txt** + + Ruby on Rails is an open-source application framework written in Ruby. It emphasizes + best practices such as convention over configuration, active record pattern, and the + model-view-controller pattern. -### Long description - -> **README.md** -> # What is Ruby on Rails -> -> Ruby on Rails, often simply referred to as Rails, is an open source web application -> framework which runs via the Ruby programming language. It is a full-stack framework: -> it allows creating pages and applications that gather information from the web server, -> talk to or query the database, and render templates out of the box. As a result, Rails ->features a routing system that is independent of the web server. -> -> [wikipedia.org/wiki/Ruby_on_Rails](https://en.wikipedia.org/wiki/Ruby_on_Rails) -> -#### How to use this image - -> 1. create a `Dockerfile` in your rails app project +## Long description + **README.md** + # What is Ruby on Rails + + Ruby on Rails, often simply referred to as Rails, is an open source web application + framework which runs via the Ruby programming language. It is a full-stack framework: + it allows creating pages and applications that gather information from the web server, + talk to or query the database, and render templates out of the box. As a result, Rails + features a routing system that is independent of the web server. + + [wikipedia.org/wiki/Ruby_on_Rails](https://en.wikipedia.org/wiki/Ruby_on_Rails) + + **How to use this image** + + 1. create a `Dockerfile` in your rails app project + FROM rails:onbuild -> -> Put this file in the root of your app, next to the `Gemfile`. + + Put this file in the root of your app, next to the `Gemfile`. -> This image includes multiple `ONBUILD` triggers so that should be all that you need for -> most applications. The build will `ADD . /usr/src/app`, `RUN bundle install`, ->`EXPOSE 3000`, and set the default command to `rails server`. -> -> 2. build the rails app image -> -> docker build -t my-rails-app . - -> 3. start the rails app container -> -> docker run --name some-rails-app -d my-rails-app -> -> Then go to `http://container-ip:3000` in a browser. On the other hand, if you need access -> outside the host on port 8080: -> -> docker run --name some-rails-app -p 8080:3000 -d my-rails-app -> -> Then go to `http://localhost:8080` or `http://host-ip:8080` in a browser. + This image includes multiple `ONBUILD` triggers so that should be all that you need + for most applications. The build will `ADD . /usr/src/app`, `RUN bundle install`, + `EXPOSE 3000`, and set the default command to `rails server`. + + 2. build the rails app image + + docker build -t my-rails-app . + + 3. start the rails app container + + docker run --name some-rails-app -d my-rails-app + + Then go to `http://container-ip:3000` in a browser. On the other hand, if you need access + outside the host on port 8080: + + docker run --name some-rails-app -p 8080:3000 -d my-rails-app + + Then go to `http://localhost:8080` or `http://host-ip:8080` in a browser. From a899b8a63ec83bc5fa70ff8663db5ae3671d56a9 Mon Sep 17 00:00:00 2001 From: Fred Lifton Date: Mon, 8 Sep 2014 12:36:52 -0700 Subject: [PATCH 03/10] Format and typo fixes Docker-DCO-1.1-Signed-off-by: Fred Lifton (github: fredlf) --- docs/sources/docker-hub/official_repos.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/sources/docker-hub/official_repos.md b/docs/sources/docker-hub/official_repos.md index a8ee135e01..07a933a769 100644 --- a/docs/sources/docker-hub/official_repos.md +++ b/docs/sources/docker-hub/official_repos.md @@ -39,8 +39,9 @@ Official Image. document](TODO: link). In addition, Docker, Inc. engineer Michael Crosby has a good discussion of Dockerfiles in this [blog post](http://crosbymichael.com/dockerfile-best-practices-take-2.html). -While [ONBUILD triggers](https://docs.docker.com/reference/builder/#onbuild) are not +While `[ONBUILD triggers]`(https://docs.docker.com/reference/builder/#onbuild) are not required, if you choose to use them you should: + * Build both `ONBUILD` and non-`ONBUILD` images, with the `ONBUILD` image built `FROM` the non-`ONBUILD` image. * The `ONBUILD` image should be specifically tagged, for example, `ruby:latest` and @@ -117,7 +118,7 @@ contacts, additional “how-to” information or other resources. ## License -Include a file, (`LICENSE`), of any applicable license. Docker recommends using the +Include a file, `LICENSE`, of any applicable license. Docker recommends using the license of the software contained in the image, provided it allows Docker, Inc. to legally build and distribute the image. Otherwise Docker recommends adopting the [Expat license]((http://directory.fsf.org/wiki/License:Expat). @@ -129,7 +130,7 @@ Ruby on Rails. ## Short description - **README-short.txt** + README-short.txt Ruby on Rails is an open-source application framework written in Ruby. It emphasizes best practices such as convention over configuration, active record pattern, and the @@ -137,7 +138,8 @@ Ruby on Rails. ## Long description - **README.md** + README.md + # What is Ruby on Rails Ruby on Rails, often simply referred to as Rails, is an open source web application From 5fea2b5be32165364294e22bc24aee3fa34cf756 Mon Sep 17 00:00:00 2001 From: Fred Lifton Date: Mon, 8 Sep 2014 16:30:39 -0700 Subject: [PATCH 04/10] More format fixes. Docker-DCO-1.1-Signed-off-by: Fred Lifton (github: fredlf) --- docs/sources/docker-hub/official_repos.md | 39 +++++++++++------------ 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/docs/sources/docker-hub/official_repos.md b/docs/sources/docker-hub/official_repos.md index 07a933a769..811d31cb13 100644 --- a/docs/sources/docker-hub/official_repos.md +++ b/docs/sources/docker-hub/official_repos.md @@ -2,7 +2,7 @@ page_title: Guidelines for Official Repositories on Docker Hub page_description: Guidelines for Official Repositories on Docker Hub page_keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, official, image, documentation -# Introduction +## Introduction 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 @@ -15,9 +15,9 @@ This document consists of three major sections: * Examples embodying those practices * Instructions for submitting contributions and reporting issues -# Expected Files & Resources +## Expected Files & Resources -## A Git repository +### A Git repository Your image needs to live in a Git repository, preferably on GitHub. (If you’d like to use a different provider, please [contact us](TODO: link) directly.) Docker **strongly** @@ -27,7 +27,7 @@ If the repo is private or has otherwise limited access, you must provide a means least “read-only” access for both general users and for the docker-library maintainers, who need access for review and building purposes. -## A `Dockerfile` +### A `Dockerfile` Complete information on `Dockerfile`s can be found in the [Reference section](https://docs.docker.com/reference/builder/). We also have a page discussing best practices for writing `Dockerfile`s (TODO: link). @@ -47,7 +47,7 @@ the non-`ONBUILD` image. * The `ONBUILD` image should be specifically tagged, for example, `ruby:latest` and `ruby:onbuild`, or `ruby:2` and `ruby:2-onbuild`. -## A short description +### A short description Include a brief description of your image (in plaintext). Only one description is required; you don’t need additional descriptions for each tag. The file should also: @@ -56,7 +56,7 @@ required; you don’t need additional descriptions for each tag. The file should * Reside in the repo for the “latest” tag * Not exceed 200 characters. -## A logo +### A logo Include a logo of your company or the product (png format preferred). Only one logo is required; you don’t need additional logo files for each tag. The logo file should have @@ -68,7 +68,7 @@ the following characteristics: * Square or wide (landscape) is preferred over tall (portrait), but exceptions can be made based on the logo needed. -## A long description +### A long description Include a comprehensive description of your image (in markdown format). Only one description is required; you don’t need additional descriptions for each tag. The file @@ -86,49 +86,47 @@ In terms of content, the long description must include the following sections: * User Feedback * License -### Overview & links + +#### 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. -### How-to/usage +This section *must* also include a link to the `Dockerfile`. + +#### How-to/usage A section that describes how to run and use the image, including common use cases and example `Dockerfile`s (if applicable). Try to provide clear, step-by-step instructions wherever possible. -### User Feedback - -This section should have two parts, one explaining how users can contribute to the repo -and one explaining how to report issues with the repo. - -#### Contributing +##### Contributing In this part, point users to any resources that can help them contribute to the project. Include contribution guidelines and any specific instructions related to your development practices. Include a link to [Docker’s resources for contributors](https://docs.docker.com/contributing/contributing/). Be sure to include contact info, handles, etc. for official maintainers. -#### Issues +##### Issues Include a brief section letting users know where they can go for help and how they can file issues with the repo. Point them to any specific IRC channels, issue trackers, contacts, additional “how-to” information or other resources. -## License +### License Include a file, `LICENSE`, of any applicable license. Docker recommends using the license of the software contained in the image, provided it allows Docker, Inc. to legally build and distribute the image. Otherwise Docker recommends adopting the [Expat license]((http://directory.fsf.org/wiki/License:Expat). -# Examples +## Examples Below are sample short and long description files for an imaginary image containing Ruby on Rails. -## Short description +### Short description README-short.txt @@ -136,7 +134,7 @@ Ruby on Rails. best practices such as convention over configuration, active record pattern, and the model-view-controller pattern. -## Long description +### Long description README.md @@ -177,3 +175,4 @@ Ruby on Rails. Then go to `http://localhost:8080` or `http://host-ip:8080` in a browser. +For more examples, take a look at these repos: From 5b6c4051d58bf535eded3ae557a0996937e96045 Mon Sep 17 00:00:00 2001 From: Fred Lifton Date: Mon, 8 Sep 2014 17:32:29 -0700 Subject: [PATCH 05/10] More format wrestling. Docker-DCO-1.1-Signed-off-by: Fred Lifton (github: fredlf) --- docs/sources/docker-hub/official_repos.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sources/docker-hub/official_repos.md b/docs/sources/docker-hub/official_repos.md index 811d31cb13..47d34c4441 100644 --- a/docs/sources/docker-hub/official_repos.md +++ b/docs/sources/docker-hub/official_repos.md @@ -2,6 +2,8 @@ page_title: Guidelines for Official Repositories on Docker Hub page_description: Guidelines for Official Repositories on Docker Hub page_keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, official, image, documentation +# Guidelines for Creating and Documenting Official Repositories + ## Introduction You’ve been given the job of creating an image for an Official Repository hosted on From bcb9378c5b91f8fd7bc99d1ad0904f5cba6ee613 Mon Sep 17 00:00:00 2001 From: Joe Ferguson Date: Mon, 8 Sep 2014 15:59:16 -0600 Subject: [PATCH 06/10] Fix formatting, change to markdown block for long Signed-off-by: Joe Ferguson --- docs/sources/docker-hub/official_repos.md | 73 ++++++++++------------- 1 file changed, 31 insertions(+), 42 deletions(-) diff --git a/docs/sources/docker-hub/official_repos.md b/docs/sources/docker-hub/official_repos.md index 47d34c4441..4a2b2ecf0e 100644 --- a/docs/sources/docker-hub/official_repos.md +++ b/docs/sources/docker-hub/official_repos.md @@ -41,7 +41,7 @@ Official Image. document](TODO: link). In addition, Docker, Inc. engineer Michael Crosby has a good discussion of Dockerfiles in this [blog post](http://crosbymichael.com/dockerfile-best-practices-take-2.html). -While `[ONBUILD triggers]`(https://docs.docker.com/reference/builder/#onbuild) are not +While [`ONBUILD` triggers](https://docs.docker.com/reference/builder/#onbuild) are not required, if you choose to use them you should: * Build both `ONBUILD` and non-`ONBUILD` images, with the `ONBUILD` image built `FROM` @@ -86,7 +86,6 @@ In terms of content, the long description must include the following sections: * Overview & Links * How-to/Usage * User Feedback -* License #### Overview & links @@ -121,7 +120,7 @@ contacts, additional “how-to” information or other resources. Include a file, `LICENSE`, of any applicable license. Docker recommends using the license of the software contained in the image, provided it allows Docker, Inc. to legally build and distribute the image. Otherwise Docker recommends adopting the -[Expat license]((http://directory.fsf.org/wiki/License:Expat). +[Expat license](http://directory.fsf.org/wiki/License:Expat). ## Examples @@ -130,51 +129,41 @@ Ruby on Rails. ### Short description - README-short.txt - - Ruby on Rails is an open-source application framework written in Ruby. It emphasizes - best practices such as convention over configuration, active record pattern, and the - model-view-controller pattern. +`README-short.txt` + +`Ruby on Rails is an open-source application framework written in Ruby. It emphasizes best practices such as convention over configuration, active record pattern, and the model-view-controller pattern.` ### Long description - README.md - - # What is Ruby on Rails - - Ruby on Rails, often simply referred to as Rails, is an open source web application - framework which runs via the Ruby programming language. It is a full-stack framework: - it allows creating pages and applications that gather information from the web server, - talk to or query the database, and render templates out of the box. As a result, Rails - features a routing system that is independent of the web server. - - [wikipedia.org/wiki/Ruby_on_Rails](https://en.wikipedia.org/wiki/Ruby_on_Rails) - - **How to use this image** - - 1. create a `Dockerfile` in your rails app project - - FROM rails:onbuild - - Put this file in the root of your app, next to the `Gemfile`. +`README.md` + +```markdown +# What is Ruby on Rails + +Ruby on Rails, often simply referred to as Rails, is an open source web application framework which runs via the Ruby programming language. It is a full-stack framework: it allows creating pages and applications that gather information from the web server, talk to or query the database, and render templates out of the box. As a result, Rails features a routing system that is independent of the web server. + +> [wikipedia.org/wiki/Ruby_on_Rails](https://en.wikipedia.org/wiki/Ruby_on_Rails) + +# How to use this image + +## Create a `Dockerfile` in your rails app project + + FROM rails:onbuild + +Put this file in the root of your app, next to the `Gemfile`. + +This image includes multiple `ONBUILD` triggers so that should be all that you need for most applications. The build will `ADD . /usr/src/app`, `RUN bundle install`, `EXPOSE 3000`, and set the default command to `rails server`. + +Then build and run the docker image. - This image includes multiple `ONBUILD` triggers so that should be all that you need - for most applications. The build will `ADD . /usr/src/app`, `RUN bundle install`, - `EXPOSE 3000`, and set the default command to `rails server`. - - 2. build the rails app image - docker build -t my-rails-app . - - 3. start the rails app container - docker run --name some-rails-app -d my-rails-app - - Then go to `http://container-ip:3000` in a browser. On the other hand, if you need access - outside the host on port 8080: - + +Test it by visiting `http://container-ip:3000` in a browser. On the other hand, if you need access outside the host on port 8080: + docker run --name some-rails-app -p 8080:3000 -d my-rails-app - - Then go to `http://localhost:8080` or `http://host-ip:8080` in a browser. + +Then hit `http://localhost:8080` or `http://host-ip:8080` in a browser. +``` For more examples, take a look at these repos: From a2ba4d56eb134f95eba790bb484e0c8bd77d1fc4 Mon Sep 17 00:00:00 2001 From: Fred Lifton Date: Wed, 10 Sep 2014 14:26:03 -0700 Subject: [PATCH 07/10] Fixes a couple small typos Docker-DCO-1.1-Signed-off-by: Fred Lifton (github: fredlf) --- docs/sources/docker-hub/official_repos.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/sources/docker-hub/official_repos.md b/docs/sources/docker-hub/official_repos.md index 47d34c4441..b4cf54fcdb 100644 --- a/docs/sources/docker-hub/official_repos.md +++ b/docs/sources/docker-hub/official_repos.md @@ -86,8 +86,6 @@ In terms of content, the long description must include the following sections: * Overview & Links * How-to/Usage * User Feedback -* License - #### Overview & links From d9fd5f6199aebb9ea784f5b23ec97b960f89f3d4 Mon Sep 17 00:00:00 2001 From: Fred Lifton Date: Tue, 23 Sep 2014 14:21:00 -0700 Subject: [PATCH 08/10] Adding new Dockerfile Best Practices doc, and links thereto. Docker-DCO-1.1-Signed-off-by: Fred Lifton (github: fredlf) --- docs/mkdocs.yml | 9 +- docs/sources/articles/baseimages.md | 11 +- .../articles/dockerfile_best-practices.md | 333 ++++++++++++++++++ docs/sources/docker-hub/official_repos.md | 117 +++--- docs/sources/reference/builder.md | 5 + docs/sources/userguide/dockerimages.md | 4 +- 6 files changed, 420 insertions(+), 59 deletions(-) create mode 100644 docs/sources/articles/dockerfile_best-practices.md diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index f620030713..9428b85e3e 100755 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -84,17 +84,18 @@ pages: - ['articles/networking.md', 'Articles', 'Advanced networking'] - ['articles/security.md', 'Articles', 'Security'] - ['articles/https.md', 'Articles', 'Running Docker with HTTPS'] -- ['articles/host_integration.md', 'Articles', 'Automatically starting Containers'] +- ['articles/host_integration.md', 'Articles', 'Automatically starting containers'] +- ['articles/baseimages.md', 'Articles', 'Creating a base image'] +- ['articles/dockerfile_best-practices.md', 'Articles', 'Best practices for writing Dockerfiles'] - ['articles/certificates.md', 'Articles', 'Using certificates for repository client verification'] - ['articles/using_supervisord.md', 'Articles', 'Using Supervisor'] - ['articles/cfengine_process_management.md', 'Articles', 'Process management with CFEngine'] - ['articles/puppet.md', 'Articles', 'Using Puppet'] - ['articles/chef.md', 'Articles', 'Using Chef'] - ['articles/dsc.md', 'Articles', 'Using PowerShell DSC'] -- ['articles/ambassador_pattern_linking.md', 'Articles', 'Cross-Host linking using Ambassador Containers'] +- ['articles/ambassador_pattern_linking.md', 'Articles', 'Cross-Host linking using ambassador containers'] - ['articles/runmetrics.md', 'Articles', 'Runtime metrics'] -- ['articles/baseimages.md', 'Articles', 'Creating a Base Image'] -- ['articles/b2d_volume_resize.md', 'Articles', 'Increasing a Boot2Docker Volume'] +- ['articles/b2d_volume_resize.md', 'Articles', 'Increasing a Boot2Docker volume'] # Reference - ['reference/index.md', '**HIDDEN**'] diff --git a/docs/sources/articles/baseimages.md b/docs/sources/articles/baseimages.md index bc677eb8a3..3f53c8a84b 100644 --- a/docs/sources/articles/baseimages.md +++ b/docs/sources/articles/baseimages.md @@ -55,5 +55,14 @@ image to base your new minimal containers `FROM`: COPY true-asm /true CMD ["/true"] -The Dockerfile above is from extremely minimal image - [tianon/true]( +The `Dockerfile` above is from an extremely minimal image - [tianon/true]( https://github.com/tianon/dockerfiles/tree/master/true). + +## More resources + +There are lots more resources available to help you write your 'Dockerfile`. + +* There's a [complete guide to all the instructions](/reference/builder/) available for use in a `Dockerfile` in the reference section. +* To help you write a clear, readable, maintainable `Dockerfile`, we've also +written a [`Dockerfile` Best Practices guide](/articles/dockerfile_best-practices). +* If you're working on an Official Repo, be sure to check out the [Official Repo Guidelines](/docker-hub/official_repos/). diff --git a/docs/sources/articles/dockerfile_best-practices.md b/docs/sources/articles/dockerfile_best-practices.md new file mode 100644 index 0000000000..f73c72c4ad --- /dev/null +++ b/docs/sources/articles/dockerfile_best-practices.md @@ -0,0 +1,333 @@ +page_title: Best Practices for Writing Dockerfiles +page_description: Hints, tips and guidelines for writing clean, reliable Dockerfiles +page_keywords: Examples, Usage, base image, docker, documentation, dockerfile, best practices, hub, official repo + + + # Best Practices for Writing `Dockerfile`s + +## Overview + +Docker can build images automatically by reading the instructions from a +`Dockerfile`, a text file that contains all the commands, in order, needed to +build a given image. `Dockerfile`s adhere to a specific format and use a +specific set of instructions. You can learn the basics on the +[Dockerfile Reference](https://docs.docker.com/reference/builder/) page. If +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). + +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). + +> Note: for more detailed explanations of any of the Dockerfile commands +>mentioned here, visit the [Dockerfile Reference](https://docs.docker.com/reference/builder/) page. + +## General Guidelines and Recommendations + +### Containers should be ephemeral + +The container produced by the image your `Dockerfile` defines should be as +ephemeral as possible. “Ephemeral” here means that it can be stopped and +destroyed and a new one built and put in place with an absolute minimum of +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. + +### Avoid installing unnecessary packages + +You should avoid installing extra or unnecessary packages just because they +might be “nice to have.” For example, you don’t need to include a text editor +in a database image. + +### Run only one process per container + +In almost all cases, you should only run a single process in a single +container. Decoupling applications into multiple containers makes it much +easier to scale horizontally and reuse containers. If that service depends on +another service, make use of [container linking](https://docs.docker.com/userguide/dockerlinks/). + +### Minimize the number of layers + +You need to find the balance between readability (and thus long-term +maintainability) of the `Dockerfile` and minimizing the number of layers it +uses. Be strategic and cautious about the number of layers you use. + +### Sort multi-line arguments + +Whenever possible, ease later changes by sorting multi-line arguments +alphanumerically. This will help you avoid duplication of packages and make the +list much easier to update. This also makes PRs a lot easier to read and +review. Adding a space before a backslash (`\`) helps as well. + +Here’s an example from the [`buildpack-deps` image](https://github.com/docker-library/buildpack-deps): + + RUN apt-get update && apt-get install -y \ + bzr \ + cvs \ + git \ + mercurial \ + subversion + +## The `Dockerfile` instructions + +This section contains specific recommendations for the correct usage of the +various instructions contained in a `Dockerfile`. + +### [`FROM`](https://docs.docker.com/reference/builder/#from) + +Whenever possible, use 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) + +As always, to make your `Dockerfile` more readable, understandable, and +maintainable, put long or complex statements on multiple lines separated with +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 +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. + +* 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 +and maintain, but also, by including `apt-get update`, ensures that the cache +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 +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. + +#### Example + +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). + + RUN apt-get update && apt-get install -y \ + aufs-tools \ + automake \ + btrfs-tools \ + build-essential \ + curl \ + dpkg-sig \ + git \ + iptables \ + libapparmor-dev \ + libcap-dev \ + libsqlite3-dev \ + lxc=1.0* \ + mercurial \ + parallel \ + reprepro \ + ruby1.9.1 \ + ruby1.9.1-dev \ + s3cmd=1.1.0* + +### [`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 +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 `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 +conjunction with [`ENTRYPOINT`](https://docs.docker.com/reference/builder/#entrypoint), unless +you and your expected users are already quite familiar with how `ENTRYPOINT` +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. + +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. +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) + +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 +example, `ENV PATH /usr/local/nginx/bin:$PATH` will ensure that `CMD [“nginx”]` +just works. + +The `ENV` instruction is also useful for providing required environment +variables specific to services you wish to containerize, such as Postgres’s +`PGDATA`. + +Lastly, `ENV` can also be used to set commonly used version numbers so that +version bumps are easier to maintain, as seen in the following example: + + ENV PG_MAJOR 9.3 + ENV PG_VERSION 9.3.4 + RUN curl -SL http://example.com/postgres-$PG_VERSION.tar.xz | tar -xJC /usr/src/postgress && … + ENV PATH /usr/local/postgres-$PG_MAJOR/bin:$PATH + +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) + +Although `ADD` and `COPY` are functionally similar, generally speaking, `COPY` +is preferred. That’s because it’s more transparent than `ADD`. `COPY` only +supports the basic copying of local files into the container, while `ADD` has +some features (like local-only tar extraction and remote URL support) that are +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: + + ADD http://example.com/big.tar.xz /usr/src/things/ + RUN tar -xJf /usr/src/things/big.tar.xz -C /usr/src/things + RUN make -C /usr/src/things all + +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 + +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) + +The best use for `ENTRYPOINT` is as a helper script. Using `ENTRYPOINT` for +other tasks can make your code harder to understand. For example, `docker run +-it official-image bash` is much easier to understand than `docker run -it +--entrypoint bash official-image -i`, especially for Docker beginners. + +In order to avoid a situation where commands are run without clear visibility +to the user, make sure your script ends with something like `exec "$@"`. After +the entrypoint completes, the script will transparently bootstrap the command +invoked by the user, making what has been run clear to the user (for example, +`docker run -it mysql mysqld --some --flags` will transparently run `mysqld +--some --flags` after `ENTRYPOINT` runs `initdb`). + +For example, let’s look at the `Dockerfile` for the +[Postgres Official Image](https://github.com/docker-library/postgres). +It refers to the following script: + +```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 "$@" +``` + +That script then gets copied into the container and the run via `ENTRYPOINT` on +container startup: + + COPY ./docker-entrypoint.sh / + ENTRYPOINT ["/docker-entrypoint.sh"] + +### [`VOLUME`](https://docs.docker.com/reference/builder/#volume) + +`VOLUME` 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) + +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 +like `RUN groupadd -r postgres && useradd -r -g postgres postgres`. + +>**Note** that users/groups in an image get assigned nondeterministic UID/GID in +>that the “next” UID/GID will be assigned regardless of image rebuilds. So, if +>it’s critical, you should assign an explicit UID/GID. + +You should avoid installing or using `sudo` since it has unpredictable TTY and +signal-forwarding behavior that can cause more more problems than it solves. If +you absolutely need functionality similar to `sudo` (e.g., initializing the +daemon as root but running it as non-root), you may be able to use +[“gosu”](https://github.com/tianon/gosu). + +Lastly, to reduce layers and complexity, try to minimize switching `USER` back +and forth frequently. + +### [`WORKDIR`](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` is only useful for images that are going to be built `FROM` a given +image. For example, you would use `ONBUILD` for a language stack image that +builds arbitrary user software written in that language within the +`Dockerfile`, as you can see in [Ruby’s `ONBUILD` variants](https://github.com/docker-library/ruby/blob/master/2.1/onbuild/Dockerfile). + +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. + +## Examples For Official Repositories + +These Official Repos have exemplary `Dockerfile`s: +* [Go](https://registry.hub.docker.com/_/golang/) +* [Perl](https://registry.hub.docker.com/_/perl/) +* [Hy](https://registry.hub.docker.com/_/hylang/) +* [Rails](https://registry.hub.docker.com/_/rails) + +## Additional Resources: + +* [Dockerfile Reference](https://docs.docker.com/reference/builder/#onbuild) +* [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 Repositories](https://docs.docker.com/docker-hub/official_repos/) \ No newline at end of file diff --git a/docs/sources/docker-hub/official_repos.md b/docs/sources/docker-hub/official_repos.md index e7cb86a369..be73c94524 100644 --- a/docs/sources/docker-hub/official_repos.md +++ b/docs/sources/docker-hub/official_repos.md @@ -6,10 +6,11 @@ page_keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub ## Introduction -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 planning to create an Official -Repo, you can think of these guidelines as best practices for image creation generally. +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 +planning to create an Official Repo, you can think of these guidelines as best +practices for image creation generally. This document consists of three major sections: @@ -21,38 +22,41 @@ This document consists of three major sections: ### A Git repository -Your image needs to live in a Git repository, preferably on GitHub. (If you’d like to use -a different provider, please [contact us](TODO: link) directly.) Docker **strongly** -recommends that this repo be publicly accessible. +Your image needs to live in a Git repository, preferably on GitHub. (If you’d +like to use a different provider, please [contact us](mailto:feedback@docker.com) +directly.) Docker **strongly** recommends that this repo be publicly +accessible. -If the repo is private or has otherwise limited access, you must provide a means of at -least “read-only” access for both general users and for the docker-library maintainers, -who need access for review and building purposes. +If the repo is private or has otherwise limited access, you must provide a +means of at least “read-only” access for both general users and for the docker- +library maintainers, who need access for review and building purposes. ### A `Dockerfile` Complete information on `Dockerfile`s can be found in the [Reference section](https://docs.docker.com/reference/builder/). -We also have a page discussing best practices for writing `Dockerfile`s (TODO: link). +We also have a page discussing [best practices for writing `Dockerfile`s](/articles/dockerfile_best-practices). Your `Dockerfile` should adhere to the following: -* It must be written either by using `FROM scratch` or be based on another, established -Official Image. -* It must follow `Dockerfile` best practices. These are discussed in the [Best Practices -document](TODO: link). In addition, Docker, Inc. engineer Michael Crosby has a good -discussion of Dockerfiles in this [blog post](http://crosbymichael.com/dockerfile-best-practices-take-2.html). +* It must be written either by using `FROM scratch` or be based on another, +established Official Image. +* It must follow `Dockerfile` best practices. These are discussed in the +[Best Practices document](/articles/dockerfile_best-practices). In addition, +Docker, Inc. engineer Michael Crosby has a good discussion of Dockerfiles in +this [blog post](http://crosbymichael.com/dockerfile-best-practices-take-2.html). -While [`ONBUILD` triggers](https://docs.docker.com/reference/builder/#onbuild) are not -required, if you choose to use them you should: +While [`ONBUILD` triggers](https://docs.docker.com/reference/builder/#onbuild) +are not required, if you choose to use them you should: -* Build both `ONBUILD` and non-`ONBUILD` images, with the `ONBUILD` image built `FROM` -the non-`ONBUILD` image. -* The `ONBUILD` image should be specifically tagged, for example, `ruby:latest` and -`ruby:onbuild`, or `ruby:2` and `ruby:2-onbuild`. +* Build both `ONBUILD` and non-`ONBUILD` images, with the `ONBUILD` image +built `FROM` the non-`ONBUILD` image. +* The `ONBUILD` image should be specifically tagged, for example, `ruby: +latest`and `ruby:onbuild`, or `ruby:2` and `ruby:2-onbuild`. ### A short description -Include a brief description of your image (in plaintext). Only one description is -required; you don’t need additional descriptions for each tag. The file should also: +Include a brief description of your image (in plaintext). Only one description +is required; you don’t need additional descriptions for each tag. The file +should also: * Be named `README-short.txt` * Reside in the repo for the “latest” tag @@ -60,26 +64,26 @@ required; you don’t need additional descriptions for each tag. The file should ### A logo -Include a logo of your company or the product (png format preferred). Only one logo is -required; you don’t need additional logo files for each tag. The logo file should have -the following characteristics: +Include a logo of your company or the product (png format preferred). Only one +logo is required; you don’t need additional logo files for each tag. The logo +file should have the following characteristics: * Be named `logo.png` * Should reside in the repo for the “latest” tag * Should be 200px min. in one dimension, 200px max. in the other. -* Square or wide (landscape) is preferred over tall (portrait), but exceptions can be -made based on the logo needed. +* Square or wide (landscape) is preferred over tall (portrait), but exceptions +can be made based on the logo needed. ### A long description -Include a comprehensive description of your image (in markdown format). Only one -description is required; you don’t need additional descriptions for each tag. The file -should also: +Include a comprehensive description of your image (in markdown format). Only +one description is required; you don’t need additional descriptions for each +tag. The file should also: * Be named `README.md` * Reside in the repo for the “latest” tag -* Be no longer than absolutely necessary, while still addressing all the content -requirements. +* Be no longer than absolutely necessary, while still addressing all the +content requirements. In terms of content, the long description must include the following sections: @@ -89,42 +93,43 @@ In terms of content, the long description must include the following sections: #### 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. +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`. #### How-to/usage -A section that describes how to run and use the image, including common use cases and -example `Dockerfile`s (if applicable). Try to provide clear, step-by-step instructions -wherever possible. +A section that describes how to run and use the image, including common use +cases and example `Dockerfile`s (if applicable). Try to provide clear,step-by- +step instructions wherever possible. ##### Contributing -In this part, point users to any resources that can help them contribute to the project. -Include contribution guidelines and any specific instructions related to your development -practices. Include a link to [Docker’s resources for contributors](https://docs.docker.com/contributing/contributing/). +In this part, point users to any resources that can help them contribute to the +project. Include contribution guidelines and any specific instructions related +to your development practices. Include a link to +[Docker’s resources for contributors](https://docs.docker.com/contributing/contributing/). Be sure to include contact info, handles, etc. for official maintainers. ##### Issues -Include a brief section letting users know where they can go for help and how they can -file issues with the repo. Point them to any specific IRC channels, issue trackers, -contacts, additional “how-to” information or other resources. +Include a brief section letting users know where they can go for help and how +they can file issues with the repo. Point them to any specific IRC channels, +issue trackers, contacts, additional “how-to” information or other resources. ### License -Include a file, `LICENSE`, of any applicable license. Docker recommends using the -license of the software contained in the image, provided it allows Docker, Inc. to -legally build and distribute the image. Otherwise Docker recommends adopting the -[Expat license](http://directory.fsf.org/wiki/License:Expat). +Include a file, `LICENSE`, of any applicable license. Docker recommends using +the license of the software contained in the image, provided it allows Docker, +Inc. to legally build and distribute the image. Otherwise Docker recommends +adopting the [Expat license](http://directory.fsf.org/wiki/License:Expat). ## Examples -Below are sample short and long description files for an imaginary image containing -Ruby on Rails. +Below are sample short and long description files for an imaginary image +containing Ruby on Rails. ### Short description @@ -165,4 +170,10 @@ Test it by visiting `http://container-ip:3000` in a browser. On the other hand, Then hit `http://localhost:8080` or `http://host-ip:8080` in a browser. ``` -For more examples, take a look at these repos: +For more examples, take a look at these repos: + +* [Go](https://github.com/docker-library/golang) +* [PostgreSQL](https://github.com/docker-library/postgres) +* [Buildpack-deps](https://github.com/docker-library/buildpack-deps) +* ["Hello World" minimal container](https://github.com/docker-library/hello-world) +* [Node](https://github.com/docker-library/node) diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md index 796d07d98e..eca8dd618f 100644 --- a/docs/sources/reference/builder.md +++ b/docs/sources/reference/builder.md @@ -11,6 +11,11 @@ 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). + + ## Usage To [*build*](../commandline/cli/#cli-build) an image from a source repository, diff --git a/docs/sources/userguide/dockerimages.md b/docs/sources/userguide/dockerimages.md index e6583a0f82..2b64d900ab 100644 --- a/docs/sources/userguide/dockerimages.md +++ b/docs/sources/userguide/dockerimages.md @@ -468,11 +468,13 @@ We can then create a container from our new image. root@8196968dac35:/# > **Note:** -> This is just the briefest introduction to creating images. We've +> This is just a brief introduction to creating images. We've > skipped a whole bunch of other instructions that you can use. We'll see more of > those instructions in later sections of the Guide or you can refer to the > [`Dockerfile`](/reference/builder/) reference for a > detailed description and examples of every instruction. +> To help you write a clear, readable, maintainable `Dockerfile`, we've also +> written a [`Dockerfile` Best Practices guide](/articles/dockerfile_best-practices). ## Setting tags on an image From 6747dfc8031205f0e629a3508f14125b3b66a5b2 Mon Sep 17 00:00:00 2001 From: Fred Lifton Date: Tue, 23 Sep 2014 15:51:17 -0700 Subject: [PATCH 09/10] Typo and formatting fixes. Copy edits. Docker-DCO-1.1-Signed-off-by: Fred Lifton (github: fredlf) --- .../articles/dockerfile_best-practices.md | 57 +++++++++---------- docs/sources/docker-hub/official_repos.md | 21 +++---- 2 files changed, 36 insertions(+), 42 deletions(-) diff --git a/docs/sources/articles/dockerfile_best-practices.md b/docs/sources/articles/dockerfile_best-practices.md index f73c72c4ad..85bc5edff7 100644 --- a/docs/sources/articles/dockerfile_best-practices.md +++ b/docs/sources/articles/dockerfile_best-practices.md @@ -2,8 +2,7 @@ page_title: Best Practices for Writing Dockerfiles page_description: Hints, tips and guidelines for writing clean, reliable Dockerfiles page_keywords: Examples, Usage, base image, docker, documentation, dockerfile, best practices, hub, official repo - - # Best Practices for Writing `Dockerfile`s +# Best Practices for Writing `Dockerfile`s ## Overview @@ -90,7 +89,7 @@ mb), while still being a full distribution. ### [`RUN`](https://docs.docker.com/reference/builder/#run) As always, to make your `Dockerfile` more readable, understandable, and -maintainable, put long or complex statements on multiple lines separated with +maintainable, put long or complex `RUN` statements on multiple lines separated with backslashes. Probably the most common use-case for `RUN` is an application of `apt-get`. @@ -103,7 +102,7 @@ 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 @@ -112,9 +111,8 @@ 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.*`) since it 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. @@ -150,13 +148,13 @@ that version (which in this case had a new, required feature). 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 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. +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 `CMD -[“php”, “-a”]`. Using this form means that when you execute something like +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 conjunction with [`ENTRYPOINT`](https://docs.docker.com/reference/builder/#entrypoint), unless @@ -199,17 +197,15 @@ 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`](https://docs.docker.com/reference/builder/#add) or [`COPY`](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 supports the basic copying of local files into the container, while `ADD` has some features (like local-only tar extraction and remote URL support) that are -not immediately obvious. +not immediately obvious. Consequently, the best use for `ADD` is local tar file +auto-extraction into the image, as in `ADD rootfs.tar.xz /`. -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 @@ -220,27 +216,29 @@ should avoid doing things like: RUN make -C /usr/src/things all 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 For other items (files, directories) that do not require `ADD`’s tar -auto-extraction capability, you should always use `COPY`. +auto-extraction capability, you should always use `COPY`. ### [`ENTRYPOINT`](https://docs.docker.com/reference/builder/#entrypoint) The best use for `ENTRYPOINT` is as a helper script. Using `ENTRYPOINT` for -other tasks can make your code harder to understand. For example, `docker run --it official-image bash` is much easier to understand than `docker run -it ---entrypoint bash official-image -i`, especially for Docker beginners. +other tasks can make your code harder to understand. For example, +`docker run -it official-image bash` is much easier to understand than +`docker run -it --entrypoint bash official-image -i`, especially for Docker +beginners. In order to avoid a situation where commands are run without clear visibility to the user, make sure your script ends with something like `exec "$@"`. After the entrypoint completes, the script will transparently bootstrap the command invoked by the user, making what has been run clear to the user (for example, -`docker run -it mysql mysqld --some --flags` will transparently run `mysqld ---some --flags` after `ENTRYPOINT` runs `initdb`). +`docker run -it mysql mysqld --some --flags` will transparently run +`mysqld --some --flags` after `ENTRYPOINT` runs `initdb`). For example, let’s look at the `Dockerfile` for the [Postgres Official Image](https://github.com/docker-library/postgres). @@ -271,10 +269,10 @@ container startup: ### [`VOLUME`](https://docs.docker.com/reference/builder/#volume) -`VOLUME` 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. +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) @@ -282,9 +280,9 @@ 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 like `RUN groupadd -r postgres && useradd -r -g postgres postgres`. ->**Note** that users/groups in an image get assigned nondeterministic UID/GID in ->that the “next” UID/GID will be assigned regardless of image rebuilds. So, if ->it’s critical, you should assign an explicit UID/GID. +>**Note** that users/groups in an image get assigned a non-deterministic +>UID/GID in that the “next” UID/GID gets assigned regardless of image +>rebuilds. So, if it’s critical, you should assign an explicit UID/GID. You should avoid installing or using `sudo` since it has unpredictable TTY and signal-forwarding behavior that can cause more more problems than it solves. If @@ -320,6 +318,7 @@ separate tag, as recommended above, will help mitigate this by allowing the ## Examples For Official Repositories These Official Repos have exemplary `Dockerfile`s: + * [Go](https://registry.hub.docker.com/_/golang/) * [Perl](https://registry.hub.docker.com/_/perl/) * [Hy](https://registry.hub.docker.com/_/hylang/) diff --git a/docs/sources/docker-hub/official_repos.md b/docs/sources/docker-hub/official_repos.md index be73c94524..a6ed809f8e 100644 --- a/docs/sources/docker-hub/official_repos.md +++ b/docs/sources/docker-hub/official_repos.md @@ -7,16 +7,15 @@ page_keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub ## Introduction 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 +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 planning to create an Official Repo, you can think of these guidelines as best practices for image creation generally. -This document consists of three major sections: +This document consists of two major sections: -* Expected files, resources and supporting items for your image +* A list of expected files, resources and supporting items for your image * Examples embodying those practices -* Instructions for submitting contributions and reporting issues ## Expected Files & Resources @@ -28,8 +27,8 @@ directly.) Docker **strongly** recommends that this repo be publicly accessible. If the repo is private or has otherwise limited access, you must provide a -means of at least “read-only” access for both general users and for the docker- -library maintainers, who need access for review and building purposes. +means of at least “read-only” access for both general users and for the +docker-library maintainers, who need access for review and building purposes. ### A `Dockerfile` @@ -41,7 +40,7 @@ Your `Dockerfile` should adhere to the following: established Official Image. * It must follow `Dockerfile` best practices. These are discussed in the [Best Practices document](/articles/dockerfile_best-practices). In addition, -Docker, Inc. engineer Michael Crosby has a good discussion of Dockerfiles in +Docker engineer Michael Crosby has a good discussion of Dockerfiles in this [blog post](http://crosbymichael.com/dockerfile-best-practices-take-2.html). While [`ONBUILD` triggers](https://docs.docker.com/reference/builder/#onbuild) @@ -89,10 +88,9 @@ In terms of content, the long description must include the following sections: * Overview & Links * How-to/Usage -* User Feedback +* 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. @@ -100,13 +98,11 @@ to outside resources that help to describe the software. This section *must* also include a link to the `Dockerfile`. #### How-to/usage - A section that describes how to run and use the image, including common use cases and example `Dockerfile`s (if applicable). Try to provide clear,step-by- step instructions wherever possible. -##### Contributing - +##### Issues & Contribution Info In this part, point users to any resources that can help them contribute to the project. Include contribution guidelines and any specific instructions related to your development practices. Include a link to @@ -114,7 +110,6 @@ to your development practices. Include a link to Be sure to include contact info, handles, etc. for official maintainers. ##### Issues - Include a brief section letting users know where they can go for help and how they can file issues with the repo. Point them to any specific IRC channels, issue trackers, contacts, additional “how-to” information or other resources. From 950eccab4ad4d79a5afa154849567ddfdf8dc7eb Mon Sep 17 00:00:00 2001 From: Fred Lifton Date: Tue, 23 Sep 2014 18:26:02 -0700 Subject: [PATCH 10/10] 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