Setting Up a Docker Repos­i­to­ry

Learn how to store your Docker images, either with a self-hosted local registry, or using a Docker Hub repos­i­to­ry. This will allow you to store and organize your Docker images, and to share images among multiple teams.

“Registry” versus “Repos­i­to­ry”.

A repos­i­to­ry 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 repos­i­to­ry.

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 repos­i­to­ry and choose to make it ac­ces­si­ble from the internet, you will also need:

• A func­tion­ing domain name (URL).
• An SSL cer­tifi­cate.

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­tifi­cate.

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­tifi­cate (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 Repos­i­to­ry

The Docker Hub website is a con­ve­nient place to store and organize your Docker images in the cloud. You can use this site to host your own public or private repos­i­to­ry, manage user access to the repos­i­to­ry, and access the repos­i­to­ry from anywhere online.

Official images

Docker Hub is also an excellent place to browse public Docker images. Be aware that only repos­i­to­ries 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­ti­va­tion, then sign into the site.

Close

Every Docker Hub account can create a number of free public repos­i­to­ries. Each account also comes with one free private repos­i­to­ry. You can purchase more private repos­i­to­ries for a monthly fee.

Setting up an or­ga­ni­za­tion and teams

Docker Hub lets you set up or­ga­ni­za­tions and teams in order to manage a number of users. This is con­ve­nient if you have several different groups of people, and you need to manage their per­mis­sions sep­a­rate­ly.

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­ga­ni­za­tion

On the main Docker Hub Dashboard, click Create Or­ga­ni­za­tion.

Close

Fill out the or­ga­ni­za­tion’s details, then click Create.

Close

Every or­ga­ni­za­tion starts out with one default team, called Owners. You are au­to­mat­i­cal­ly added to Owners when you create the or­ga­ni­za­tion.

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

Close

Setting your or­ga­ni­za­tion to Public or Private

Or­ga­ni­za­tions are Public by default. To set your or­ga­ni­za­tion to Private, on the main or­ga­ni­za­tion page click Settings.

Close

Click Private, then click Save.

Close

Adding a team

To add a team, select your or­ga­ni­za­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 Repos­i­to­ry

From the Docker Hub dashboard, click Create Repos­i­to­ry.

Close

Fill out the repos­i­to­ry details (be sure to set the Vis­i­bil­i­ty drop-down to either public or private), then click Create.

Close

On the next page you will find details about your new repos­i­to­ry, including the docker pull command for your images.

Close

Setting Repos­i­to­ry Team Access

To set access to your repos­i­to­ry by team, click Col­lab­o­ra­tors.

Close

In our example, we have two teams:

• The QA de­part­ment jdoe­soft­ware­qa which needs read (but not write) access to the images.
• The de­vel­op­ers jdoe­soft­ware­dev who need both read and write access to the images.

There is no need for QA to push updated images to the repos­i­to­ry, and we want to prevent them doing this by accident. However, the de­vel­op­ers will need full access to the repos­i­to­ry.

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 Repos­i­to­ry from the command line

To access your Docker Hub repos­i­to­ry from the command line, you must first au­then­ti­cate 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 repos­i­to­ry with the docker push and docker pull commands.

Pushing an image to your Docker Hub Repos­i­to­ry

To upload (push) an image to your Docker Hub repos­i­to­ry, you must first prepare the image. It will need:

• Your Docker Hub username or the name of your Docker Hub or­ga­ni­za­tion.
• The name of your Docker Hub repos­i­to­ry.
• 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 organization]/[repository name]:[tag]

For example, if Docker Hub user jdoe wanted to upload an image currently named my-ubuntu-test to a Docker Hub repos­i­to­ry 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 repos­i­to­ry under the jdoe­soft­ware or­ga­ni­za­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 repos­i­to­ry with the command:

sudo docker push [Docker Hub username or organization 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 repos­i­to­ry.

Close

On the repos­i­to­ry page, click Tags.

Close

This will list the versions that have been pushed to the repos­i­to­ry, along with the Last Updated time.

Close

Pulling an image from your Docker Hub Repos­i­to­ry

The command to pull an image from your Docker Hub repos­i­to­ry is shown on the repos­i­to­ry page on the Docker Hub website.

Close

The command is:

sudo docker pull [your Hub username or organization 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