Docker Hub and Registry

Docker Hub and Registry

What is a Registry?

A Docker Registry is a storage and distribution system for Docker images. When you run docker pull nginx, Docker contacts a registry to download the image.

Docker Hub (hub.docker.com) is the default public registry - it's free to use and hosts millions of images.

Types of Images on Docker Hub

docker login - Log Into a Registry

# Login to Docker Hub
docker login

# Login with username
docker login -u irfanaslam

# Login with username and password (not recommended - password visible in shell history)
docker login -u irfanaslam -p mypassword

# Login to a private registry
docker login registry.example.com

# Login with a token/password from stdin (secure)
echo "mytoken" | docker login -u irfanaslam --password-stdin

# Login to Amazon ECR
aws ecr get-login-password --region us-east-1 | docker login \
  --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com

docker logout - Log Out

# Logout from Docker Hub
docker logout

# Logout from a specific registry
docker logout registry.example.com

docker pull - Download an Image

# Pull latest version
docker pull nginx

# Pull a specific version
docker pull nginx:1.25

# Pull from Docker Hub by username
docker pull irfanaslam/my-app:1.0

# Pull from a private registry
docker pull registry.example.com/my-app:1.0

# Pull from Amazon ECR
docker pull 123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest

# Pull all tags of an image
docker pull --all-tags nginx

# Pull for a specific platform
docker pull --platform linux/amd64 nginx

docker push - Upload an Image to Registry

Before pushing, you must:

1. Be logged in (docker login)
2. Tag your image with your Docker Hub username

# Tag your image for Docker Hub
docker tag my-app:1.0 irfanaslam/my-app:1.0

# Push to Docker Hub
docker push irfanaslam/my-app:1.0

# Push all tags
docker push --all-tags irfanaslam/my-app

# Push to a private registry
docker push registry.example.com/my-app:1.0

# Push to Amazon ECR
docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest

docker tag - Tag an Image

Creates an alias for an image, usually before pushing.

# Tag to prepare for push to Docker Hub
docker tag my-local-app irfanaslam/my-app:1.0
docker tag my-local-app irfanaslam/my-app:latest

# Tag to point to a private registry
docker tag my-app registry.example.com/my-app:production

# Re-tag an existing image
docker tag nginx:1.25 my-nginx:stable

# Add multiple tags
docker tag my-app:1.0 irfanaslam/my-app:1.0
docker tag my-app:1.0 irfanaslam/my-app:latest

docker search - Search Docker Hub

# Search for an image
docker search nginx

# Search and filter official images only
docker search --filter "is-official=true" nginx

# Search images with at least 100 stars
docker search --filter "stars=100" nginx

# Limit results
docker search --limit 10 python

# Custom format
docker search --format "table {{.Name}}\t{{.StarCount}}\t{{.IsOfficial}}" nginx

Example output:

NAME         DESCRIPTION                   STARS   OFFICIAL   AUTOMATED
nginx        Official build of Nginx.      19482   [OK]
bitnami/nginx Bitnami nginx Docker Image   180                [OK]

Full Workflow - Build, Tag, Push

# Step 1: Build your image
docker build -t my-app:1.0 .

# Step 2: Tag it with your Docker Hub username
docker tag my-app:1.0 irfanaslam/my-app:1.0

# Step 3: Login
docker login -u irfanaslam

# Step 4: Push
docker push irfanaslam/my-app:1.0

# Step 5: Anyone can now pull it
docker pull irfanaslam/my-app:1.0

Running a Private Registry

You can host your own Docker registry using the official registry image.

# Run a local private registry on port 5000
docker run -d \
  --name my-registry \
  -p 5000:5000 \
  -v registry-data:/var/lib/registry \
  --restart always \
  registry:2

# Tag image for local registry
docker tag my-app:1.0 localhost:5000/my-app:1.0

# Push to local registry (no login needed)
docker push localhost:5000/my-app:1.0

# Pull from local registry
docker pull localhost:5000/my-app:1.0

# List all images in local registry
curl http://localhost:5000/v2/_catalog

Other Popular Registries

Commands Quick Reference