docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Revisions based on feedback. 

Docker-DCO-1.1-Signed-off-by: Fred Lifton <fred.lifton@docker.com> (github: fredlf)
This commit is contained in:
Fred Lifton 2014-09-08 11:43:09 -07:00
parent 58e8987837
commit eb8d0c1ccf
1 changed files with 62 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
docs/sources/docker-hub/official_repos.md
View File

@ -2,7 +2,7 @@ page_title: Guidelines for Official Repositories on Docker Hub
page_description: 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 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 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 [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. 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 three major sections:
* Expected files, resources and supporting items for your image * Expected files, resources and supporting items for your image
* Examples embodying those practices * 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 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** 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, least “read-only” access for both general users and for the docker-library maintainers,
who need access for review and building purposes. 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/). 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 (TODO: link).
@ -45,7 +46,7 @@ the non-`ONBUILD` image.
* The `ONBUILD` image should be specifically tagged, for example, `ruby:latest` and * The `ONBUILD` image should be specifically tagged, for example, `ruby:latest` and
`ruby:onbuild`, or `ruby:2` and `ruby:2-onbuild`. `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 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: 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 * Reside in the repo for the “latest” tag
* Not exceed 200 characters. * Not exceed 200 characters.
### A logo ## A logo
Include a logo of your company or the product (png format preferred). Only one logo is 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 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 * Square or wide (landscape) is preferred over tall (portrait), but exceptions can be
made based on the logo needed. made based on the logo needed.
### A long description ## A long description
Include a comprehensive description of your image (in markdown format). Only one 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 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 * User Feedback
* License * License
#### Overview & links ### Overview & links
A section providing (a) an overview of the software contained in the image, similar to 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 the introduction in a Wikipedia entry and (b) a selection of links to outside resources
that help to describe the software. 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 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 example `Dockerfile`s (if applicable). Try to provide clear, step-by-step instructions
wherever possible. wherever possible.
#### User Feedback ### User Feedback
This section should have two parts, one explaining how users can contribute to the repo 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. 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. 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 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/). 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. 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 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, file issues with the repo. Point them to any specific IRC channels, issue trackers,
contacts, additional “how-to” information or other resources. contacts, additional “how-to” information or other resources.
#### License ## License
Include a copy of any applicable license. Docker recommends using the license of the Include a file, (`LICENSE`), of any applicable license. Docker recommends using the
software contained in the image, provided it allows Docker, Inc. to legally build and license of the software contained in the image, provided it allows Docker, Inc. to
distribute the image. Otherwise Docker recommends adopting the [Apache license](https://github.com/docker/docker/blob/master/LICENSE). 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 Below are sample short and long description files for an imaginary image containing
Ruby on Rails. Ruby on Rails.
### Short description ## 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 model-
>view-controller pattern.
### Long description 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.md** ## Long description
> # 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 **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 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 Put this file in the root of your app, next to the `Gemfile`.
> 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 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`,
> docker run --name some-rails-app -d my-rails-app `EXPOSE 3000`, and set the default command to `rails server`.
>
> Then go to `http://container-ip:3000` in a browser. On the other hand, if you need access 2. build the rails app image
> outside the host on port 8080:
> docker build -t my-rails-app .
> docker run --name some-rails-app -p 8080:3000 -d my-rails-app
> 3. start the rails app container
> Then go to `http://localhost:8080` or `http://host-ip:8080` in a browser.
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.