mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
132 lines
4.5 KiB
ReStructuredText
132 lines
4.5 KiB
ReStructuredText
:title: Working With Repositories
|
|
:description: Repositories allow users to share images.
|
|
:keywords: repo, repositiores, usage, pull image, push image, image, documentation
|
|
|
|
.. _working_with_the_repository:
|
|
|
|
Working with Repositories
|
|
=========================
|
|
|
|
A *repository* is a hosted collection of tagged :ref:`images
|
|
<image_def>` that together create the file system for a container. The
|
|
repository's name is a tag 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.
|
|
|
|
So Docker is not only a tool for creating and managing your own
|
|
:ref:`containers <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``.
|
|
|
|
Top-level, User, and Your Own 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.
|
|
|
|
* 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.
|
|
|
|
Right now (version 0.5), private 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, like this:
|
|
|
|
.. code-block:: bash
|
|
|
|
# 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
|
|
docker tag 0u812deadbeef localhost.localdomain:5000/repo_name
|
|
|
|
# Push the new repository to its home location on localhost
|
|
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.
|
|
|
|
Find public images available on the Central Index
|
|
-------------------------------------------------
|
|
|
|
Seach by name, namespace or description
|
|
|
|
.. code-block:: bash
|
|
|
|
docker search <value>
|
|
|
|
|
|
Download them simply by their name
|
|
|
|
.. code-block:: bash
|
|
|
|
docker pull <value>
|
|
|
|
|
|
Very similarly you can search for and browse the index online on
|
|
https://index.docker.io
|
|
|
|
|
|
Connecting to the Central Registry
|
|
----------------------------------
|
|
|
|
You can create a user on the central Docker Index online, or by running
|
|
|
|
.. code-block:: bash
|
|
|
|
docker login
|
|
|
|
This will prompt you for a username, which will become a public
|
|
namespace for your public repositories.
|
|
|
|
If your username does not exist it will prompt you to also enter a
|
|
password and your e-mail address. It will then automatically log you
|
|
in.
|
|
|
|
|
|
Committing a container to a named image
|
|
---------------------------------------
|
|
|
|
In order to commit to the repository it is required to have committed
|
|
your container to an image within your username namespace.
|
|
|
|
.. code-block:: bash
|
|
|
|
# for example docker commit $CONTAINER_ID dhrp/kickassapp
|
|
docker commit <container_id> <username>/<repo_name>
|
|
|
|
|
|
Pushing a container to its repository
|
|
-------------------------------------
|
|
|
|
In order to push an image to its repository you need to have committed
|
|
your container to a named image (see above)
|
|
|
|
Now you can commit this image to the repository
|
|
|
|
.. code-block:: bash
|
|
|
|
# for example docker push dhrp/kickassapp
|
|
docker push <username>/<repo_name>
|