DevDocs v1.0

Docker Registry Guide

Learn how Docker registries work, how to use private registries, and where to store container images.

Docker Registry Guide

Docker images become truly useful when they can be shared, distributed, and deployed across multiple environments.

Docker registries provide centralized storage for container images and act as the source of truth for deployments.

Whether you're working on a personal project or managing enterprise infrastructure, understanding registries is an essential Docker skill.

What is a Docker Registry?

A Docker registry is a service that stores and distributes Docker images.

Think of a registry as a package repository for containers.

Example workflow:

Build Image
     │
     ▼
Push to Registry
     │
     ▼
Pull from Registry
     │
     ▼
Deploy Anywhere

Instead of rebuilding images on every machine, you build once and distribute through a registry.

Docker Hub

Docker Hub is Docker's default public registry.

Example:

docker pull nginx

Docker automatically downloads:

docker.io/library/nginx

from Docker Hub.

Docker Hub provides:

  • Public repositories
  • Private repositories
  • Automated builds
  • Team collaboration
  • Image versioning

For most beginners, Docker Hub is the first registry they use.

Registry vs Repository

These terms are often confused.

Registry

The overall image hosting platform.

Examples:

Docker Hub
GitHub Container Registry
Amazon ECR
Google Artifact Registry
Azure Container Registry

Repository

A collection of image versions.

Example:

john/my-app

Inside that repository:

john/my-app:v1.0
john/my-app:v1.1
john/my-app:v2.0

Each tag represents a different image version.

Understanding Image References

A complete image reference looks like:

registry/repository:tag

Example:

docker.io/library/nginx:latest

Components:

docker.io     → Registry
library/nginx → Repository
latest        → Tag

Docker often hides the registry portion when using Docker Hub.

Public Registries

Public registries allow anyone to download images.

Examples:

Docker Hub
GitHub Container Registry (GHCR)
Quay.io

Advantages:

  • Easy sharing
  • Community access
  • Open-source distribution

Disadvantages:

  • Public visibility
  • Potential rate limits
  • Limited privacy

Private Registries

Private registries restrict image access.

Common use cases:

  • Internal applications
  • Proprietary software
  • Enterprise deployments

Benefits:

  • Better security
  • Access control
  • Compliance requirements

Many organizations use private registries exclusively.

Docker Hub

Best for:

  • Learning Docker
  • Open-source projects
  • Small teams

GitHub Container Registry

Best for:

  • GitHub-based projects
  • GitHub Actions workflows

Image format:

ghcr.io/username/project

Amazon Elastic Container Registry (ECR)

Best for:

  • AWS workloads
  • ECS
  • EKS

Image format:

account-id.dkr.ecr.region.amazonaws.com/my-app

Azure Container Registry (ACR)

Best for:

  • Azure deployments
  • AKS clusters

Google Artifact Registry

Best for:

  • Google Cloud
  • GKE deployments

Logging Into a Registry

Before pushing images, authenticate.

Example:

docker login

For custom registries:

docker login registry.example.com

Successful login:

Login Succeeded

Docker stores credentials locally for future use.

Pushing Images

Tag the image:

docker tag my-app registry.example.com/my-app:v1

Push:

docker push registry.example.com/my-app:v1

Docker uploads image layers to the registry.

Pulling Images

Download an image:

docker pull registry.example.com/my-app:v1

Verify:

docker images

The image is now available locally.

Running a Private Registry

Docker provides an official registry image.

Launch a registry:

docker run -d \
  -p 5000:5000 \
  --name registry \
  registry:2

Registry endpoint:

http://localhost:5000

You now have a self-hosted registry.

Using a Local Registry

Tag an image:

docker tag my-app localhost:5000/my-app

Push:

docker push localhost:5000/my-app

Pull:

docker pull localhost:5000/my-app

Useful for:

  • Testing
  • Local development
  • Air-gapped environments

Image Versioning

Always use meaningful tags.

Avoid relying solely on:

latest

Prefer:

v1.0.0
v1.1.0
v2.0.0

Benefits:

  • Easier rollbacks
  • Predictable deployments
  • Clear release history

Registry Security

Images should be treated as software artifacts.

Best practices include:

  • Require authentication
  • Use HTTPS
  • Scan images regularly
  • Remove outdated images
  • Enforce access controls

Security should apply to both public and private registries.

Image Scanning

Many registries support vulnerability scanning.

Benefits:

  • Detect outdated packages
  • Identify security risks
  • Improve compliance

Scanning should become part of your deployment pipeline.

Registry Cleanup

Unused images consume storage.

Over time:

v1.0
v1.1
v1.2
v1.3
v1.4

may accumulate.

Regular cleanup helps:

  • Reduce storage costs
  • Improve organization
  • Simplify maintenance

Always retain important production releases.

Registries in CI/CD

Most modern pipelines follow this workflow:

Developer Pushes Code
          │
          ▼
CI Pipeline
          │
          ▼
Build Docker Image
          │
          ▼
Push to Registry
          │
          ▼
Deploy Application

The registry becomes the central source for deployments.

Common Commands

Login:

docker login

Tag image:

docker tag my-app my-registry/my-app:v1

Push image:

docker push my-registry/my-app:v1

Pull image:

docker pull my-registry/my-app:v1

Logout:

docker logout

Best Practices

Use Versioned Tags

Prefer:

v1.0.0
v1.1.0
v2.0.0

over:

latest

Secure Private Registries

Enable authentication and encryption.

Scan Images

Review vulnerabilities before deployment.

Automate Publishing

Use CI/CD pipelines whenever possible.

Remove Unused Images

Maintain a clean registry.

Summary

Docker registries provide centralized storage and distribution for container images.

Key concepts include:

  • Registries store images
  • Repositories organize versions
  • Tags identify releases
  • Public and private registries serve different needs
  • Registries integrate naturally with CI/CD workflows

Whether you use Docker Hub, GitHub Container Registry, Amazon ECR, or a self-hosted solution, registries are a critical part of modern container-based deployments.