| :title: Working With Repositories |
| :description: Repositories allow users to share images. |
| :keywords: repo, repositories, 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``. |
| |
| .. _using_public_repositories: |
| |
| 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 :ref:`using_private_repositories` if you need to keep 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. |
| |
| .. _searching_central_index: |
| |
| Find Public Images on the Central Index |
| --------------------------------------- |
| |
| You can search the Central Index `online <https://index.docker.io>`_ |
| or by the CLI. Searching can find images by name, user name or |
| description: |
| |
| .. code-block:: bash |
| |
| $ 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: |
| |
| .. code-block:: bash |
| |
| # sudo docker pull <value> |
| $ sudo docker pull centos |
| Pulling repository centos |
| 539c0211cd76: Download complete |
| |
| What can you do with that image? Check out the :ref:`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 |
| |
| .. code-block:: bash |
| |
| 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! |
| |
| .. _container_commit: |
| |
| 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. |
| |
| .. code-block:: bash |
| |
| # format is "sudo docker commit <container_id> <username>/<imagename>" |
| $ sudo docker commit $CONTAINER_ID myname/kickassapp |
| |
| .. _image_push: |
| |
| Pushing an image 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 designated by its name |
| or tag. |
| |
| .. code-block:: bash |
| |
| # format is "docker push <username>/<repo_name>" |
| $ sudo docker push myname/kickassapp |
| |
| .. _using_private_repositories: |
| |
| Private Repositories |
| -------------------- |
| |
| Right now (version 0.6), 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 |
| 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. |