Registries

A container registry stores container images. up needs one to pull base images from, and a git-source service needs one to push the built image to before it is deployed. Without a registry, builds have nowhere to deliver their output.

The configuration reference for the registries section lives under Configuration; this page covers the background and how to get a registry.

Common providers

You probably already have an account with one of the public providers:

• Docker Hub (docker.io) : the default image source for most public images. Public repositories are free; private ones need a paid plan.
• GitHub Container Registry (ghcr.io) : free, and natural if your code lives on GitHub. Image names must start with your GitHub username or organisation name.
• Quay (quay.io) : a general-purpose registry from Red Hat.

Any of them works as a push target for builds. up registry add registers one with the control node:

up registry add ghcr.io --username deploy-bot --password $GHCR_TOKEN --default

See Configuration/Registries for the full knob reference.

A local development registry

For local development, a registry running on your own machine is enough, and it removes the need for external credentials. Run one with Podman or Docker:

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

The optional registry UI gives you a web page to browse images:

podman run -d --name registry-ui -p 8080:80 \
  -e NGINX_PROXY_PASS_URL=http://host.containers.internal:5000 \
  -e SINGLE_REGISTRY=true \
  docker.io/joxit/docker-registry-ui:latest

Then register it with up:

up registry add localhost:5000 --default

Plain-HTTP registries

A local registry like localhost:5000 serves plain HTTP, but Podman and Docker both attempt HTTPS first. The node’s container runtime must be told to trust the registry, or every pull fails. With Podman, mark the host insecure in /etc/containers/registries.conf:

[[registry]]
location = "localhost:5000"
insecure = true

With Docker, add the host to the insecure-registries list in the daemon configuration (/etc/docker/daemon.json) and restart the daemon.

For anything beyond local development, run the registry behind TLS on a real host instead of relying on an insecure connection.

One note on local registries: registry verification runs from the control plane, so a loopback host registered there passes even though build nodes reach it through a different address. If a build node cannot reach the registry, verify from that host or pass --no-verify when adding.