Set Up a Docker Registry on Fedora

A private Docker Registry gives teams one place to publish tagged container images, manifests and layers. Teams can pull the same build on a laptop, CI worker or production host without relying on a public registry or repeatedly rebuilding it.

This guide uses Podman on Fedora to run the upstream Docker Registry v2 image. The result is Docker-compatible, while Quadlet and systemd provide repeatable startup, automatic restarts and host-level logging.

Prepare the Fedora host

Install the container runtime and firewall, then create a dedicated storage path:

sudo dnf install -y podman firewalld
sudo systemctl enable --now firewalld
sudo install -d -m 0750 /var/lib/registry

Run the daemonised registry as root so it can bind a restricted port and use predictable system-wide storage. The :Z SELinux label used later permits the container to write that directory without weakening SELinux globally.

Long image pulls and pushes can outlive an SSH session. Administrators can use tmux terminal multiplexing to keep a transfer visible and reconnect to it from another terminal.

Give the registry a stable address

Choose a DNS name such as registry.example.com.au and publish an A or CNAME record to the server. Use split-horizon DNS if internal clients should reach a private address while public clients use the public one.

For a fixed private address, use static IP with nmcli; for DHCP, reserve the resulting lease instead. A public registry normally needs a stable public address or reliable dynamic DNS. Changing the endpoint breaks existing image references and client trust settings.

Australian support teams commonly work across Sydney, Melbourne and Brisbane during long operating windows. Many follow 24-hour schedules, and clock changes vary by state, so UTC timestamps prevent ambiguity when comparing releases. Home NBN connections and some business broadband from providers such as Telstra or Optus sit behind NAT or carrier-grade NAT, making direct exposure of port 5000 impossible. Confirm whether the connection has a routable static address; otherwise, use a controlled tunnel or cloud load balancer that exposes port 443.

Run Registry v2 as a systemd service

Fedora’s Quadlet turns a container definition into a systemd unit. First, create the registry configuration and its initial administrator credential:

sudo dnf install -y httpd-tools
sudo install -d -m 0750 /etc/docker/registry
sudo tee /etc/docker/registry/config.yml >/dev/null <<'EOF'
version: 0.1
storage:
  filesystem:
    rootdirectory: /var/lib/registry
http:
  addr: :5000
  headers:
    X-Content-Type-Options: [nosniff]
auth:
  htpasswd:
    realm: Registry Realm
    path: /etc/docker/registry/htpasswd
EOF
sudo htpasswd -B -c /etc/docker/registry/htpasswd registryadmin

Then create the Quadlet container definition:

# /etc/containers/systemd/registry.container
[Unit]
Description=Private container registry
Wants=network-online.target
After=network-online.target

[Container]
Image=docker.io/library/registry:2
ContainerName=registry
PublishPort=127.0.0.1:5000:5000
Volume=/var/lib/registry:/var/lib/registry:Z
Volume=/etc/docker/registry:/etc/docker/registry:ro,Z

[Service]
Restart=always
TimeoutStartSec=180

[Install]
WantedBy=multi-user.target

Enable the generated unit and check its API endpoint:

sudo systemctl daemon-reload
sudo systemctl enable --now registry.service
curl http://127.0.0.1:5000/v2/

An UNAUTHORIZED response is expected because authentication is enabled. Binding port 5000 to loopback keeps the registry private until its proxy is ready, while Restart=always handles daemon restarts and brief failures.

Tag images with the registry name and an immutable release marker rather than only latest. OCI manifests and content-addressed layers then give clients repeatable artefacts to verify and cache.

Secure access and configure clients

Terminate TLS at Nginx and proxy requests to the local registry. Install the packages and create a virtual host:

server {
    listen 443 ssl;
    server_name registry.example.com.au;

    ssl_certificate /etc/pki/tls/certs/registry.crt;
    ssl_certificate_key /etc/pki/tls/private/registry.key;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_request_buffering off;
        client_max_body_size 2g;
    }
}

Use a certificate trusted by clients, then enable Nginx and expose only HTTPS:

sudo setsebool -P httpd_can_network_connect 1
sudo systemctl enable --now nginx
sudo firewall-cmd --permanent --add-service=https/tcp
sudo firewall-cmd --reload

For an internal CA, install its root certificate in the system trust store for Podman; Docker Engine also expects it under /etc/docker/certs.d/registry.example.com.au/ca.crt. Create one htpasswd entry per person by omitting -c after the first account. Registry authentication identifies users but does not provide fine-grained roles, so proxy policy is needed when some accounts must be read-only.

After trusting the CA, log in and exercise a complete workflow:

podman login registry.example.com.au
podman build -t registry.example.com.au/platform/api:2026.11 .
podman push registry.example.com.au/platform/api:2026.11

Docker Engine uses the same registry with docker login and compatible docker push and docker pull commands. If a transfer stalls, compare the client error with network traffic fundamentals before changing firewall or DNS settings.

Private images can still contain personal information in labels, build metadata or logs. Covered organisations must assess the Privacy Act 1988, Australian Privacy Principles and applicable state privacy legislation, with OAIC guidance providing further context. Australian customers often ask about data residency, so record where registry disks and backups physically sit, including whether they remain in Sydney or Melbourne.

Operational checks to remember

Before other teams depend on the service, verify these registry controls:

registry.service and Nginx are enabled and active.
The HTTPS endpoint presents the expected certificate and authentication challenge.
Every client uses an individual credential, and only authorised publishers can push.
Podman and Docker clients can pull, inspect and verify the same tagged image.

For ongoing operation, keep these recovery and monitoring checks:

Snapshot /var/lib/registry consistently while the service is stopped or through a storage-aware snapshot, then test restoration.
Track free disk space, inode use, container logs and failed login attempts, with alerts before storage becomes full.
Rotate credentials and certificates, and retain enough audit detail to trace who published a release.

What teams should remember is that the registry is a controlled distribution service, not merely blob storage. Stable addressing, encrypted and authorised access, repeatable tagging and tested recovery are what make the images inside it dependable.