Module 06: Registries
Distributing Images

Go back to Module 00 for a moment. The very first diagram showed three actors: the Docker client (your CLI), the Docker daemon (the engine running on your machine), and a registry (the remote store). Every time you ran docker pull nginx back in Module 01, the daemon silently reached out to Docker Hub (that's a registry) and downloaded layers. Sam, like you, has been using registries from day one without thinking about them.

By Module 02 you learned to build images: layers, Dockerfiles, the cache. By Module 05 you could orchestrate full multi-container applications with Compose. But every image stayed local on the machine that built it. Sam hit the wall the moment a teammate asked to run the app too. The second you need to:

• deploy that image to a cloud server or Kubernetes cluster,
• share it with a teammate or a CI pipeline,
• roll back production to a known-good version,

you need to push it to a registry. That's this module.

A registry is a server that stores and distributes image layers. When you push an image, the daemon uploads each layer as a blob identified by its sha256 content hash. When you pull, the daemon downloads only the layers it doesn't already have locally.

That last sentence is important: layers are content-addressed. If two images share a base layer, say both start from python:3.12-slim, that layer is stored once in the registry and once on every machine that has pulled either image. A push doesn't re-upload layers that are already there. Docker checks each layer's digest against the registry before uploading; only genuinely new or changed layers travel over the wire.

Docker Hub is the default public registry. When you type docker pull nginx without specifying a host, the daemon talks to registry-1.docker.io. The registry protocol itself is an open standard (OCI Distribution Spec), which is why every major cloud and self-hosted solution speaks the same push/pull API.

You will encounter these on the job. Know the trade-offs.

Before you can push, you need to understand the full image reference format. Every image reference has the same anatomy:

The :latest trap: a callback to Module 01

In Module 01 you were told never to rely on :latest for anything important. Here is the full reason: :latest is just a mutable tag. It points to whatever manifest was pushed most recently. Push a new version and :latest now means something different. Two machines that pull :latest at different times can get completely different images with no warning.

Here is the moment Sam has been building toward. Four commands cover the entire publish flow. They are all together, in order, for a real GHCR example. Read the whole block first, then we break down each step.

# 1. Authenticate: use a Personal Access Token, not your password
echo "<YOUR_GITHUB_PAT>" | docker login ghcr.io -u <github-username> --password-stdin

# 2. Build your image locally (you already know this from Module 02)
docker build -t myapp:1.0 .

# 3. Tag it with the full registry reference
docker tag myapp:1.0 ghcr.io/<github-username>/myapp:1.0

# 4. Push: only layers the registry doesn't already have are uploaded
docker push ghcr.io/<github-username>/myapp:1.0

# --- on another machine / in CI / in production ---

# 5. Pull the image
docker pull ghcr.io/<github-username>/myapp:1.0

# 6. Run it
docker run -p 8000:8000 ghcr.io/<github-username>/myapp:1.0

Step-by-step explanation

docker login writes an auth token to ~/.docker/config.json. The daemon attaches this token to every push/pull request to that registry host. Always pipe the token via --password-stdin rather than passing it as a CLI argument. Otherwise it appears in your shell history and in ps output on shared machines. Use a Personal Access Token (PAT) or a CI-managed secret, never your account password.

docker tag does not copy or move anything. It creates a second name for the exact same image manifest that already exists locally. The image has one set of layers; it now has two names. Think of it as an alias.

docker push contacts the registry, walks each layer's digest, and asks "do you already have this?" Only missing layers are uploaded. Sam watches the output scroll by and sees something like:

The push refers to repository [ghcr.io/user/myapp]
a3f42e8c1b20: Pushed          ← new layer, uploaded
7d3c1f9a2044: Layer already exists  ← base layer already in registry
e9c3d8b71a11: Layer already exists  ← shared with another image
1.0: digest: sha256:c8f2... size: 1234

docker pull is the reverse: the daemon downloads the manifest, checks which layers it already has locally, and fetches only the missing ones. This is why pulling a second image that shares a base is fast: the base layers are already there.

This is a concept worth mastering. Tags and digests both refer to an image, but they have fundamentally different guarantees.

To pull or reference an image by digest:

# pull by digest: immune to tag mutation
docker pull ghcr.io/user/myapp@sha256:c8f2a91b3d4e7f6082c1a9b5d8e3f2a7b4c6d9e1f3a5b7c9d2e4f6a8b0c1d3e5

# inspect an image's digest locally
docker inspect --format '{{index .RepoDigests 0}}' ghcr.io/user/myapp:1.0

# see the digest returned after a push (last line of push output)
# 1.0: digest: sha256:c8f2... size: 1234

In a Kubernetes deployment manifest, a digest pin looks like this:

# tag alone: mutable, not recommended for prod
image: ghcr.io/user/myapp:1.2.0

# tag + digest: best of both, human-readable AND immutable
image: ghcr.io/user/myapp:1.2.0@sha256:c8f2a91b3d4e7f...

A consistent tagging strategy is something engineering teams set up once and rely on forever. This is what professional CI pipelines look like.

A solid CI pipeline applies multiple tags to the same image on every build. That means a single push produces: a git SHA tag (traceable), a semver tag (releasable), and optionally moves latest. The layers are stored once; multiple tag labels just point to the same manifest. There is no storage penalty.

# CI environment variables (GitHub Actions example)
SHA=$(git rev-parse --short HEAD)    # e.g. a3f42e8
VERSION=1.2.0                         # from package.json / pyproject.toml / tag
REGISTRY=ghcr.io/myorg/myapp

# build once
docker build -t $REGISTRY:$SHA .

# apply additional tags (no re-build, just aliases)
docker tag $REGISTRY:$SHA $REGISTRY:$VERSION
docker tag $REGISTRY:$SHA $REGISTRY:latest

# push all three: same layers, three manifest pointers
docker push $REGISTRY:$SHA
docker push $REGISTRY:$VERSION
docker push $REGISTRY:latest

Pushing an image to a registry makes it available to anyone (or any system) that pulls it. Before you do that in a production context, you want to know two things: does this image contain known vulnerabilities? and can the recipient trust that this image came from you and hasn't been tampered with? That's vulnerability scanning and image signing, respectively.

Vulnerability scanning

Every layer in your image contains OS packages, language runtimes, and libraries. Any of those can have published CVEs. A scanner compares the image's bill of materials (SBOM) against a vulnerability database and reports what it finds.

# quick overview: shows CVE count by severity
docker scout quickview ghcr.io/user/myapp:1.0

# full CVE list
docker scout cves ghcr.io/user/myapp:1.0

# compare two versions to see what changed
docker scout compare ghcr.io/user/myapp:1.0 --to ghcr.io/user/myapp:1.1

Trivy (by Aqua Security) is the most widely deployed open-source scanner. It runs as a single binary or container, scans local images or remote references, and integrates easily into CI pipelines:

# scan a local image
trivy image myapp:1.0

# fail CI if any CRITICAL CVEs are found
trivy image --exit-code 1 --severity CRITICAL myapp:1.0

Image signing and provenance (intro)

Signing answers: "is this image actually what it claims to be, and did it come from the pipeline I trust?" The CNCF tool cosign (part of the Sigstore project) attaches a cryptographic signature to an image's digest in the registry. A deploy pipeline can verify the signature before running a container. If the signature is missing or invalid, the deploy is rejected.

Docker also ships an older, built-in mechanism called Docker Content Trust (DCT), backed by The Update Framework / Notary. Setting DOCKER_CONTENT_TRUST=1 makes the client sign tags on push and refuse to pull any unsigned tag. It predates Sigstore and is largely superseded by cosign in modern pipelines (cosign is keyless, registry-agnostic, and signs the immutable digest rather than the mutable tag), but you will still see DCT referenced in legacy setups.

Attestations go further: they attach machine-readable provenance metadata (which git commit, which CI run, which Dockerfile) to the image in the registry. GitHub Actions can generate these automatically with actions/attest-build-provenance.

Pushing from GitHub Actions

GitHub Actions has a built-in GITHUB_TOKEN that is scoped to the repository and has write access to GHCR for that repo. You don't need to create a separate secret; just log in with it. Sam's next step is wiring this into CI so the push happens on every commit:

- name: Log in to GHCR
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

- name: Build and push
  uses: docker/build-push-action@v5
  with:
    context: .
    push: true
    tags: |
      ghcr.io/${{ github.repository_owner }}/myapp:${{ github.sha }}
      ghcr.io/${{ github.repository_owner }}/myapp:latest

For other registries (ECR, Docker Hub) you store the credentials as encrypted repository secrets (secrets.DOCKERHUB_TOKEN, etc.) and reference them the same way. Never hard-code tokens in the workflow file itself.

Pulling in production with imagePullSecrets

When Kubernetes pulls a private image, it needs credentials. You create a Kubernetes Secret of type kubernetes.io/dockerconfigjson containing the registry auth, then reference it in your Pod spec under imagePullSecrets. This is a forward reference to the Kubernetes phase, so just know that the registry credential problem you solved locally with docker login has a direct equivalent in every orchestrator.

Self-hosting with registry:2

Running your own registry is genuinely one command. The official registry:2 image is the CNCF Distribution reference implementation: no UI, no RBAC, just the OCI-compliant HTTP API. Useful for air-gapped labs or local testing:

# start a local registry on port 5000, persist data in a volume
docker run -d -p 5000:5000 --name registry -v registry-data:/var/lib/registry registry:2

# tag and push to it
docker tag myapp:1.0 localhost:5000/myapp:1.0
docker push localhost:5000/myapp:1.0

# pull from it on the same machine
docker pull localhost:5000/myapp:1.0

Walk Sam's path yourself. The only way to understand push/pull is to do it and watch only the changed layers travel. This checklist should take 30 to 45 minutes.

• Create a free Docker Hub account at hub.docker.com, or enable GHCR on any GitHub repo (it's free for public repos).
• Run docker login docker.io (or docker login ghcr.io) and verify you get "Login Succeeded".
• Take any local image you built in Modules 02–05. Tag it: docker tag myapp:1.0 <yournamespace>/myapp:1.0.
• Push it: docker push <yournamespace>/myapp:1.0. Watch the output and note which layers say "Pushed" vs "Layer already exists".
• Delete the local image: docker rmi <yournamespace>/myapp:1.0. Then pull it back: docker pull <yournamespace>/myapp:1.0. Confirm it runs.
• Make a trivial one-line change to the app (e.g., edit a string), rebuild, retag as :1.1, and push again. Observe that only the changed layers upload; the base layers say "Layer already exists".
• Find the digest: run docker inspect --format '{{index .RepoDigests 0}}' <image>. Copy the sha256:... and pull by that digest directly.
• Run docker scout quickview <yourimage> (or trivy image <yourimage> if Trivy is installed). Read the CVE summary. Note that even a minimal image may have findings.
• Optional: start a local registry:2 container, push and pull to localhost:5000 to see that the same commands work against a self-hosted registry.