225 lines
8.8 KiB
Markdown
225 lines
8.8 KiB
Markdown
---
|
|
description: Using repositories on Docker Hub
|
|
keywords: Docker, docker, trusted, registry, accounts, plans, Dockerfile, Docker Hub, webhooks, docs, documentation
|
|
title: Repositories
|
|
redirect_from:
|
|
- /engine/tutorials/dockerrepos/
|
|
---
|
|
|
|
Docker Hub repositories allow you share container images with your team,
|
|
customers, or the Docker community at large.
|
|
|
|
Docker images are pushed to Docker Hub through the [`docker push`](https://docs.docker.com/engine/reference/commandline/push/)
|
|
command. A single Docker Hub repository can hold many Docker images (stored as
|
|
**tags**).
|
|
|
|
## Creating repositories
|
|
|
|
To create a repository, sign into Docker Hub, click on **Repositories** then
|
|
**Create Repository**:
|
|
|
|
|
|
|
|
When creating a new repository:
|
|
|
|
* You can choose to put it in your Docker ID namespace, or in any
|
|
[organization](orgs.md) where you are an [_owner_](orgs.md#the-owners-team).
|
|
* The repository name needs to be unique in that namespace, can be two
|
|
to 255 characters, and can only contain lowercase letters, numbers, hyphens (`-`),
|
|
and underscores (`_`).
|
|
* The description can be up to 100 characters and is used in the search result.
|
|
* You can link a GitHub or Bitbucket account now, or choose to do it later in
|
|
the repository settings.
|
|
|
|
|
|
|
|
After you hit the **Create** button, you can start using `docker push` to push
|
|
images to this repository.
|
|
|
|
## Pushing a Docker container image to Docker Hub
|
|
|
|
To push an image to Docker Hub, you must first name your local image using your
|
|
Docker Hub username and the repository name that you created through Docker Hub
|
|
on the web.
|
|
|
|
You can add multiple images to a repository by adding a specific `:<tag>` to
|
|
them (for example `docs/base:testing`). If it's not specified, the tag defaults
|
|
to `latest`.
|
|
|
|
Name your local images using one of these methods:
|
|
|
|
* When you build them, using `docker build -t <hub-user>/<repo-name>[:<tag>]`
|
|
* By re-tagging an existing local image `docker tag <existing-image> <hub-user>/<repo-name>[:<tag>]`
|
|
* By using `docker commit <existing-container> <hub-user>/<repo-name>[:<tag>]`
|
|
to commit changes
|
|
|
|
Now you can push this repository to the registry designated by its name or tag.
|
|
|
|
```console
|
|
$ docker push <hub-user>/<repo-name>:<tag>
|
|
```
|
|
|
|
The image is then uploaded and available for use by your teammates and/or
|
|
the community.
|
|
|
|
## Private repositories
|
|
|
|
Private repositories let you keep container images private, either to your
|
|
own account or within an organization or team.
|
|
|
|
To create a private repository, select **Private** when creating a repository:
|
|
|
|
{: style="max-width: 60%"}
|
|
|
|
You can also make an existing repository private by going to its **Settings** tab:
|
|
|
|
{: style="max-width: 60%"}
|
|
|
|
You get one private repository for free with your Docker Hub user account (not
|
|
usable for organizations you're a member of). If you need more private
|
|
repositories for your user account, upgrade your Docker Hub plan from your
|
|
[Billing Information](https://hub.docker.com/billing/plan) page.
|
|
|
|
Once the private repository is created, you can `push` and `pull` images to and
|
|
from it using Docker.
|
|
|
|
> **Note**: You need to be signed in and have access to work with a
|
|
> private repository.
|
|
|
|
> **Note**: Private repositories are not currently available to search through
|
|
> the top-level search or `docker search`.
|
|
|
|
You can designate collaborators and manage their access to a private
|
|
repository from that repository's **Settings** page. You can also toggle the
|
|
repository's status between public and private, if you have an available
|
|
repository slot open. Otherwise, you can upgrade your
|
|
[Docker Hub](https://hub.docker.com/account/billing-plans/) plan.
|
|
|
|
## Collaborators and their role
|
|
|
|
A collaborator is someone you want to give access to a private repository. Once
|
|
designated, they can `push` and `pull` to your repositories. They are not
|
|
allowed to perform any administrative tasks such as deleting the repository or
|
|
changing its status from private to public.
|
|
|
|
> **Note**
|
|
>
|
|
> A collaborator cannot add other collaborators. Only the owner of
|
|
> the repository has administrative access.
|
|
|
|
You can also assign more granular collaborator rights ("Read", "Write", or
|
|
"Admin") on Docker Hub by using organizations and teams. For more information
|
|
see the [organizations documentation](orgs.md).
|
|
|
|
|
|
## Viewing repository tags
|
|
|
|
Docker Hub's individual repositories view shows you the available tags and the
|
|
size of the associated image. Go to the **Repositories** view and click on a
|
|
repository to see its tags.
|
|
|
|
|
|
|
|
|
|
|
|
Image sizes are the cumulative space taken up by the image and all its parent
|
|
images. This is also the disk space used by the contents of the `.tar` file
|
|
created when you `docker save` an image.
|
|
|
|
To view individual tags, click on the **Tags** tab.
|
|
|
|
|
|
|
|
An image is considered stale if there has been no push/pull activity for more
|
|
than 1 month, i.e.:
|
|
|
|
* It has not been pulled for more than 1 month
|
|
* And it has not been pushed for more than 1 month
|
|
|
|
A multi-architecture image is considered stale if all single-architecture images
|
|
part of its manifest are stale.
|
|
|
|
To delete a tag, select the corresponding checkbox and select **Delete** from the
|
|
**Action** drop-down list.
|
|
|
|
> **Note**
|
|
>
|
|
> Only a user with administrative access (owner or team member with Admin
|
|
> permission) over the repository can delete tags.
|
|
|
|
Select a tag's digest to view details.
|
|
|
|
|
|
|
|
## Searching for Repositories
|
|
|
|
You can search the [Docker Hub](https://hub.docker.com) registry through its
|
|
search interface or by using the command line interface. Searching can find
|
|
images by image name, username, or description:
|
|
|
|
```console
|
|
$ docker search centos
|
|
|
|
NAME DESCRIPTION STARS OFFICIAL AUTOMATED
|
|
centos The official build of CentOS. 1034 [OK]
|
|
ansible/centos7-ansible Ansible on Centos7 43 [OK]
|
|
tutum/centos Centos image with SSH access. For the root... 13 [OK]
|
|
...
|
|
```
|
|
|
|
There you can see two example results: `centos` and `ansible/centos7-ansible`.
|
|
The second result shows that it comes from the public repository of a user,
|
|
named `ansible/`, while the first result, `centos`, doesn't explicitly list a
|
|
repository which means that it comes from the top-level namespace for
|
|
[official images](official_images.md). The `/` character separates
|
|
a user's repository from the image name.
|
|
|
|
Once you've found the image you want, you can download it with `docker pull <imagename>`:
|
|
|
|
```console
|
|
$ docker pull centos
|
|
|
|
latest: Pulling from centos
|
|
6941bfcbbfca: Pull complete
|
|
41459f052977: Pull complete
|
|
fd44297e2ddb: Already exists
|
|
centos:latest: The image you are pulling has been verified. Important: image verification is a tech preview feature and should not be relied on to provide security.
|
|
Digest: sha256:d601d3b928eb2954653c59e65862aabb31edefa868bd5148a41fa45004c12288
|
|
Status: Downloaded newer image for centos:latest
|
|
```
|
|
|
|
You now have an image from which you can run containers.
|
|
|
|
## Starring Repositories
|
|
|
|
Your repositories can be starred and you can star repositories in return. Stars
|
|
are a way to show that you like a repository. They are also an easy way of
|
|
bookmarking your favorites.
|
|
|
|
## Service accounts
|
|
|
|
A service account is a Docker ID used by a bot for automating the build pipeline
|
|
for containerized applications. Service accounts are typically used in automated
|
|
workflows, and do not share Docker IDs with the members in the Team plan.
|
|
|
|
To create a new service account for your Team account:
|
|
|
|
1. Create a new Docker ID.
|
|
2. Create a [team](orgs.md#create-a-team) in your organization and grant it read-only access to your private repositories.
|
|
3. Add the new Docker ID to your [organization](orgs.md#working-with-organizations).
|
|
4. Add the new Docker ID to the [team](orgs.md#add-a-member-to-a-team) you created earlier.
|
|
5. Create a new [personal access token (PAT)](/access-tokens.md) from the user account and use it for CI.
|
|
|
|
To create a new service account for your Pro account:
|
|
|
|
1. Create a new Docker ID.
|
|
2. Click **Repositories** from the main menu.
|
|
3. Select a repository from the list and go to the **Collaborators** tab.
|
|
4. Add the new Docker ID as a collaborator.
|
|
5. Create a new [personal access token (PAT)](/access-tokens.md) from the user account and use it for CI.
|
|
|
|
> **Note**
|
|
>
|
|
> If you want a read-only PAT just for your open source repos, or to access
|
|
> official images and other public images, you do not have to grant any access permissions to the new Docker ID.
|