github.com/guilhermebr/docker@v1.4.2-0.20150428121140-67da055cebca/docs/sources/docker-hub/official_repos.md (about)

     1  page_title: Guidelines for official repositories on Docker Hub
     2  page_description: Guidelines for Official Repositories on Docker Hub
     3  page_keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, official, image, documentation
     4  
     5  # Guidelines for creating and documenting official repositories
     6  
     7  ## Introduction
     8  
     9  You’ve been given the job of creating an image for an Official Repository
    10  hosted on [Docker Hub Registry](https://registry.hub.docker.com/). These are
    11  our guidelines for getting that task done. Even if you’re not
    12  planning to create an Official Repo, you can think of these guidelines as best
    13  practices for image creation generally.
    14  
    15  This document consists of two major sections:
    16  
    17  * A list of expected files, resources and supporting items for your image,
    18  along with best practices for creating those items
    19  * Examples embodying those practices
    20  
    21  ## Expected files and resources
    22  
    23  ### A Git repository
    24  
    25  Your image needs to live in a Git repository, preferably on GitHub. (If you’d
    26  like to use a different provider, please [contact us](mailto:feedback@docker.com)
    27  directly.) Docker **strongly** recommends that this repo be publicly
    28  accessible.
    29  
    30  If the repo is private or has otherwise limited access, you must provide a
    31  means of at least “read-only” access for both general users and for the
    32  docker-library maintainers, who need access for review and building purposes.
    33  
    34  ### A Dockerfile
    35  
    36  Complete information on `Dockerfile`s can be found in the [Reference section](https://docs.docker.com/reference/builder/).
    37  We also have a page discussing [best practices for writing `Dockerfile`s](/articles/dockerfile_best-practices).
    38  Your `Dockerfile` should adhere to the following:
    39  
    40  * It must be written either by using `FROM scratch` or be based on another,
    41  established Official Image.
    42  * It must follow `Dockerfile` best practices. These are discussed on the
    43  [best practices page](/articles/dockerfile_best-practices). In addition,
    44  Docker engineer Michael Crosby has some good tips for `Dockerfiles` in
    45  this [blog post](http://crosbymichael.com/dockerfile-best-practices-take-2.html).
    46  
    47  While [`ONBUILD` triggers](https://docs.docker.com/reference/builder/#onbuild)
    48  are not required, if you choose to use them you should:
    49  
    50  * Build both `ONBUILD` and non-`ONBUILD` images, with the `ONBUILD` image
    51  built `FROM` the non-`ONBUILD` image.
    52  * The `ONBUILD` image should be specifically tagged, for example, `ruby:
    53  latest`and `ruby:onbuild`, or `ruby:2` and  `ruby:2-onbuild`
    54  
    55  ### A short description
    56  
    57  Include a brief description of your image (in plaintext). Only one description
    58  is required; you don’t need additional descriptions for each tag. The file
    59  should also: 
    60  
    61  * Be named `README-short.txt`
    62  * Reside in the repo for the “latest” tag
    63  * Not exceed 100 characters
    64  
    65  ### A logo
    66  
    67  Include a logo of your company or the product (png format preferred). Only one
    68  logo is required; you don’t need additional logo files for each tag. The logo
    69  file should have the following characteristics: 
    70  
    71  * Be named `logo.png`
    72  * Should reside in the repo for the “latest” tag
    73  * Should fit inside a 200px square, maximized in one dimension (preferably the
    74  width)
    75  * Square or wide (landscape) is preferred over tall (portrait), but exceptions
    76  can be made based on the logo needed
    77  
    78  ### A long description
    79  
    80  Include a comprehensive description of your image (in Markdown format, GitHub 
    81  flavor preferred). Only one description is required; you don’t need additional
    82  descriptions for each tag. The file should also: 
    83  
    84  * Be named `README.md`
    85  * Reside in the repo for the “latest” tag
    86  * Be no longer than absolutely necessary, while still addressing all the
    87  content requirements
    88  
    89  In terms of content, the long description must include the following sections:
    90  
    91  * Overview & links
    92  * How-to/usage
    93  * Issues & contributions
    94  
    95  #### Overview and links
    96  
    97  This section should provide:
    98  
    99  * an overview of the software contained in the image, similar to the
   100  introduction in a Wikipedia entry
   101  
   102  * a selection of links to outside resources that help to describe the software
   103  
   104  * a *mandatory* link to the `Dockerfile`
   105  
   106  #### How-to/usage
   107  
   108  A section that describes how to run and use the image, including common use
   109  cases and example `Dockerfile`s (if applicable). Try to provide clear, step-by-
   110  step instructions wherever possible.
   111  
   112  ##### Issues and contributions
   113  
   114  In this section, point users to any resources that can help them contribute to
   115  the project. Include contribution guidelines and any specific instructions
   116  related to your development practices. Include a link to
   117  [Docker’s resources for contributors](https://docs.docker.com/contributing/contributing/).
   118  Be sure to include contact info, handles, etc. for official maintainers.
   119  
   120  Also include information letting users know where they can go for help and how
   121  they can file issues with the repo. Point them to any specific IRC channels,
   122  issue trackers, contacts, additional “how-to” information or other resources.
   123  
   124  ### License
   125  
   126  Include a file, `LICENSE`, of any applicable license.  Docker recommends using
   127  the license of the software contained in the image, provided it allows Docker,
   128  Inc. to legally build and distribute the image. Otherwise, Docker recommends
   129  adopting the [Expat license](http://directory.fsf.org/wiki/License:Expat)
   130  (a.k.a., the MIT or X11 license).
   131  
   132  ## Examples
   133  
   134  Below are sample short and long description files for an imaginary image
   135  containing Ruby on Rails.
   136  
   137  ### Short description
   138  
   139  `README-short.txt`
   140  
   141  `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.`
   142  
   143  ### Long description
   144  
   145  `README.md`
   146  
   147  ```markdown
   148  # What is Ruby on Rails
   149  
   150  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.
   151  
   152  > [wikipedia.org/wiki/Ruby_on_Rails](https://en.wikipedia.org/wiki/Ruby_on_Rails)
   153  
   154  # How to use this image
   155  
   156  ## Create a `Dockerfile` in your rails app project
   157  
   158      FROM rails:onbuild
   159  
   160  Put this file in the root of your app, next to the `Gemfile`.
   161  
   162  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`.
   163  
   164  Then build and run the Docker image.
   165  
   166      docker build -t my-rails-app .
   167      docker run --name some-rails-app -d my-rails-app
   168  
   169  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:
   170  
   171      docker run --name some-rails-app -p 8080:3000 -d my-rails-app
   172  
   173  Then go to `http://localhost:8080` or `http://host-ip:8080` in a browser.
   174  ```
   175  
   176  For more examples, take a look at these repos: 
   177  
   178  * [Go](https://github.com/docker-library/golang)
   179  * [PostgreSQL](https://github.com/docker-library/postgres)
   180  * [Buildpack-deps](https://github.com/docker-library/buildpack-deps)
   181  * ["Hello World" minimal container](https://github.com/docker-library/hello-world)
   182  * [Node](https://github.com/docker-library/node)
   183  
   184  ## Submit your repo
   185  
   186  Once you've checked off everything in these guidelines, and are confident your
   187  image is ready for primetime, please contact us at
   188  [partners@docker.com](mailto:partners@docker.com) to have your project
   189  considered for the Official Repos program.