Setting Up a Private Docker Registry with Authentication

A private Docker registry gives your team a controlled place to store and distribute container images without relying entirely on Docker Hub or another public service. It is useful for internal applications, customer deployments, CI/CD pipelines, and images containing proprietary code or configuration.

For an Australian business, the design also needs to account for internet latency, data location, backup connectivity, and privacy obligations. A registry hosted in Sydney may be convenient for a local team, while a Melbourne or Brisbane office pulling images across an NBN connection may need caching and sensible image-retention policies.

Why Run Your Own Container Registry

A registry is more than a folder containing compressed images. It provides an HTTP API that Docker, containerd, Kubernetes, and automation tools use to push, pull, tag, and inspect image layers. A private service can keep internal images out of public repositories and give administrators control over access, retention, and backups.

Self-hosting can also reduce dependency on external rate limits and subscription changes. It is particularly practical when several environments use the same images, such as development, testing, staging, and production. Instead of rebuilding an image on every host, a pipeline publishes one version and deployment systems retrieve that immutable tag.

The trade-off is operational responsibility. You must manage TLS certificates, user authentication, storage capacity, software updates, monitoring, and recovery testing. A registry that works on a developer laptop is not automatically suitable for production workloads.

Choose The Host And Storage

The simplest deployment is a Linux virtual machine running Docker or Podman, with persistent storage attached for registry data. A small internal registry may run comfortably with modest CPU and memory, but storage growth depends on image size, the number of tags, and how often old layers are retained. SSD-backed storage improves upload and download performance when several builds run concurrently.

Choose a hosting location based on the systems that will use the registry. An Australian cloud region can reduce round-trip time for teams in Sydney, Melbourne, or Perth and may make data-residency discussions easier. If the registry is hosted in a local office, consider the reliability of the NBN service, power protection, upload bandwidth, and a second internet connection before treating it as a production dependency.

Use a dedicated DNS name such as registry.example.com, and allocate enough capacity for growth. Storage should be mounted outside the container so that recreating the registry does not remove image data. For cloud deployments, an object-storage backend can provide greater durability than a single virtual disk, though it adds configuration and service costs.

Enable TLS And Authentication

Docker clients expect a secure registry endpoint. Obtain a certificate for the registry hostname from a trusted certificate authority, or use an internal certificate authority whose root certificate is installed on every client. Terminating TLS at Nginx, Caddy, or a cloud load balancer is common, while the registry itself listens on a private network.

The Docker Distribution registry supports basic authentication through an htpasswd file. Create a strong password hash with the Apache utility, store it in a protected directory, and mount it into the registry container. A minimal Compose service might look like this:

services:
  registry:
    image: registry:2
    restart: unless-stopped
    environment:
      REGISTRY_HTTP_ADDR: 0.0.0.0:5000
      REGISTRY_HTTP_SECRET: replace-with-a-long-random-value
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: Private Registry
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
      REGISTRY_STORAGE_DELETE_ENABLED: "true"
    volumes:
      - ./data:/var/lib/registry
      - ./auth:/auth:ro
    networks:
      - registry_net

networks:
  registry_net:

Place the service behind a reverse proxy that handles HTTPS and forwards requests to port 5000. Never expose an unauthenticated registry directly to the internet. Restrict firewall access to known build agents, administration networks, and production hosts where possible.

Basic authentication is acceptable for a controlled environment when it is protected by TLS, but larger teams may need an identity provider, token-based authentication, or a product such as Harbor. Keep credentials out of shell history and pipeline logs. Use separate accounts or robot credentials for automation so that a compromised build job does not expose a personal administrator password.

Push And Pull Images Safely

After DNS and TLS are working, authenticate from a client with:

docker login registry.example.com
docker tag inventory-api:1.4.2 registry.example.com/apps/inventory-api:1.4.2
docker push registry.example.com/apps/inventory-api:1.4.2
docker pull registry.example.com/apps/inventory-api:1.4.2

Use meaningful repository paths and immutable version tags. A tag such as 1.4.2 communicates a release, while a commit SHA provides a precise reference for rollback. Avoid relying on latest in production because it can change without an obvious deployment record.

Build pipelines should authenticate using short-lived or narrowly scoped credentials where possible. Store secrets in the CI platform’s protected secret store and grant push access only to the projects that need it. Runtime hosts generally need pull access, not permission to delete images or publish new ones.

When connecting older Docker clients or private build machines, certificate trust errors are common. Install the issuing CA correctly rather than configuring an insecure registry exception. If a client must use a corporate proxy, verify that large layer uploads and long-lived connections work through it.

For a broader technology workflow, Karl Katzke’s blog provides useful context around infrastructure, systems administration, and operational decision-making. Even a straightforward registry benefits from the same disciplined approach used for larger cloud platforms.

Operate And Maintain The Registry

A registry should be monitored like any other infrastructure service. Track disk usage, HTTP error rates, authentication failures, upload latency, container restarts, and certificate expiry. A sudden increase in failed pulls may indicate a DNS problem, an expired certificate, or a storage backend that has reached its limit.

Australian organisations should also consider privacy and contractual obligations under the Privacy Act 1988 when image layers contain personal information, credentials, customer data, or diagnostic exports. Container images should contain application binaries and dependencies, not secrets or production databases. Review cloud-region terms, access logging, and backup locations before placing regulated material in the repository.

A practical workstation setup can make administration easier, particularly when reviewing logs alongside deployment tools; this second monitor guide is relevant for teams standardising Windows 10 Pro desks. Keep the registry host itself minimal, patched, and separate from unrelated services.

Routine Registry Checks

• Verify HTTPS certificate validity and renew before the alert window becomes urgent.
• Review authentication logs for repeated failures, unfamiliar source addresses, and unused accounts.
• Check storage growth, failed uploads, and registry container health at least weekly.
• Test image pulls from both office networks and cloud deployment environments.
• Confirm that backups include registry metadata, configuration, authentication files, and image content.

Retention And Recovery Tasks

• Remove unreferenced layers only after confirming that required release tags remain available.
• Keep production images for the period required by operational and audit policies.
• Store encrypted backups in a separate failure domain from the registry host.
• Perform a restore to an isolated test registry and pull a representative application image.
• Document DNS, certificates, credentials, storage mounts, and recovery commands.

A basic registry can be running in minutes, but dependable service comes from the surrounding controls. Start with a private network, trusted TLS, authenticated users, persistent storage, and a tested backup. Then add automation, retention rules, monitoring, and stronger identity integration as usage grows.

Create a small pilot repository, publish a non-sensitive image, and test the full path from build pipeline to deployment host. Record the decisions in your operations documentation, apply least-privilege access, and schedule a recovery test before the registry becomes critical to daily releases.