Setting up a Docker re­pos­it­ory

Learn how to store your Docker images, either with a self-hosted local registry, or using a Docker Hub re­pos­it­ory. This will allow you to store and organise your Docker images, and to share images among multiple teams.

“Registry” versus “Re­pos­it­ory”.

A re­pos­it­ory is a place where data is actually stored. A registry is a col­lec­tion of pointers to that data.

For example, a library’s card catalog is the registry you would consult to find the location of the book you need. The library’s actual book­shelves are its re­pos­it­ory.

Re­quire­ments

• Basic knowledge of Docker usage and commands.
• Docker installed and running on your system.
• An internet con­nec­tion.

If you set up a self-hosted re­pos­it­ory and choose to make it ac­cess­ible from the internet, you will also need:

• A func­tion­ing domain name (URL).
• An SSL cer­ti­fic­ate.

Setting up a self-hosted Docker Registry

Docker provides a built-in registry server. The registry server runs in a container which you can start with the docker run command.

For example, to start a registry server named “my-registry” the command would be:

sudo docker run -d -p 5000:5000 --name my-registry registry:2

Pushing an image to your self-hosted Registry

The first step to using your self-hosted registry is to tag a Docker image for that registry using the docker tag command:

sudo docker tag [image name] localhost:5000/[image name]

For example, to re-tag the image my-nginx for your self-hosted registry, the command would be:

sudo docker tag my-nginx localhost:5000/my-nginx

You can then push this image to your registry with the command:

sudo docker push localhost:5000/[image name]

To push the image we created in the example above, the command would be:

sudo docker push localhost:5000/my-nginx

Pulling an image from your self-hosted Registry

The command to pull an image from your registry is:

sudo docker pull localhost:5000/[image name]

For example, to pull the image we created in the example above, the command would be:

sudo docker pull localhost:5000/my-nginx

Stopping and deleting your self-hosted Registry

If you make a mistake or simply want to stop and remove the registry you have created, along with all the images stored there, use the command:

sudo docker stop [repository name] && docker rm -v [repository name]

For example, to stop and delete the registry we created above named my-registry the command would be:

sudo docker stop my-registry && docker rm -v my-registry

Allowing outside access to your self-hosted Registry

Before you begin sharing your private registry, you will need to secure access with TLS using an SSL cer­ti­fic­ate.

Create a directory named certs in your Docker root directory. On most systems, this will be the /var/lib/docker directory:

sudo mkdir /var/lib/docker/certs

Name your SSL cer­ti­fic­ate (cert) file domain.crt and your SSL key file domain.key. Place both files into the /var/lib/docker/certs directory.

If you are updating an existing self-hosted registry, you will need to stop it with the command:

sudo docker stop [repository name]

Start (or restart) your self-hosted registry with the command:

sudo docker run -d -p 5000:5000 --restart=always --name my-registry -v `pwd`/certs:/certs -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key registry:2

Accessing your self-hosted registry from another host

To access your registry from another host, use [your domain]:5000/[image name].

For example, to push an image named my-nginx to a registry hosted at example.com first you will need to tag the image:

sudo docker tag my-nginx example.com:5000/my-nginx

You can then push the image with the command:

sudo docker push example.com:5000/ubuntu

To pull the same image from that registry, use the command:

sudo docker pull example.com:5000/ubuntu

Setting up a Docker Hub Re­pos­it­ory

The Docker Hub website is a con­veni­ent place to store and organise your Docker images in the cloud. You can use this site to host your own public or private re­pos­it­ory, manage user access to the re­pos­it­ory, and access the re­pos­it­ory from anywhere online.

Official images

Docker Hub is also an excellent place to browse public Docker images. Be aware that only re­pos­it­or­ies marked “Official” contain the official versions of the images.

Close

We recommend that you only pull and run official Docker images.

Creating a Docker Hub account

To begin, you will need to set up a Docker Hub account. Fill out your account details on the main Docker Hub website and click Sign Up.

Close

Check your email account for a message to complete your account ac­tiv­a­tion, then sign into the site.

Close

Every Docker Hub account can create a number of free public re­pos­it­or­ies. Each account also comes with one free private re­pos­it­ory. You can purchase more private re­pos­it­or­ies for a monthly fee.

Setting up an or­gan­isa­tion and teams

Docker Hub lets you set up or­gan­isa­tions and teams in order to manage a number of users. This is con­veni­ent if you have several different groups of people, and you need to manage their per­mis­sions sep­ar­ately.

The three access levels are:

• Read (can only pull images, not push them)
• Write (can both pull and push images)
• Admin (can pull and push images, as well as add and delete users)

Creating an Or­gan­isa­tion

On the main Docker Hub Dashboard, click Create Or­gan­isa­tion.

Close

Fill out the or­gan­isa­tion’s details, then click Create.

Close

Every or­gan­isa­tion starts out with one default team, called Owners. You are auto­mat­ic­ally added to Owners when you create the or­gan­isa­tion.

To add someone else to Owners, fill out their Docker Hub username and click the blue +.

Close

Setting your or­gan­iz­a­tion to Public or Private

Or­gan­isa­tions are Public by default. To set your or­gan­iz­a­tion to Private, on the main or­gan­isa­tion page click Settings.

Close

Click Private, then click Save.

Close

Adding a team

To add a team, select your or­gan­isa­tion name from the drop-down menu (if it is not already selected) and click Teams.

Close

On the Teams page, click Add Team.

Close

Fill out the team name and de­scrip­tion, then click Add.

Close

Creating a Docker Hub Re­pos­it­ory

From the Docker Hub dashboard, click Create Re­pos­it­ory.

Close

Fill out the re­pos­it­ory details (be sure to set the Vis­ib­il­ity drop-down to either public or private), then click Create.

Close

On the next page you will find details about your new re­pos­it­ory, including the docker pull command for your images.

Close

Setting Re­pos­it­ory Team Access

To set access to your re­pos­it­ory by team, click Col­lab­or­at­ors.

Close

In our example, we have two teams:

• The QA de­part­ment jdoesoft­ware­qa which needs read (but not write) access to the images.
• The de­velopers jdoesoft­ware­dev who need both read and write access to the images.

There is no need for QA to push updated images to the re­pos­it­ory, and we want to prevent them doing this by accident. However, the de­velopers will need full access to the re­pos­it­ory.

For security reasons, it is a good idea to sort all of your Docker Hub users into at least two groups: one with read-only access, and one with read/write access.

To set a team’s access, select the team and access level from the drop-down menus, then click Add Team.

Close

Accessing your Docker Hub Re­pos­it­ory from the command line

To access your Docker Hub re­pos­it­ory from the command line, you must first au­then­tic­ate with Docker Hub using the login you created on the website:

sudo docker login

You will be asked to provide your Docker Hub login name, password, and email address.

Close

Once you have logged in, you will be able to access your Docker Hub re­pos­it­ory with the docker push and docker pull commands.

Pushing an image to your Docker Hub Re­pos­it­ory

To upload (push) an image to your Docker Hub re­pos­it­ory, you must first prepare the image. It will need:

• Your Docker Hub username or the name of your Docker Hub or­gan­isa­tion.
• The name of your Docker Hub re­pos­it­ory.
• Optional: A version tag. (If no tag is specified, it will default to “latest.”)

You can rename an existing image using the command:

sudo docker tag [existing image name or ID] [Docker Hub username or organisation]/[repository name]:[tag]

For example, if Docker Hub user jdoe wanted to upload an image currently named my-ubuntu-test to a Docker Hub re­pos­it­ory named ubuntu-test and tag it version 1.0, the image would first have to be renamed with the command:

sudo docker tag my-ubuntu-test jdoe/ubuntu-test:1.0

If jdoe is planning to push to the re­pos­it­ory under the jdoesoft­ware or­gan­isa­tion, then the command will be:

sudo docker tag my-ubuntu-test jdoesoftware/ubuntu-test:1.0

You can verify that the image was renamed correctly by listing all of the Docker images on your system with the command:

sudo docker images

Next, you can push the image to the re­pos­it­ory with the command:

sudo docker push [Docker Hub username or organisation name]/[repository name]:[tag]

To push the image we renamed in the previous example, the command would be:

sudo docker push jdoe/ubuntu-test:1.0

Or:

sudo docker push jdoesoftware/ubuntu-test:1.0

To verify that the image was pushed to Docker Hub, go to the Docker Hub dashboard and click Details for your re­pos­it­ory.

Close

On the re­pos­it­ory page, click Tags.

Close

This will list the versions that have been pushed to the re­pos­it­ory, along with the Last Updated time.

Close

Pulling an image from your Docker Hub Re­pos­it­ory

The command to pull an image from your Docker Hub re­pos­it­ory is shown on the re­pos­it­ory page on the Docker Hub website.

Close

The command is:

sudo docker pull [your Hub username or organisation name]/[your Hub repository name]:[tag]

For example, to pull the image jdoe/ubuntu-test:1.0 which we pushed to the Hub in the section above, the command would be:

sudo docker pull jdoe/ubuntu-test:1.0

Or:

sudo docker pull jdoesoftware/ubuntu-test:1.0

You can verify that the image was renamed correctly by listing all of the Docker images on your system with the command:

sudo docker images