07 — Container Registries: Where Images Live, Get Tagged, and Ship

"Docker Hub, the website" was how I conflated the registry concept with the product, which hid what a tag actually is. The model that separated them: a registry is a content-addressed storage service for images, and a tag is just a movable pointer — so production should pin digests, not trust :latest. [1][5]

The framing worth holding onto is that registries are the distribution layer of the Docker story. Building an image on my laptop is useless if I can't get it to the server, and copying image files by hand is a nightmare because an image is a manifest plus many layers. A registry solves this with a simple API: push an image up, pull it down anywhere, by name and tag [1].

The registry's job

A registry stores images keyed by name plus an immutable digest (a SHA256 hash of the manifest). On top of that, it lets me attach human-readable tags — 1.2.0, alpine, latest — that point at a digest. The digest is the truth; the tag is a convenience that can be re-pointed at any time [1][5]. That distinction is the source of every tagging best practice and every tagging footgun.

Docker Hub and the alternatives

Docker Hub is Docker's own public registry and the default docker push/pull destination. It hosts "official images" (the vetted nginx, postgres, node images maintained by the upstream projects or Docker), plus public and private user repositories, automated builds linked to source repos, and webhooks [2][3]. When I run docker pull nginx with no registry prefix, Docker Hub is where it comes from.

But Hub is one choice. The major cloud platforms each ship a managed registry tightly integrated with their own ecosystem [4]:

• GitHub Container Registry (GHCR) — natural fit when my CI is GitHub Actions; images live next to the code.
• Amazon ECR — integrated with IAM and ECS/EKS on AWS.
• Google Artifact Registry — the successor to GCR, integrated with GCP.
• Azure Container Registry — the Azure equivalent.

There's also the open-source Distribution registry (the project behind Docker Hub's API) that I can self-host for fully private, air-gapped setups [1]. The choice between them is almost never technical — the registry API is standardized — it's about which cloud I'm already in and where my IAM lives.

Tagging: the label you learn to control

If the digest is truth and the tag is a movable label, then tagging strategy is about which labels I move where, and when. The best practices the roadmap collects all flow from that [5][6]:

• Pin explicit versions in production. my-app:1.2.0 is honest. my-app:latest is ambiguous — it's whatever was last pushed under that name, which means two deploys a week apart can run different code with no version bump [5].
• Use semantic versioning for releases. 1.2.0 conveys breaking/minor/patch; latest conveys nothing.
• Include build metadata in CI tags. Tagging with the git commit hash or build number (1.2.0-abc1234) makes every image traceable back to the exact source that produced it.
• Automate tagging in CI/CD. Manual tagging is where typos and "I forgot to bump it" live. The pipeline should tag on every merge.
• Clean up old tags. Registries accumulate thousands of layers if I let them; most managed registries have lifecycle policies to prune untagged or old images.

The rule I internalized: in dev, :latest is convenient; in anything that resembles production, I pin a real version and treat the tag as a contract.

Runtime configuration: how the image runs

A neighboring idea the roadmap groups with registries is runtime configuration — the options that shape how an image behaves when it starts [7]. These don't change the image; they shape the container produced from it:

• Environment variables (-e KEY=value) — the Twelve-Factor config mechanism.
• Resource limits (--cpus, --memory) — cgroup ceilings, the topic of an earlier post.
• Restart policy (--restart unless-stopped) — whether the daemon brings the container back after a crash or reboot.
• Network and port settings (--network, -p) — covered in the CLI post.
• Logging drivers (--log-driver) — where stdout goes.

The unifying idea: the image is immutable, but the container is shaped at run time by these flags or, more manageably, by a Compose file. The same image can run as a dev container (no limits, logs to the terminal) and a prod container (memory-capped, logs shipped to a central store), purely from runtime config [7].

How I use this

The payoff is a default set of habits. Every stateful project I ship gets pushed to a registry the moment it builds in CI, tagged with the git short SHA plus a semver on release, and the production manifest references that explicit tag — never :latest. I pick the registry that matches the cloud I'm already in, because the IAM and lifecycle tools come for free. And when a deploy behaves differently from the previous one, the first thing I check is the image digest the running container actually resolved to, because the tag is a label and the digest is the truth. Treating tags as movable pointers, not promises, is the one habit that has saved me the most debugging time.

References

[1] Docker, Inc., "Docker Registry," Docker Docs, 2024. [Online]. Available: https://docs.docker.com/registry/

[2] Docker, Inc., "Docker Hub," hub.docker.com, 2024. [Online]. Available: https://hub.docker.com/

[3] Docker, Inc., "Docker Hub repositories," Docker Docs, 2024. [Online]. Available: https://docs.docker.com/docker-hub/repos/

[4] GitHub, "About GitHub Container Registry," GitHub Docs, 2024. [Online]. Available: https://docs.github.com/en/packages/guides/about-github-container-registry

[5] Docker, Inc., "Build, tag, and publish an image," Docker Docs, 2024. [Online]. Available: https://docs.docker.com/get-started/docker-concepts/building-images/build-tag-and-publish-an-image/

[6] S. Preston, "Semantic Versioning 2.0.0," semver.org, 2024. [Online]. Available: https://semver.org/

[7] Docker, Inc., "docker run reference," Docker Docs, 2024. [Online]. Available: https://docs.docker.com/engine/reference/run/