2014-09-04 21:09:00 -04:00
|
|
|
|
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
|
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
# Introduction
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
|
|
|
|
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:
|
2014-09-08 14:43:09 -04:00
|
|
|
|
|
2014-09-04 21:09:00 -04:00
|
|
|
|
* Expected files, resources and supporting items for your image
|
|
|
|
|
* Examples embodying those practices
|
2014-09-08 14:43:09 -04:00
|
|
|
|
* Instructions for submitting contributions and reporting issues
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
# Expected Files & Resources
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
## A Git repository
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
## A `Dockerfile`
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
|
|
|
|
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`.
|
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
## A short description
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
## A logo
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
## A long description
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
### Overview & links
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
### How-to/usage
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
### User Feedback
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
#### Contributing
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
#### Issues
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
## License
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
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).
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
# Examples
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|
|
|
|
|
Below are sample short and long description files for an imaginary image containing
|
|
|
|
|
Ruby on Rails.
|
|
|
|
|
|
2014-09-08 14:43:09 -04:00
|
|
|
|
## 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
|
|
|
|
|
|
2014-09-04 21:09:00 -04:00
|
|
|
|
FROM rails:onbuild
|
2014-09-08 14:43:09 -04:00
|
|
|
|
|
|
|
|
|
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.
|
2014-09-04 21:09:00 -04:00
|
|
|
|
|