: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>