Setting Up a Container Registry with Podman on Fedora

A private container registry gives Fedora administrators a controlled place to store, version and distribute OCI images. Podman can run the registry itself without a Docker daemon, making the arrangement suitable for development workstations, test servers and small production environments. Learn more about Myeasyprojects.net.

This guide uses Fedora commands and a registry container based on the standard Distribution image. It covers local testing, authenticated access, TLS, firewall rules and automatic startup with systemd. The same approach fits CentOS Stream, RHEL-compatible hosts and many lab systems.

For an Australian team, keeping images in an office, a Sydney or Melbourne cloud region, or an approved Australian data centre can reduce latency and help meet internal data-residency requirements. Plan maintenance in a suitable AEST or AEDT window, particularly when developers in Brisbane, Perth and Adelaide share the same registry.

Prepare Fedora And Podman

Update the host and install the tools required to run containers, create credentials and inspect network access:

sudo dnf update -y
sudo dnf install -y podman httpd-tools firewalld policycoreutils-python-utils
sudo systemctl enable --now firewalld

Confirm that Podman is available and create a dedicated storage directory. A rootful registry is straightforward for a shared server because it can bind to port 5000 and use a system service:

podman --version
sudo mkdir -p /srv/registry/{data,auth,certs}
sudo chown -R root:root /srv/registry

Administrators building broader command-line knowledge can also consult these Linux administration guides while checking Fedora permissions, SELinux and systemd behaviour.

Run A Basic Private Registry

For an initial LAN test, start the registry on port 5000 and persist its image layers on the host:

sudo podman run -d --name registry \
  -p 5000:5000 \
  -v /srv/registry/data:/var/lib/registry:Z \
  docker.io/library/registry:2

The :Z suffix applies an SELinux label suitable for a private container volume. Check that the service is running and review its logs:

sudo podman ps
sudo podman logs registry
curl http://127.0.0.1:5000/v2/

A successful request normally returns {}. This unencrypted mode is acceptable only for a deliberately isolated test network. Do not use it for credentials or image traffic across a shared office, public cloud network or the internet.

Configure Local Registry Names

A registry address should be stable and resolvable by every client. For testing, add a hostname such as registry.lab.example to internal DNS or to /etc/hosts. If the server is called 10.20.30.15, a client might use:

10.20.30.15 registry.lab.example

Fedora treats plain HTTP registries as insecure unless they are explicitly allowed. Create /etc/containers/registries.conf.d/registry.conf on each test client:

[[registry]]
location = "registry.lab.example:5000"
insecure = true

Restarting Podman is unnecessary because the configuration is read when a command starts. Avoid leaving this exception in place after TLS is enabled. A clear registry hostname also makes image references easier to move between a Sydney development server and an Australian cloud host.

Add Authentication

Create an htpasswd file before exposing the registry beyond a trusted lab:

sudo htpasswd -Bbn registryadmin 'replace-with-a-long-password' \
  | sudo tee /srv/registry/auth/htpasswd >/dev/null

Recreate the container with authentication enabled:

sudo podman rm -f registry
sudo podman run -d --name registry \
  -p 5000:5000 \
  -v /srv/registry/data:/var/lib/registry:Z \
  -v /srv/registry/auth:/auth:Z \
  -e REGISTRY_AUTH=htpasswd \
  -e REGISTRY_AUTH_HTPASSWD_REALM="Private Registry" \
  -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  docker.io/library/registry:2

Log in from a client and keep credentials in Podman’s authentication file:

podman login registry.lab.example:5000

Use separate accounts where practical, rotate passwords and avoid placing secrets directly in shell history. For larger teams, an identity provider or a registry platform with role-based access is preferable to one shared account.

Enable TLS With A Trusted Certificate

Production clients should connect over HTTPS. Place the certificate and private key in /srv/registry/certs, using names such as domain.crt and domain.key. The certificate’s subject alternative name must include the exact registry hostname.

Start the registry with TLS variables and publish the same port:

sudo podman rm -f registry
sudo podman run -d --name registry \
  -p 5000:5000 \
  -v /srv/registry/data:/var/lib/registry:Z \
  -v /srv/registry/auth:/auth:Z \
  -v /srv/registry/certs:/certs:Z \
  -e REGISTRY_AUTH=htpasswd \
  -e REGISTRY_AUTH_HTPASSWD_REALM="Private Registry" \
  -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  docker.io/library/registry:2

Install the issuing CA on Fedora clients under /etc/pki/ca-trust/source/anchors/, then run sudo update-ca-trust. Do not bypass certificate validation with an insecure-registry setting when the registry contains business or customer images.

Open The Firewall And Test Pushes

Permit only the required service through firewalld:

sudo firewall-cmd --permanent --add-port=5000/tcp
sudo firewall-cmd --reload

Build a small image, tag it with the complete registry path and push it after authentication:

podman build -t registry.lab.example:5000/demo/web:1.0 .
podman login registry.lab.example:5000
podman push registry.lab.example:5000/demo/web:1.0
podman pull registry.lab.example:5000/demo/web:1.0

If a push fails, inspect DNS, certificate names, firewall rules, SELinux audit messages and the registry log. For offices connected over NBN or site-to-site VPN, test from the actual developer network rather than only from the registry host.

Make The Registry Start Automatically

Generate a systemd unit from the existing container:

sudo podman generate systemd --new --name registry \
  | sudo tee /etc/systemd/system/container-registry.service
sudo systemctl daemon-reload
sudo systemctl enable --now container-registry.service

Check its status after a reboot simulation or service restart:

systemctl status container-registry.service
sudo podman ps

Back up /srv/registry/data, /srv/registry/auth and the certificate material with restricted permissions. Registry storage grows continuously, so monitor disk usage and establish retention rules for old tags. A Melbourne startup or Sydney consultancy may also need documented backup locations when client contracts require Australian data handling.

Maintain Images And Registry Health

The registry does not automatically remove unreferenced layers simply because tags are deleted. Use the Distribution garbage-collection process carefully, with the registry stopped and a verified backup. Never run cleanup while clients are pushing or pulling images.

Record image digests in deployment manifests rather than relying only on mutable tags such as latest. Regularly patch the registry image, review authentication logs and check available storage:

sudo podman pull docker.io/library/registry:2
sudo du -sh /srv/registry/data
sudo journalctl -u container-registry.service --since today

A practical next step is to create the TLS certificate for registry.lab.example, start the authenticated container, and verify one complete podman push and podman pull from a separate Fedora client.