Container Regisitries

Docker Registries

You’ve built a Docker image. Now what?

If you want to share it with your team, with the public, or just between your own machines, you need a registry. Registries are where images live when they’re not on your local machine. Think of them as the app store for containers.

This article covers how registries work, the different types available, and how to push and pull your own images.

What’s Inside a Registry?

A registry is organised in a hierarchy.

At the top level, there are users or organisations. Each user has a space in the registry where their images live.

Under a user are repositories. A repository represents a single image and all of its variants. For example, if you build a web server image, you might have one repository for it. That repository can contain the latest version, a v1.0 release, a beta build, or something else. These are all tags identifing each image.

The full name of an image in a registry looks like this:

[registry-hostname]/[username]/[repository]:[tag]

For an image on Docker Hub from a user called myuser, with the name mywebserver and the tag v1.0:

myuser/mywebserver:v1.0

Docker Hub is the default registry, so you don’t need to include the hostname for images stored there.

Docker Hub

Docker Hub is the default public registry and the largest one in the world. When you run docker pull nginx, Docker fetches that image from Docker Hub automatically.

Anyone can create a free account and push images. Official images from organisations like Nginx, PostgreSQL, Ubuntu, and Docker themselves, sit alongside community-contributed images.

Public and Private Repositories

Within Docker Hub (and most registries), repositories can be either public or private.

A public repository is visible to everyone. Anyone can pull the images inside it. Only you can push to it.

A private repository is hidden from public view. Only authorised users can see or pull the images. This is useful for proprietary applications or images containing custom configuration.

Docker Hub’s free tier includes one private repository. Paid plans allow more.

Other Registries

Docker Hub isn’t your only option.

Cloud-hosted private registries like Azure Container Registry (ACR) and Amazon Elastic Container Registry (ECR) are designed for organisations that want a private registry integrated with their cloud infrastructure.

Self-hosted registries like Harbor and Docker’s own registry image let you run your own registry on your own hardware. No cloud dependency, no ongoing subscription.

Self-hosting is worth considering if you want images to stay within your own network, or if you just don’t want to rely on external services.

Running Your Own Local Registry

Docker provides a minimal registry as a container image. Getting it running is straightforward:

docker run -d -p 5000:5000 --name registry registry:latest

This runs the registry on port 5000. It’s now available at localhost:5000.

Because this registry isn’t set up with TLS, you’ll need to tell Docker to allow it as an insecure registry. On Docker Desktop for Windows, go to Settings → Docker Engine and add this:

"insecure-registries": ["localhost:5000"]

On Mac or Linux, edit /etc/docker/daemon.json and add the same entry.

Once that’s done, you can push images to your local registry and pull from it just like you would with Docker Hub.

Tagging Images for a Registry

Before you can push an image, you need to tag it so Docker knows which registry it belongs to. The docker tag command does this:

docker tag mywebserver localhost:5000/mywebserver

The new tag includes the registry address as a prefix. Docker uses this prefix to determine where to push or pull the image.

To tag an image for Docker Hub:

docker tag mywebserver myusername/mywebserver:latest

The repository name is the combination of your username and the image name, separated by a slash.

Authenticating with Docker Hub

To push to Docker Hub, you need to authenticate. Docker Hub uses Personal Access Tokens (PATs). This is a string that works like a password, but with configurable permissions and expiry.

To create one, log in to Docker Hub, go to Account Settings → Personal Access Tokens, and generate a new token with Read & Write permissions.

Then log in from your terminal:

docker login -u yourusername

Docker prompts you for a password. Paste your token here. You’ll see a Login Succeeded message.

To log out when you’re done:

docker logout

Pushing an Image

Once you’re logged in and the image is tagged correctly, pushing is simple:

docker push myusername/mywebserver:latest

Docker uploads each layer individually. If you’ve already pushed some layers previously, perhaps as part of an earlier version, those layers are skipped. Only new layers are uploaded. This is layer caching working in your favour.

Once pushed, the image is available in your Docker Hub repository for anyone (or just authorised users, if it’s private) to pull.

Pulling from a Registry

You’ve been doing this all along with docker run and docker pull. For Docker Hub:

docker pull nginx:latest

For your local registry:

docker pull localhost:5000/mywebserver

For any other registry, include the full hostname:

docker pull myregistry.example.com/mywebserver:v1.0

Where to Go Next

The full course walks through setting up Docker Hub accounts, self-hosted registries, and integrating registries with Docker Compose:

Watch the free YouTube course → COMING SOON

Enrol in the full Udemy course → COMING SOON