Registries, Docker Hub, Private Registries, Authentication, Credential Stores, Push/Pull, and Distribution: Configuration, Design Choices, and Tradeoffs

1. Docker Hub versus self-hosted/private registry

A hosted registry shifts control-plane and storage operations to a provider; a self-hosted registry gives your organization more direct control and more operational responsibility. The protocol can still be OCI/Docker Distribution-compatible in both cases.

2. Credential helper/store versus inline or plaintext credentials

The best client pattern is a credential helper or platform-native keychain with revocable, scoped credentials. Docker Desktop configures native storage automatically. Standalone CLI users can set credsStore globally or credHelpers for specific registries. Without either, Docker can store base64-encoded credentials in config.json; base64 is representation, not encryption.

{
  "credsStore": "secretservice",
  "credHelpers": {
    "registry.internal.example": "pass"
  }
}

Do not copy that example blindly. The helper binary must exist, be trusted, and match the host platform. In CI, a short-lived token delivered through the CI secret mechanism is usually better than a long-lived password baked into a script or image.

3. Public versus private repository is an authorization decision

Public content reduces pull-friction but expands who can retrieve the bytes. Private content requires authorization and therefore introduces credential distribution and availability concerns. Neither visibility mode proves artifact integrity. Consumers still need digest identity and, where policy requires, provenance/signature/scan evidence.

Repository namespace design also matters. Avoid one broad publisher credential that can overwrite every team repository. Prefer scoped identities and separate promotion permissions where the registry/provider supports them.

4. Local development HTTP versus production TLS

Loopback HTTP can be acceptable for a disposable single-host exercise because there is no untrusted network hop. Shared/private production registries should use TLS with a CA trusted by the Docker daemon and suitable access control. “It is on our LAN” is not a substitute for endpoint authentication.

5. Push success, pull policy, and deployment are separate states

docker push changes registry state. It does not notify existing containers, rewrite deployment manifests, or force another Engine to pull. A consumer that uses a mutable tag plus a “missing” policy can keep locally cached content; a consumer that uses an exact digest remains pinned even when a tag moves. Chapter 13's pull-policy model still applies after a registry push.

A release record should therefore preserve at least: human tag, pushed digest, repository, platform/index semantics, promotion timestamp, and the deployment reference that consumers use.

6. Blob reuse improves efficiency but changes how you interpret size and cleanup

Registries address layers/blobs by digest. Several manifests can reference the same blob, so a second push may report existing layers. This saves bandwidth and storage. It also means “delete release B” does not imply all B's layers are unique or immediately removable.

Registry garbage collection is a storage-admin operation. For CNCF Distribution, current documentation describes mark-and-sweep collection and warns against uploads during collection unless the registry is read-only/stopped. Application teams should request retention through registry policy rather than manipulating backend files.

7. Rate limits and retention are provider policy, not protocol guarantees

Docker Hub's current documented six-hour pull limits are 100 for unauthenticated users per IPv4/IPv6-/64 and 200 for authenticated Personal users; paid authenticated plans are documented as unlimited subject to fair use. A different registry can have different quotas or none at all. Similarly, tag immutability, retention, deletion grace periods, and garbage collection vary by provider.

Record provider policy when it materially affects availability or release operations, but keep the protocol model independent of one vendor.

8. Decision table: choose by trust and operational prerequisites

9. Boundaries that remain distinct

• Client/context vs registry: selecting a Docker context does not authenticate to an arbitrary registry.
• Authentication vs authorization: a valid user/token can still receive DENIED for a repository action.
• TLS trust vs artifact trust: HTTPS proves the endpoint/channel, not that you approve the image's contents.
• Registry storage vs runtime writable layer: pushed layers are image content; container runtime edits are not automatically pushed back.
• Push vs deployment: publishing an image is not the same state as running it.

10. Worked choice: promote one digest through dev, test, and prod

Suppose CI produces app:1.8.0 and pushes digest D. A controlled pipeline can attach human aliases such as candidate and later stable to the same registry content, but deployment records should carry D. Rebuilding separately for production creates a new artifact identity and breaks “build once, promote the same bytes.”

Prerequisites: registry authorization that permits controlled tagging/promotion, immutable digest recording, environment policy, and retained evidence. Verification: resolve every alias at promotion time and prove each one points to the intended digest.

Knowledge check

Official references and version notes

• docker login — authentication, --password-stdin, Docker Desktop native keychains, credsStore, and per-registry credHelpers.
• docker image push — repository naming, layer reuse, push progress, and digest output.
• docker image pull — pull-by-tag versus pull-by-digest and registry-qualified references.
• Registry certificates — platform-specific CA/client-certificate configuration and TLS verification.
• Docker daemon: insecure registries — why plaintext/untrusted registries are testing-only and why trusted CA configuration is preferred.
• Docker Hub pull usage and limits — current rate-limit behavior and authentication attribution.
• CNCF Distribution Registry — current Registry v3 documentation and local-registry workflow.
• Registry v2 token authentication — 401 challenge, token service, repository scope, Bearer token, and retry flow.
• Distribution HTTP API V2 — manifests, blobs, uploads, errors, and digest-addressed operations.
• Deploying Distribution Registry — local development registry, production TLS/auth expectations, and storage.
• Registry garbage collection — shared blobs, reference-aware deletion, mark/sweep behavior, and read-only guidance.
• OCI Distribution Specification v1.1.1 — latest OCI Distribution Specification release used as the standards baseline.
• Distribution Registry v3.1.1 — current stable registry release used as the local-lab baseline.
• Docker Engine 29 release notes — Engine 29.8.1 baseline used when authoring this chapter.
• Buildx releases, BuildKit releases, and Compose releases — current build/orchestration tool release history.