Registry

Local registry

Required — where built images live

External registry

Credentials for other registries

Maintenance

Per-application retention + nightly cleanup

The registry's role in a deploy

1. 01buildthe image is built by the Docker daemon
2. 02push → localhost:5000/<project>/<app>:<id>
3. 03runa container is created from that image
4. 04rollbackthe old image is pulled back from the registry

Every deploy pushes an image to the local registry, and a rollback pulls it back from there. That's why the registry must be provisioned before the first deploy — without it, deploys fail with No self-hosted registry. Applications on a remote server don't use the registry (the image stays on that server's daemon).

Local registry

1. Registry menu → Local registry tab → Provision registry (owner)

   aoox runs registry:3 as the aoox-registry container with htpasswd authentication, data on the aoox_registry_data volume, and tag deletion enabled. The card shows a Registry ready status, the container, and the URL.

   Before provisioning, pick where images are stored: Local (VPS disk, the default) or one of the S3 destinations already added under Instance backup. It can't be changed afterward without removing and re-provisioning.

2. Save the credentials

   The aoox username and a random password are shown when the registry is enabled — click I've saved it after writing it down. Deploying from the dashboard does not need it; these credentials are for pushing manually from another machine. If you lose it, owners and admins can show it again, and owners can reset it without losing any image.

docker login localhost:5000 -u aoox
docker tag myimage:latest localhost:5000/tools/myimage:1.0
docker push localhost:5000/tools/myimage:1.0

Who can reach port 5000

From 0.1.0-alpha.13 the registry's host port is bound to 127.0.0.1 by default, so only this server can push to localhost:5000 (deploys, the host's own docker push, and the panel itself are unaffected: the API reaches the registry over the internal aoox network). Before, the port listened on every interface, which exposed a password-protected registry to the internet over plain HTTP. The card says this server only next to the address while that is the case. To push from another machine, pick one:

• Give it a custom domain (recommended, below): HTTPS through the proxy, nothing else to open.
• Expose the port by IP: set REGISTRY_PUBLISH_ADDRESS=0.0.0.0 in .env.dist, restart the stack (docker compose ... up -d), then recreate the registry container (re-enable it, or apply/remove a custom domain). The card then shows the address other machines use (REGISTRY_PUBLIC_HOST or this server's public IP). It is plain HTTP, so those machines need the address in insecure-registries, and password protection is all that stands between the registry and the internet — prefer the domain.

Custom domain

An alternative to manually juggling REGISTRY_PUBLIC_HOST and insecure-registries: route the registry through the built-in reverse proxy (Traefik) with a real Let's Encrypt certificate — docker push/login trust it out of the box, no extra config needed on any daemon, including other Swarm nodes.

• Needs the proxy already provisioned (see Proxy & domain) with PROXY_ACME_EMAIL set.
• Fill in the Custom domain field on the Local registry card (owner/admin), then Apply — the container is recreated with Traefik labels (router aoox-registry), data and credentials are untouched. Or from the CLI:

aoox registry domain --set registry.example.com

Once the domain is active, docker login registry.example.com (no port — standard HTTPS). The host port stays bound as configured above (loopback by default). Remove the domain with aoox registry domain --clear or the Remove domain button in the dashboard.

Show or reset the password

• Show password (eye icon on the Local registry card, owners and admins) reads the stored password again; it hides itself after a minute and each reveal is recorded in the audit log.
• Reset password (owner) generates a new password, rewrites the registry's login file and restarts the container briefly. Images are not touched. Every client and CI job that used the old password has to run docker login again. If anything fails midway, the old password stays in force.
• From the CLI: aoox registry password --show or aoox registry password --reset --yes.

Browsing & cleaning up contents

• The Local registry tab lists repository → tag along with digest and size. Repository name = <project-slug>/<app-slug>.
• Deleting a tag deletes the manifest. Other tags pointing at the same digest disappear too — the UI warns about it.
• Garbage collect (owner) reclaims disk space after tags are deleted — it runs inside the running registry container; there's a dry run mode to preview what would be removed.
• Delete image (the button on each repository's header row) removes the whole repository, not just one tag: every tag and manifest, its folder in storage, then an automatic garbage collect — different from deleting tags one at a time, and this is what you need when a repository still shows “0 tags” and won't disappear from the list no matter how many times garbage collect runs (garbage collect only reclaims unused blobs, never the repository's own folder). Its confirmation dialog shows which applications' current image looks like it came from this repository — a rollback or a build-free redeploy to that image will fail once it's gone.
• Deleting a tag still used by a running container doesn't stop it, but rolling back to that version is no longer possible.
• Deleting the registry (owner) stops the container; you'll be asked about the data volume. Deploys can't happen again until it's provisioned again.

Disk maintenance

So old images don't fill up the disk, aoox has automatic cleanup that runs every night at 04:30 (server time zone, UTC unless you set TZ) and can also be triggered manually.

1. Docker → disk strip and Details

   The strip at the top of the Docker page (host selected) shows total usage and what can be freed; Details shows image, container, volume, and build cache usage, how much can be reclaimed, how many deployments can be pruned, and the most recent cleanup report.

2. Clean now (owner)

   Runs the same cycle on demand. The report: deployments pruned, images deleted, bytes reclaimed, registry GC status, and any errors.

External registry

External registry tab → Add registry (owner/admin): register credentials for Docker Hub, GHCR, GitLab, etc.

Common pitfalls

Next steps