2014-04-16 00:53:12 +00:00
|
|
|
|
page_title: Share Images via Repositories
|
|
|
|
|
page_description: Repositories allow users to share images.
|
|
|
|
|
page_keywords: repo, repositories, usage, pull image, push image, image, documentation
|
|
|
|
|
|
|
|
|
|
# Share Images via Repositories
|
|
|
|
|
|
|
|
|
|
## Introduction
|
|
|
|
|
|
|
|
|
|
A *repository* is a shareable collection of tagged
|
|
|
|
|
[*images*](../../terms/image/#image-def) that together create the file
|
|
|
|
|
systems for containers. The repository’s name is a label that indicates
|
|
|
|
|
the provenance of the repository, i.e. who created it and where the
|
|
|
|
|
original copy is located.
|
|
|
|
|
|
|
|
|
|
You can find one or more repositories hosted on a *registry*. There can
|
|
|
|
|
be an implicit or explicit host name as part of the repository tag. The
|
|
|
|
|
implicit registry is located at `index.docker.io`,
|
|
|
|
|
the home of "top-level" repositories and the Central Index. This
|
|
|
|
|
registry may also include public "user" repositories.
|
|
|
|
|
|
|
|
|
|
Docker is not only a tool for creating and managing your own
|
|
|
|
|
[*containers*](../../terms/container/#container-def) – **Docker is also
|
|
|
|
|
a tool for sharing**. The Docker project provides a Central Registry to
|
|
|
|
|
host public repositories, namespaced by user, and a Central Index which
|
|
|
|
|
provides user authentication and search over all the public
|
|
|
|
|
repositories. You can host your own Registry too! Docker acts as a
|
|
|
|
|
client for these services via `docker search, pull, login`
|
|
|
|
|
and `push`.
|
|
|
|
|
|
|
|
|
|
## Repositories
|
|
|
|
|
|
|
|
|
|
### Local Repositories
|
|
|
|
|
|
|
|
|
|
Docker images which have been created and labeled on your local Docker
|
|
|
|
|
server need to be pushed to a Public or Private registry to be shared.
|
|
|
|
|
|
|
|
|
|
### Public Repositories
|
|
|
|
|
|
|
|
|
|
There are two types of public repositories: *top-level* repositories
|
|
|
|
|
which are controlled by the Docker team, and *user* repositories created
|
|
|
|
|
by individual contributors. Anyone can read from these repositories –
|
|
|
|
|
they really help people get started quickly! You could also use
|
2014-04-17 15:09:08 +00:00
|
|
|
|
[*Trusted Builds*](#trusted-builds) if you need to keep
|
2014-04-16 00:53:12 +00:00
|
|
|
|
control of who accesses your images, but we will only refer to public
|
|
|
|
|
repositories in these examples.
|
|
|
|
|
|
|
|
|
|
- Top-level repositories can easily be recognized by **not** having a
|
|
|
|
|
`/` (slash) in their name. These repositories
|
|
|
|
|
can generally be trusted.
|
|
|
|
|
- User repositories always come in the form of
|
|
|
|
|
`<username>/<repo_name>`. This is what your
|
|
|
|
|
published images will look like if you push to the public Central
|
|
|
|
|
Registry.
|
|
|
|
|
- Only the authenticated user can push to their *username* namespace
|
|
|
|
|
on the Central Registry.
|
|
|
|
|
- User images are not checked, it is therefore up to you whether or
|
|
|
|
|
not you trust the creator of this image.
|
|
|
|
|
|
|
|
|
|
## Find Public Images on the Central Index
|
|
|
|
|
|
|
|
|
|
You can search the Central Index [online](https://index.docker.io) or
|
|
|
|
|
using the command line interface. Searching can find images by name,
|
|
|
|
|
user name or description:
|
|
|
|
|
|
|
|
|
|
$ sudo docker help search
|
|
|
|
|
Usage: docker search NAME
|
|
|
|
|
|
|
|
|
|
Search the docker index for images
|
|
|
|
|
|
|
|
|
|
-notrunc=false: Don't truncate output
|
|
|
|
|
$ sudo docker search centos
|
|
|
|
|
Found 25 results matching your query ("centos")
|
|
|
|
|
NAME DESCRIPTION
|
|
|
|
|
centos
|
|
|
|
|
slantview/centos-chef-solo CentOS 6.4 with chef-solo.
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
There you can see two example results: `centos` and
|
|
|
|
|
`slantview/centos-chef-solo`. The second result
|
|
|
|
|
shows that it comes from the public repository of a user,
|
|
|
|
|
`slantview/`, while the first result
|
|
|
|
|
(`centos`) doesn’t explicitly list a repository so
|
|
|
|
|
it comes from the trusted Central Repository. The `/`
|
|
|
|
|
character separates a user’s repository and the image name.
|
|
|
|
|
|
|
|
|
|
Once you have found the image name, you can download it:
|
|
|
|
|
|
|
|
|
|
# sudo docker pull <value>
|
|
|
|
|
$ sudo docker pull centos
|
|
|
|
|
Pulling repository centos
|
|
|
|
|
539c0211cd76: Download complete
|
|
|
|
|
|
|
|
|
|
What can you do with that image? Check out the
|
|
|
|
|
[*Examples*](../../examples/#example-list) and, when you’re ready with
|
|
|
|
|
your own image, come back here to learn how to share it.
|
|
|
|
|
|
|
|
|
|
## Contributing to the Central Registry
|
|
|
|
|
|
|
|
|
|
Anyone can pull public images from the Central Registry, but if you
|
|
|
|
|
would like to share one of your own images, then you must register a
|
|
|
|
|
unique user name first. You can create your username and login on the
|
|
|
|
|
[central Docker Index online](https://index.docker.io/account/signup/),
|
|
|
|
|
or by running
|
|
|
|
|
|
|
|
|
|
sudo docker login
|
|
|
|
|
|
|
|
|
|
This will prompt you for a username, which will become a public
|
|
|
|
|
namespace for your public repositories.
|
|
|
|
|
|
|
|
|
|
If your username is available then `docker` will
|
|
|
|
|
also prompt you to enter a password and your e-mail address. It will
|
|
|
|
|
then automatically log you in. Now you’re ready to commit and push your
|
|
|
|
|
own images!
|
|
|
|
|
|
|
|
|
|
## Committing a Container to a Named Image
|
|
|
|
|
|
|
|
|
|
When you make changes to an existing image, those changes get saved to a
|
|
|
|
|
container’s file system. You can then promote that container to become
|
|
|
|
|
an image by making a `commit`. In addition to
|
|
|
|
|
converting the container to an image, this is also your opportunity to
|
|
|
|
|
name the image, specifically a name that includes your user name from
|
|
|
|
|
the Central Docker Index (as you did a `login`
|
|
|
|
|
above) and a meaningful name for the image.
|
|
|
|
|
|
|
|
|
|
# format is "sudo docker commit <container_id> <username>/<imagename>"
|
|
|
|
|
$ sudo docker commit $CONTAINER_ID myname/kickassapp
|
|
|
|
|
|
|
|
|
|
## Pushing a repository to its registry
|
|
|
|
|
|
|
|
|
|
In order to push an repository to its registry you need to have named an
|
|
|
|
|
image, or committed your container to a named image (see above)
|
|
|
|
|
|
|
|
|
|
Now you can push this repository to the registry designated by its name
|
|
|
|
|
or tag.
|
|
|
|
|
|
|
|
|
|
# format is "docker push <username>/<repo_name>"
|
|
|
|
|
$ sudo docker push myname/kickassapp
|
|
|
|
|
|
|
|
|
|
## Trusted Builds
|
|
|
|
|
|
|
|
|
|
Trusted Builds automate the building and updating of images from GitHub,
|
|
|
|
|
directly on `docker.io` servers. It works by adding
|
|
|
|
|
a commit hook to your selected repository, triggering a build and update
|
|
|
|
|
when you push a commit.
|
|
|
|
|
|
|
|
|
|
### To setup a trusted build
|
|
|
|
|
|
|
|
|
|
1. Create a [Docker Index account](https://index.docker.io/) and login.
|
|
|
|
|
2. Link your GitHub account through the `Link Accounts`
|
|
|
|
|
menu.
|
|
|
|
|
3. [Configure a Trusted build](https://index.docker.io/builds/).
|
|
|
|
|
4. Pick a GitHub project that has a `Dockerfile`
|
|
|
|
|
that you want to build.
|
|
|
|
|
5. Pick the branch you want to build (the default is the
|
|
|
|
|
`master` branch).
|
|
|
|
|
6. Give the Trusted Build a name.
|
|
|
|
|
7. Assign an optional Docker tag to the Build.
|
|
|
|
|
8. Specify where the `Dockerfile` is located. The
|
|
|
|
|
default is `/`.
|
|
|
|
|
|
|
|
|
|
Once the Trusted Build is configured it will automatically trigger a
|
|
|
|
|
build, and in a few minutes, if there are no errors, you will see your
|
|
|
|
|
new trusted build on the Docker Index. It will will stay in sync with
|
|
|
|
|
your GitHub repo until you deactivate the Trusted Build.
|
|
|
|
|
|
|
|
|
|
If you want to see the status of your Trusted Builds you can go to your
|
|
|
|
|
[Trusted Builds page](https://index.docker.io/builds/) on the Docker
|
|
|
|
|
index, and it will show you the status of your builds, and the build
|
|
|
|
|
history.
|
|
|
|
|
|
|
|
|
|
Once you’ve created a Trusted Build you can deactivate or delete it. You
|
|
|
|
|
cannot however push to a Trusted Build with the `docker push`
|
|
|
|
|
command. You can only manage it by committing code to your
|
|
|
|
|
GitHub repository.
|
|
|
|
|
|
|
|
|
|
You can create multiple Trusted Builds per repository and configure them
|
|
|
|
|
to point to specific `Dockerfile`‘s or Git branches.
|
|
|
|
|
|
|
|
|
|
## Private Registry
|
|
|
|
|
|
|
|
|
|
Private registries and private shared repositories are only possible by
|
|
|
|
|
hosting [your own
|
|
|
|
|
registry](https://github.com/dotcloud/docker-registry). To push or pull
|
|
|
|
|
to a repository on your own registry, you must prefix the tag with the
|
|
|
|
|
address of the registry’s host (a `.` or
|
|
|
|
|
`:` is used to identify a host), like this:
|
|
|
|
|
|
|
|
|
|
# Tag to create a repository with the full registry location.
|
|
|
|
|
# The location (e.g. localhost.localdomain:5000) becomes
|
|
|
|
|
# a permanent part of the repository name
|
|
|
|
|
sudo docker tag 0u812deadbeef localhost.localdomain:5000/repo_name
|
|
|
|
|
|
|
|
|
|
# Push the new repository to its home location on localhost
|
|
|
|
|
sudo docker push localhost.localdomain:5000/repo_name
|
|
|
|
|
|
|
|
|
|
Once a repository has your registry’s host name as part of the tag, you
|
|
|
|
|
can push and pull it like any other repository, but it will **not** be
|
|
|
|
|
searchable (or indexed at all) in the Central Index, and there will be
|
|
|
|
|
no user name checking performed. Your registry will function completely
|
|
|
|
|
independently from the Central Index.
|
|
|
|
|
|
|
|
|
|
<iframe width="640" height="360" src="//www.youtube.com/embed/CAewZCBT4PI?rel=0" frameborder="0" allowfullscreen></iframe>
|
|
|
|
|
|
|
|
|
|
See also
|
|
|
|
|
|
|
|
|
|
[Docker Blog: How to use your own
|
|
|
|
|
registry](http://blog.docker.io/2013/07/how-to-use-your-own-registry/)
|
|
|
|
|
|
|
|
|
|
## Authentication File
|
|
|
|
|
|
|
|
|
|
The authentication is stored in a json file, `.dockercfg`
|
|
|
|
|
located in your home directory. It supports multiple registry
|
|
|
|
|
urls.
|
|
|
|
|
|
|
|
|
|
`docker login` will create the
|
|
|
|
|
"[https://index.docker.io/v1/](https://index.docker.io/v1/)" key.
|
|
|
|
|
|
|
|
|
|
`docker login https://my-registry.com` will create
|
|
|
|
|
the "[https://my-registry.com](https://my-registry.com)" key.
|
|
|
|
|
|
|
|
|
|
For example:
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"https://index.docker.io/v1/": {
|
|
|
|
|
"auth": "xXxXxXxXxXx=",
|
|
|
|
|
"email": "email@example.com"
|
|
|
|
|
},
|
|
|
|
|
"https://my-registry.com": {
|
|
|
|
|
"auth": "XxXxXxXxXxX=",
|
|
|
|
|
"email": "email@my-registry.com"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
The `auth` field represents
|
|
|
|
|
`base64(<username>:<password>)`
|