diff --git a/api/client.go b/api/client.go index 81e337b023..eb345ae40b 100644 --- a/api/client.go +++ b/api/client.go @@ -1668,7 +1668,7 @@ func (cli *DockerCli) CmdSearch(args ...string) error { type ports []int func (cli *DockerCli) CmdTag(args ...string) error { - cmd := cli.Subcmd("tag", "[OPTIONS] IMAGE REPOSITORY[:TAG]", "Tag an image into a repository") + cmd := cli.Subcmd("tag", "[OPTIONS] IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG]", "Tag an image into a repository") force := cmd.Bool([]string{"f", "#force", "-force"}, false, "Force") if err := cmd.Parse(args); err != nil { return nil @@ -1681,7 +1681,7 @@ func (cli *DockerCli) CmdTag(args ...string) error { var repository, tag string if cmd.NArg() == 3 { - fmt.Fprintf(cli.err, "[DEPRECATED] The format 'IMAGE [REPOSITORY [TAG]]' as been deprecated. Please use IMAGE [REPOSITORY[:TAG]]\n") + fmt.Fprintf(cli.err, "[DEPRECATED] The format 'IMAGE [REPOSITORY [TAG]]' as been deprecated. Please use IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG]]\n") repository, tag = cmd.Arg(1), cmd.Arg(2) } else { repository, tag = utils.ParseRepositoryTag(cmd.Arg(1)) diff --git a/docs/sources/reference/commandline/cli.rst b/docs/sources/reference/commandline/cli.rst index 7ba0123065..927f6d3b2d 100644 --- a/docs/sources/reference/commandline/cli.rst +++ b/docs/sources/reference/commandline/cli.rst @@ -1301,7 +1301,7 @@ The main process inside the container will receive SIGTERM, and after a grace pe :: - Usage: docker tag [OPTIONS] IMAGE REPOSITORY[:TAG] + Usage: docker tag [OPTIONS] IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG] Tag an image into a repository diff --git a/docs/sources/terms/index.rst b/docs/sources/terms/index.rst index 882d83f0d4..40851082b5 100644 --- a/docs/sources/terms/index.rst +++ b/docs/sources/terms/index.rst @@ -18,5 +18,7 @@ Contents: layer image container + registry + repository diff --git a/docs/sources/terms/registry.rst b/docs/sources/terms/registry.rst new file mode 100644 index 0000000000..90c3ee721c --- /dev/null +++ b/docs/sources/terms/registry.rst @@ -0,0 +1,16 @@ +:title: Registry +:description: Definition of an Registry +:keywords: containers, lxc, concepts, explanation, image, repository, container + +.. _registry_def: + +Registry +========== + +A Registry is a hosted service containing :ref:`repositories` +of :ref:`images` which responds to the Registry API. + +The default registry can be accessed using a browser at http://images.docker.io +or using the ``sudo docker search`` command. + +For more information see :ref:`Working with Repositories` diff --git a/docs/sources/terms/repository.rst b/docs/sources/terms/repository.rst new file mode 100644 index 0000000000..e4fe4b8fd1 --- /dev/null +++ b/docs/sources/terms/repository.rst @@ -0,0 +1,30 @@ +:title: Repository +:description: Definition of an Repository +:keywords: containers, lxc, concepts, explanation, image, repository, container + +.. _repository_def: + +Repository +========== + +A repository is a set of images either on your local Docker server, or +shared, by pushing it to a :ref:`Registry` server. + +Images can be associated with a repository (or multiple) by giving them an image name +using one of three different commands: + +1. At build time (e.g. ``sudo docker build -t IMAGENAME``), +2. When committing a container (e.g. ``sudo docker commit CONTAINERID IMAGENAME``) or +3. When tagging an image id with an image name (e.g. ``sudo docker tag IMAGEID IMAGENAME``). + +A `Fully Qualified Image Name` (FQIN) can be made up of 3 parts: + +``[registry_hostname[:port]/][user_name/](repository_name[:version_tag])`` + +``version_tag`` defaults to ``latest``, ``username`` and ``registry_hostname`` default to an empty string. +When ``registry_hostname`` is an empty string, then ``docker push`` will push to ``index.docker.io:80``. + +If you create a new repository which you want to share, you will need to set at least the +``user_name``, as the 'default' blank ``user_name`` prefix is reserved for official Docker images. + +For more information see :ref:`Working with Repositories` diff --git a/docs/sources/use/workingwithrepository.rst b/docs/sources/use/workingwithrepository.rst index 38062556cb..cbde932cde 100644 --- a/docs/sources/use/workingwithrepository.rst +++ b/docs/sources/use/workingwithrepository.rst @@ -7,9 +7,9 @@ Share Images via 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 +A *repository* is a shareable collection of tagged :ref:`images` +that together create the file systems for containers. The +repository's name is a label that indicates the provenance of the repository, i.e. who created it and where the original copy is located. @@ -19,7 +19,7 @@ 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 +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 @@ -28,6 +28,12 @@ repositories. You can host your own Registry too! Docker acts as a client for these services via ``docker search, pull, login`` and ``push``. +Local Repositories +------------------ + +Docker images which have been created and labeled on your local Docker server +need to be pushed to a Public or Private registry to be shared. + .. _using_public_repositories: Public Repositories @@ -58,8 +64,8 @@ Find Public Images on the Central Index --------------------------------------- You can search the Central Index `online `_ -or by the CLI. Searching can find images by name, user name or -description: +or using the command line interface. Searching can find images by name, user +name or description: .. code-block:: bash @@ -136,13 +142,13 @@ name for the image. .. _image_push: -Pushing an image to its repository ----------------------------------- +Pushing a repository to its registry +------------------------------------ -In order to push an image to its repository you need to have committed -your container to a named image (see above) +In order to push an repository to its registry you need to have named an image, +or committed your container to a named image (see above) -Now you can commit this image to the repository designated by its name +Now you can push this repository to the registry designated by its name or tag. .. code-block:: bash @@ -156,7 +162,7 @@ Trusted Builds -------------- Trusted Builds automate the building and updating of images from GitHub, directly -on docker.io servers. It works by adding a commit hook to your selected repository, +on ``docker.io`` servers. It works by adding a commit hook to your selected repository, triggering a build and update when you push a commit. To setup a trusted build @@ -180,21 +186,22 @@ If you want to see the status of your Trusted Builds you can go to your `Trusted Builds page `_ on the Docker index, and it will show you the status of your builds, and the build history. -Once you've created a Trusted Build you can deactive or delete it. You cannot +Once you've created a Trusted Build you can deactivate or delete it. You cannot however push to a Trusted Build with the ``docker push`` command. You can only manage it by committing code to your GitHub repository. You can create multiple Trusted Builds per repository and configure them to point to specific ``Dockerfile``'s or Git branches. -Private Repositories --------------------- +Private Registry +---------------- -Right now (version 0.6), private repositories are only possible by -hosting `your own registry +Private registries and private shared 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: +address of the registry's host (a ``.`` or ``:`` is used to identify a host), +like this: .. code-block:: bash