Docker Registry and Docker Hub Explained — Push, Pull and Publish Images

# Docker image names follow a predictable pattern:
# [registry-host]/[namespace]/[repository]:[tag]
#
# Let's break down some real examples:

# 1. Official Docker Hub image (short form — Docker fills in the rest automatically)
docker pull nginx
# Docker expands this to: docker.io/library/nginx:latest

# 2. A community image on Docker Hub — username/repository:tag
docker pull bitnami/postgresql:15.4.0
# registry-host = docker.io (default)
# namespace     = bitnami
# repository    = postgresql
# tag           = 15.4.0

# 3. An image on a private registry (e.g. your company's internal registry)
docker pull registry.mycompany.com/backend/payments-service:v3.1
# registry-host = registry.mycompany.com
# namespace     = backend
# repository    = payments-service
# tag           = v3.1

# 4. Check what images you already have locally
docker images
# This shows your local image cache — images already pulled from a registry

# ── STEP 1: Write a simple Dockerfile for our demo app ──────────────────────
# Create a file called Dockerfile in an empty folder with these contents:

cat > Dockerfile << 'EOF'
# Start from an official, minimal Node.js base image
FROM node:20-alpine

# Set the working directory inside the container
WORKDIR /app

# Copy our simple server file into the container
COPY server.js .

# Tell Docker which port this app listens on (documentation only)
EXPOSE 3000

# The command that runs when the container starts
CMD ["node", "server.js"]
EOF

# Create the tiny Node.js server it references
cat > server.js << 'EOF'
const http = require('http');
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from Docker Hub! Version 1.0\n');
});
server.listen(3000, () => console.log('Server running on port 3000'));
EOF

# ── STEP 2: Build the image locally ─────────────────────────────────────────
# Replace 'yourDockerHubUsername' with your actual Docker Hub username
docker build --tag yourDockerHubUsername/hello-web-server:v1.0 .
# --tag gives our image its Docker Hub address from the very start
# The dot (.) means 'use the Dockerfile in the current directory'

# ── STEP 3: Log in to Docker Hub ────────────────────────────────────────────
docker login
# Docker will prompt for your username and password
# After success it caches a token in ~/.docker/config.json

# ── STEP 4: Push the image to Docker Hub ────────────────────────────────────
docker push yourDockerHubUsername/hello-web-server:v1.0
# Docker uploads each layer of the image separately
# Layers that already exist on Docker Hub are skipped (they show 'Layer already exists')

# ── STEP 5: Pull it back down on any machine to verify it worked ─────────────
docker pull yourDockerHubUsername/hello-web-server:v1.0

# ── STEP 6: Run it to confirm everything works ───────────────────────────────
docker run --publish 3000:3000 yourDockerHubUsername/hello-web-server:v1.0
# Visit http://localhost:3000 in your browser — you should see the Hello message

# ── Run your own private Docker registry locally in 60 seconds ──────────────
# This uses Docker's official 'registry' image — it IS a registry running inside Docker

# Start the registry container on port 5000
docker run \
  --detach \
  --publish 5000:5000 \
  --name my-private-registry \
  --restart always \
  --volume registry-image-data:/var/lib/registry \
  registry:2
# --detach            = run in background
# --publish 5000:5000 = expose registry on localhost port 5000
# --name              = friendly name so we can reference it easily
# --restart always    = auto-restart if the machine reboots
# --volume            = persist images to a named Docker volume (survive container restarts)

# ── Now push an image to YOUR local registry ─────────────────────────────────

# First, tag an existing local image with the local registry address as the prefix
docker tag yourDockerHubUsername/hello-web-server:v1.0 \
            localhost:5000/hello-web-server:v1.0
# 'localhost:5000' IS the registry address — Docker reads it and knows where to push

# Push to the local registry (no login needed for localhost)
docker push localhost:5000/hello-web-server:v1.0

# ── Query the registry's API to see what's stored ────────────────────────────
curl http://localhost:5000/v2/_catalog
# Returns a JSON list of all repositories stored in your local registry

curl http://localhost:5000/v2/hello-web-server/tags/list
# Returns all tags for the hello-web-server repository

# ── Pull from your local registry on the same machine (or same network) ───────
docker pull localhost:5000/hello-web-server:v1.0

# ── Check your current Docker Hub rate-limit status ─────────────────────────
# Pull a temporary token (anonymous request mirrors what an unauthenticated runner sees)
RATE_LIMIT_TOKEN=$(curl --silent \
  "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

# Use that token to hit Docker Hub and read the rate-limit headers
curl --silent --head \
  --header "Authorization: Bearer ${RATE_LIMIT_TOKEN}" \
  https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest \
  | grep --ignore-case ratelimit
# Look for RateLimit-Limit and RateLimit-Remaining in the response headers

# ── Configure a pull-through cache registry ──────────────────────────────────
# Add this to /etc/docker/daemon.json on EACH CI runner machine:
# This tells Docker: 'before going to docker.io, check our cache first'

cat > /etc/docker/daemon.json << 'EOF'
{
  "registry-mirrors": ["http://registry-cache.internal.mycompany.com:5000"]
}
EOF

# Restart Docker to pick up the new config
sudo systemctl restart docker

# ── Set up the pull-through cache registry itself (run this once on a central server) ──
docker run \
  --detach \
  --publish 5000:5000 \
  --name docker-hub-pull-cache \
  --restart always \
  --volume pull-cache-data:/var/lib/registry \
  --env REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
  registry:2
# REGISTRY_PROXY_REMOTEURL tells the registry to act as a transparent proxy/cache
# for Docker Hub. First pull fetches from Docker Hub; every subsequent pull is served
# from local cache — no rate-limit hit

# ── Verify the daemon picked up the mirror ───────────────────────────────────
docker info | grep -A3 "Registry Mirrors"