diff --git a/docs/sources/use/workingwithrepository.rst b/docs/sources/use/workingwithrepository.rst index 243c99afdf..3cdbfe49d6 100644 --- a/docs/sources/use/workingwithrepository.rst +++ b/docs/sources/use/workingwithrepository.rst @@ -7,21 +7,69 @@ Working with Repositories ========================= +A *repository* is a hosted collection of tagged :ref:`images +` 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. -Top-level repositories and user repositories --------------------------------------------- +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. -Generally, there are two types of repositories: Top-level repositories -which are controlled by the people behind Docker, and user -repositories. +So Docker is not only a tool for creating and managing your own +:ref:`containers ` -- **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 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 ``/``. This is what your published images will look like. -* User images are not checked, it is therefore up to you whether or not you trust the creator of this image. +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. -Find public images available on the index ------------------------------------------ +* 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 + ``/``. 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 +`_. 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 @@ -37,68 +85,48 @@ Download them simply by their name docker pull -Very similarly you can search for and browse the index online on https://index.docker.io +Very similarly you can search for and browse the index online on +https://index.docker.io -Connecting to the repository ----------------------------- +Connecting to the Central Registry +---------------------------------- -You can create a user on the central docker repository online, or by running +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. +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 with your namespace. +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 / + docker commit / -Pushing a container to the repository ------------------------------------------ +Pushing a container to its repository +------------------------------------ -In order to push an image to the repository you need to have committed your container to a named image (see above) +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 - - -Changing the server to connect to ----------------------------------- - -When you are running your own index and/or registry, You can change the server the docker client will connect to. - -Variable -^^^^^^^^ - -.. code-block:: sh - - DOCKER_INDEX_URL - -Setting this environment variable on the docker server will change the URL docker index. -This address is used in commands such as ``docker login``, ``docker push`` and ``docker pull``. -The docker daemon doesn't need to be restarted for this parameter to take effect. - -Example -^^^^^^^ - -.. code-block:: sh - - docker -d & - export DOCKER_INDEX_URL="https://index.docker.io" - + docker push /