* Should fit inside a 200px square, maximized in one dimension (preferably the
width)
* Square or wide (landscape) is preferred over tall (portrait), but exceptions
can be made based on the logo needed
The Official Repositories team, with help from community contributors, formally
review each proposal and provide feedback to the author. This initial review
process may require a bit of back and forth before the proposal is accepted.
### A long description
There are also subjective considerations during the review process. These
subjective concerns boil down to the basic question: "is this image generally
useful?" For example, the [`python`](https://registry.hub.docker.com/_/python/)
Official Repository is "generally useful" to the large Python developer
community, whereas an obscure text adventure game written in Python last week is
not.
Include a comprehensive description of your image (in Markdown format, GitHub
flavor preferred). Only one description is required; you don’t need additional
descriptions for each tag. The file should also:
When a new proposal is accepted, the author becomes responsibile for keeping
their images up-to-date and responding to user feedback. The Official
Repositories team becomes responsibile for publishing the images and
documentation on Docker Hub. Updates to the Official Repository follow the same
pull request process, though with less review. The Official Repositories team
ultimately acts as a gatekeeper for all changes, which helps mitigate the risk
of quality and security issues from being introduced.
* 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
* Issues & contributions
#### Overview and links
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
cases and example `Dockerfile`s (if applicable). Try to provide clear, step-by-
step instructions wherever possible.
##### Issues and contributions
In this section, 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.
Also include information 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)
(a.k.a., the MIT or X11 license).
## Examples
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`
```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.
## 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.
docker build -t my-rails-app .
docker run --name some-rails-app -d my-rails-app
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.
moxiegirl