How Docker Repository works

If you have looked into Docker, you will have heard the terms Docker repository and Docker registry and may have wondered what they mean. In this guide, we explain the difference between the two and how to use them effectively.

A Docker repository is a collection of related Docker images that share the same name but have different versions, identified by tags. For example, the official nginx repository contains images tagged nginx:1.27, nginx:latest, nginx:alpine, and so on – all different versions or variants of the same software.

A Docker registry, on the other hand, is the service that hosts and manages repositories. Think of a registry as the server, and a repository as a folder within it.

Each time the software developer releases a new version, they create a new Docker image with the same name but a different tag, and push it to the same repository in the registry.

To assign a version tag to a Docker image at build time, use the -t flag:

$ docker build -t my-app:1.0.0 .

Alternatively, you can tag an existing image using the docker tag command:

$ docker tag <image_name> <image_name>:<tag>

What is a Docker repository for?

A repository provides version control for your container images. Each tag represents a specific version, allowing you and your team to pull exactly the version you need.

Repositories can be hosted on a remote registry to make your application images available to other users and environments. Users with the appropriate permissions can download a copy of any image from the repository using the docker pull command:

$ docker pull <registry>/<repository>:<tag>

Public and private repositories

Repositories can be public or private. Public repositories are accessible by anyone without authentication. There are thousands of public repositories available on Docker Hub, including official images for popular software like Nginx, PostgreSQL, Redis, and Node.js.

To create a private repository, you need to open an account with a registry provider and configure access for your collaborators. The most commonly used registries include:

• Docker Hub: the default registry and the largest public image library
• Amazon ECR (Elastic Container Registry): integrated with AWS services
• GitHub Container Registry (ghcr.io): integrated with GitHub Actions and repositories
• Google Artifact Registry: the successor to the now-retired Google Container Registry

Authenticating to a registry

Each registry has its own authentication system. The standard method is the docker login command.

For Docker Hub, the default authentication method is now a web-based device code flow, which avoids exposing credentials in the terminal:

$ docker login

This will display a one-time code and a URL. Open the URL in your browser, enter the code, and authorize access.

For other registries or for non-interactive environments (such as CI/CD pipelines), use --password-stdin to pass credentials securely:

$ echo $REGISTRY_TOKEN | docker login -u <username> --password-stdin registry.example.com

Note: avoid passing passwords directly as command-line arguments (e.g. docker login -p <password>), as this exposes them in your shell history and system logs.

Once authenticated, you can pull and push images to any repository you have access to.

Docker Hub rate limits

If you pull images from Docker Hub without authenticating, your requests are subject to rate limits: 10 pulls per hour for unauthenticated users, and 100 pulls per hour for free authenticated accounts. All paid plans (Pro, Team, Business) include unlimited pulls. For production environments with multiple nodes, authenticating to Docker Hub or using a registry mirror is recommended to avoid hitting these limits. 

Useful resources

• Docker Hub Repositories documentation
• docker login reference
• docker tag reference

We recommend bookmarking the official Docker documentation – it contains a wealth of free resources for sysadmins and developers.

Repositories, registries, and your infrastructure

We hope this guide has clarified the difference between a Docker repository and a Docker registry, and how to take advantage of both.

Creating an account on a Docker registry allows you to share application images with your team quickly and securely. By tagging each version, you maintain a clear version history that supports rollback and backward compatibility.

Cloud providers such as Google Cloud, Azure, and AWS all offer managed container registries that integrate with their orchestration services (GKE, AKS, ECS). For a deeper look at orchestration, read our articles on Docker vs Kubernetes and how to deploy with Docker.

If you manage containerized environments, remember that a solid backup strategy is essential. Uranium Backup supports backup of virtual machines, databases, and the data that powers your containerized applications.