workingwithrepository.rst 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132
  1. :title: Working With Repositories
  2. :description: Repositories allow users to share images.
  3. :keywords: repo, repositiores, usage, pull image, push image, image, documentation
  4. .. _working_with_the_repository:
  5. Working with Repositories
  6. =========================
  7. A *repository* is a hosted collection of tagged :ref:`images
  8. <image_def>` that together create the file system for a container. The
  9. repository's name is a tag that indicates the provenance of the
  10. repository, i.e. who created it and where the original copy is
  11. located.
  12. You can find one or more repositories hosted on a *registry*. There
  13. can be an implicit or explicit host name as part of the repository
  14. tag. The implicit registry is located at ``index.docker.io``, the home
  15. of "top-level" repositories and the Central Index. This registry may
  16. also include public "user" repositories.
  17. So Docker is not only a tool for creating and managing your own
  18. :ref:`containers <container_def>` -- **Docker is also a tool for
  19. sharing**. The Docker project provides a Central Registry to host
  20. public repositories, namespaced by user, and a Central Index which
  21. provides user authentication and search over all the public
  22. repositories. You can host your own Registry too! Docker acts as a
  23. client for these services via ``docker search, pull, login`` and
  24. ``push``.
  25. Top-level, User, and Your Own Repositories
  26. ------------------------------------------
  27. There are two types of public repositories: *top-level* repositories
  28. which are controlled by the Docker team, and *user* repositories
  29. created by individual contributors.
  30. * Top-level repositories can easily be recognized by **not** having a
  31. ``/`` (slash) in their name. These repositories can generally be
  32. trusted.
  33. * User repositories always come in the form of
  34. ``<username>/<repo_name>``. This is what your published images will
  35. look like if you push to the public Central Registry.
  36. * Only the authenticated user can push to their *username* namespace
  37. on the Central Registry.
  38. * User images are not checked, it is therefore up to you whether or
  39. not you trust the creator of this image.
  40. Right now (version 0.5), private repositories are only possible by
  41. hosting `your own registry
  42. <https://github.com/dotcloud/docker-registry>`_. To push or pull to a
  43. repository on your own registry, you must prefix the tag with the
  44. address of the registry's host, like this:
  45. .. code-block:: bash
  46. # Tag to create a repository with the full registry location.
  47. # The location (e.g. localhost.localdomain:5000) becomes
  48. # a permanent part of the repository name
  49. docker tag 0u812deadbeef localhost.localdomain:5000/repo_name
  50. # Push the new repository to its home location on localhost
  51. docker push localhost.localdomain:5000/repo_name
  52. Once a repository has your registry's host name as part of the tag,
  53. you can push and pull it like any other repository, but it will
  54. **not** be searchable (or indexed at all) in the Central Index, and
  55. there will be no user name checking performed. Your registry will
  56. function completely independently from the Central Index.
  57. Find public images available on the Central Index
  58. -------------------------------------------------
  59. Seach by name, namespace or description
  60. .. code-block:: bash
  61. docker search <value>
  62. Download them simply by their name
  63. .. code-block:: bash
  64. docker pull <value>
  65. Very similarly you can search for and browse the index online on
  66. https://index.docker.io
  67. Connecting to the Central Registry
  68. ----------------------------------
  69. You can create a user on the central Docker Index online, or by running
  70. .. code-block:: bash
  71. docker login
  72. This will prompt you for a username, which will become a public
  73. namespace for your public repositories.
  74. If your username does not exist it will prompt you to also enter a
  75. password and your e-mail address. It will then automatically log you
  76. in.
  77. Committing a container to a named image
  78. ---------------------------------------
  79. In order to commit to the repository it is required to have committed
  80. your container to an image within your username namespace.
  81. .. code-block:: bash
  82. # for example docker commit $CONTAINER_ID dhrp/kickassapp
  83. docker commit <container_id> <username>/<repo_name>
  84. Pushing a container to its repository
  85. -------------------------------------
  86. In order to push an image to its repository you need to have committed
  87. your container to a named image (see above)
  88. Now you can commit this image to the repository
  89. .. code-block:: bash
  90. # for example docker push dhrp/kickassapp
  91. docker push <username>/<repo_name>