Registry

Techulus Cloud runs a private Docker Distribution Registry for storing container images built from source.

How It Works

When you deploy from a GitHub repository, an agent builds the container image using BuildKit and pushes it to the registry. Other agents pull the image from the registry during deployment. Images are tagged with the commit SHA:

registry.example.com/{project_id}/{service_id}:{commit_sha}

Configuration

The registry runs as a Docker container alongside the control plane, available at https://registry.<ROOT_DOMAIN>.

Variable	Description
`REGISTRY_HOST` / `REGISTRY_URL`	Registry endpoint aliases (an optional `http://` or `https://` scheme is accepted; paths are not)
`REGISTRY_USERNAME`	Basic auth username
`REGISTRY_PASSWORD`	Basic auth password
`REGISTRY_INSECURE`	Set to `true` to disable TLS certificate verification on agents
`REGISTRY_HTTP_SECRET`	Internal HTTP signing secret

The built-in credentials are included in the same encrypted registry bundle as custom credentials. Registered agents fetch that complete bundle over a signed, non-cacheable endpoint; registration itself does not return registry passwords.

Global custom registries

Administrators can add private registry credentials under Settings → Registries. A registry host (including an explicit port, when required) is globally unique and cannot include a scheme or path. Docker Hub aliases are treated as the same host, and hosts used by the built-in registry configuration are reserved. Registry changes are transactionally queued for every registered agent, including offline agents. Registry entries cannot be edited after creation. To change a username, password, or TLS setting, delete the registry and add it again. Deleting an entry removes it from the next complete bundle. Use pull-only robot or service-account tokens wherever possible. Passwords are write-only in the control plane UI. The control plane validates image reference syntax but neither decrypts custom registry passwords nor contacts registries to test them. An agent’s actual image pull is the authoritative credential and image availability check. TLS certificate verification is enabled by default. Disable it only for a deliberately trusted registry using a private or self-signed certificate: doing so allows credential interception if the network is compromised. The TLS setting applies to agent-managed Podman pulls, build exports, and manifest operations. Dockerfile FROM pulls are resolved by the separate BuildKit daemon; using an insecure registry there also requires configuring that host in BuildKit’s daemon configuration. Credentials for TLS-verified registries are forwarded to BuildKit automatically.

Storage

Images are stored on the local filesystem in a persistent Docker volume (registry-data). Delete operations are enabled for garbage collection.

Garbage collection

Garbage collection removes blobs that are no longer referenced by a manifest. It does not choose which tagged images to retain. Delete unwanted tags first, then run garbage collection to reclaim their storage. Registry 3 is required because its --delete-untagged behavior safely preserves manifests referenced by retained multi-platform indexes. Failed or interrupted builds can leave digest-only artifacts until the next weekly collection (between 0 and 7 days). Techulus Cloud does not install or schedule garbage collection automatically.

Preview garbage collection

You can run a dry run while the registry is serving traffic:

REGISTRY=techulus-cloud-registry-1

docker exec "$REGISTRY" \
  /bin/registry garbage-collect \
  --dry-run \
  --delete-untagged \
  /etc/distribution/config.yml

--delete-untagged removes untagged manifests so that their unreferenced blobs can also be collected.

Run garbage collection

Garbage collection must not race with image pushes. The following maintenance script stops the registry while collecting, so the registry is briefly unavailable. It prevents overlapping runs and restarts the registry if garbage collection fails. Builds overlapping this window may fail, and transient platform manifests not yet referenced by an index can be collected; retry the build after maintenance. Snapshot registry storage before the first Registry 3 collection. Install it as /usr/local/sbin/techulus-registry-gc on the control-plane server:

cat >/usr/local/sbin/techulus-registry-gc <<'EOF'
#!/bin/sh
set -eu

exec 9>/run/lock/techulus-registry-gc.lock
/usr/bin/flock -n 9 || exit 0

REGISTRY=${REGISTRY_CONTAINER:-techulus-cloud-registry-1}
IMAGE=$(/usr/bin/docker inspect --format '{{.Config.Image}}' "$REGISTRY")

restart_registry() {
    /usr/bin/docker start "$REGISTRY" >/dev/null 2>&1 || true
}

trap restart_registry EXIT
trap 'exit 1' HUP INT TERM

/usr/bin/docker stop "$REGISTRY"
/usr/bin/docker run --rm \
    --volumes-from "$REGISTRY" \
    --entrypoint /bin/registry \
    "$IMAGE" \
    garbage-collect \
    --delete-untagged \
    /etc/distribution/config.yml

restart_registry
trap - EXIT HUP INT TERM
EOF

chmod 0755 /usr/local/sbin/techulus-registry-gc

Run it manually with:

/usr/local/sbin/techulus-registry-gc

Schedule weekly garbage collection

To run garbage collection every Sunday at 03:00, create /etc/cron.d/techulus-registry-gc manually:

SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

0 3 * * 0 root /usr/local/sbin/techulus-registry-gc 2>&1 | /usr/bin/logger -t techulus-registry-gc

View scheduled-run output with:

journalctl -t techulus-registry-gc

Verify garbage collection

After garbage collection, wait for the registry to report healthy, pull a known retained multi-platform tag on every supported platform, inspect its index, and check storage usage:

docker inspect --format '{{.State.Health.Status}}' techulus-cloud-registry-1
docker pull --platform linux/amd64 REGISTRY/IMAGE:TAG
docker pull --platform linux/arm64 REGISTRY/IMAGE:TAG
docker buildx imagetools inspect REGISTRY/IMAGE:TAG
docker run --rm --volumes-from techulus-cloud-registry-1 alpine du -sh /var/lib/registry

Core

Control Plane

Agents

Services

Deployments

Networking

Infrastructure

API

How It Works

Configuration

Global custom registries

Storage

Garbage collection

Preview garbage collection

Run garbage collection

Schedule weekly garbage collection

Verify garbage collection

​How It Works

​Configuration

​Global custom registries

​Storage

​Garbage collection

​Preview garbage collection

​Run garbage collection

​Schedule weekly garbage collection

​Verify garbage collection

How It Works

Configuration

Global custom registries

Storage

Garbage collection

Preview garbage collection

Run garbage collection

Schedule weekly garbage collection

Verify garbage collection