Self-host a private Docker registry
Your own private image registry, behind exe.dev login, with no passwords to manage.
Shelley handles the setup. About 10 minutes.
Prefer a terminal?
curl -fsSL https://exe-staging.dev/deploy/container-registry/prompt.txt | ssh exe.dev new --prompt=/dev/stdinA private registry is where your own images live between docker build
and docker run: your app, your CI's output, the base images your team
agrees on. This page runs Distribution
3.1, the registry behind Docker Hub, on an exe.dev VM, with its data on
the VM's disk, a small web UI, and weekly cleanup.
The registry needs no users, passwords or certificates of its own. The
VM is private: exe.dev's HTTPS proxy answers only you,
people you share it with, and requests carrying a
token for this VM, which docker login
takes as its password. It's an always-on machine with a real disk, so a
2 GB layer is just a file.
What you get#
- Distribution 3.1 on port 8000, private behind exe.dev login, restarted at boot
- A web UI on port 8001 for browsing and deleting tags
- Weekly garbage collection that frees the space of deleted tags
- A test image pushed, pulled and deleted again on the VM itself
What's running, and where
https://my-registry.exe.xyz/
The registry, for you, people you share the VM with, and exe.dev tokens for this VM
https://my-registry.exe.xyz:8001/
The web UI
Deploy with Shelley#
Click Deploy and Shelley will set up Docker Registry on a new VM, then check that it works. No config-file wrangling required.
Prefer a terminal?
curl -fsSL \
https://exe-staging.dev/deploy/container-registry/prompt.txt \
| ssh exe.dev new --prompt=/dev/stdinWhat Shelley is told
Set up Docker Registry on this VM by following the exe.dev recipe at https://exe-staging.dev/deploy/container-registry.md?via=deploy from top to bottom.
The recipe's example VM name is my-registry. This VM's name is the output of `hostname`: use it wherever the recipe writes my-registry. Skip the step that creates the VM; you are on it.
You are done when all of these are true. Check each one yourself:
- Distribution 3.1 on port 8000, private behind exe.dev login, restarted at boot
- A web UI on port 8001 for browsing and deleting tags
- Weekly garbage collection that frees the space of deleted tags
- A test image pushed, pulled and deleted again on the VM itself
Read the whole recipe, then run only "Install by hand", skipping VM
creation. Tokens, other machines, GitHub Actions, the Docker Hub cache
and zot are the owner's choice afterwards; don't set those up unless
asked. You can't create tokens from the VM: they need the owner's
`ssh exe.dev`. Verify: docker.service is enabled; `docker compose ps`
in ~/registry shows registry and ui running; the smoke test in
"Check it" passes; registry-gc.timer is enabled. Finish with the UI URL
(port 8001) and the commands for the owner's computer from "Push your
first image", with this VM's name.
Finish with the URLs I should open.
Also at /deploy/container-registry/prompt.txt. The recipe it follows is /deploy/container-registry.md.
Push your first image#
On your computer, make a token that only works for this VM, and log in with it (the username is ignored):
ssh exe.dev ssh-key generate-api-key --vm=my-registry --label=registry-laptop --exp=90d --json \
| jq -r .token | docker login my-registry.exe.xyz -u token --password-stdin
Docker saves the login like any other registry's. Push something:
docker pull alpine:3.22
docker tag alpine:3.22 my-registry.exe.xyz/hello:1
docker push my-registry.exe.xyz/hello:1
Open https://my-registry.exe.xyz:8001/ and hello is there.
docker buildx build --push -t my-registry.exe.xyz/app:1 . works too.
The token lasts 90 days. Revoke it early with
ssh exe.dev ssh-key remove registry-laptop, or log in again with a new
one when it runs out.
Pull from other machines#
Give each machine its own token, with its own --label, so you can
revoke one without the others. Then:
-
Docker on another VM or server: the same
docker login, thendocker pull my-registry.exe.xyz/hello:1. -
k3s: put the token in
/etc/rancher/k3s/registries.yamland restart k3s (sudo systemctl restart k3s). Deployments then useimage: my-registry.exe.xyz/hello:1with noimagePullSecrets.configs: "my-registry.exe.xyz": auth: username: token password: "exe1.your-token" -
Podman:
podman login my-registry.exe.xyz -u token. -
containerd:
ctr images pull --user token:exe1.your-token my-registry.exe.xyz/hello:1. -
A remote builder:
docker loginon the builder VM, thendocker buildx build --builder exe --push -t my-registry.exe.xyz/app:1 .pushes straight from the builder.
On your exe.dev VMs you can skip tokens altogether: a VM-to-VM integration adds a credential at exe.dev's edge, so the VM holds none. Create it on your computer and attach it to the VMs that need images:
ssh exe.dev integrations add http-proxy --name registry \
--target https://my-registry.exe.xyz/ --peer --attach vm:my-app
On my-app, docker pull registry.int.exe.xyz/hello:1 works with no
login. Attach it to a tag (--attach tag:prod) and new VMs get it too.
Push from GitHub Actions#
On your computer, make a token for CI and store it as a repository secret (with the GitHub CLI, or paste it in Settings → Secrets and variables → Actions):
ssh exe.dev ssh-key generate-api-key --vm=my-registry --label=registry-ci --exp=1y --json \
| jq -r .token | gh secret set EXE_REGISTRY_TOKEN
Then in .github/workflows/image.yml:
name: image
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: docker/login-action@v4
with:
registry: my-registry.exe.xyz
username: token
password: ${{ secrets.EXE_REGISTRY_TOKEN }}
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
push: true
tags: my-registry.exe.xyz/${{ github.event.repository.name }}:${{ github.sha }}
If your runners are exe.dev VMs (GitHub Actions on exe.dev),
attach the registry integration to them instead and push to
registry.int.exe.xyz/… with no secret.
A Docker Hub cache#
Docker Hub limits pulls per IP address, and exe.dev VMs share outbound addresses with other users' VMs. On Nov 19, 2026, Docker Hub gave a fresh VM 100 pulls an hour, of which 79 were left. A pull-through cache asks Docker Hub once per image and serves your VMs from its disk after that.
On the registry VM, run a second Distribution in proxy mode on port 8002:
mkdir -p ~/hubcache && cd ~/hubcache
cat > config.yml <<'EOF'
version: 0.1
storage:
filesystem:
rootdirectory: /var/lib/registry
delete:
enabled: true
http:
addr: :5000
relativeurls: true
proxy:
remoteurl: https://registry-1.docker.io
ttl: 168h
EOF
cat > compose.yaml <<'EOF'
services:
hubcache:
image: registry:3.1.2
restart: unless-stopped
ports:
- "8002:5000"
volumes:
- ./config.yml:/etc/distribution/config.yml:ro
- ./data:/var/lib/registry
EOF
docker compose up -d
Docker can't log in to a mirror, so give your VMs a way in with an integration, from your computer:
ssh exe.dev integrations add http-proxy --name dockerhub \
--target https://my-registry.exe.xyz:8002/ --peer --attach vm:my-app
Then on my-app, make it Docker's mirror for Docker Hub:
echo '{"registry-mirrors": ["https://dockerhub.int.exe.xyz"]}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker
docker pull redis:8-alpine
The pull lands in ~/hubcache/data on the registry VM. For k3s, add a
docker.io mirror with that endpoint in registries.yaml
(k3s mirrors).
The cache keeps images a week after their last pull, and it only reads
from Docker Hub; you can't push to it.
Clean up#
Deleting a tag hides it; garbage collection frees the disk. Delete tags in the UI (the trash icon on a tag's row; it deletes the image, so every tag pointing at the same image goes too, and the dialog lists them before you confirm), or one tag at a time on the VM:
curl -X DELETE localhost:8000/v2/web/api/manifests/2026-10-01
That removes only that tag, even if other tags point at the same image.
The registry-gc timer runs every Sunday at 04:00 UTC: it stops the
registry for a few seconds, deletes every manifest and layer no tag
needs any more, and starts it again. To run it now:
sudo systemctl start registry-gc.service
journalctl -u registry-gc --no-pager | grep -E 'marked|eligible' | tail -3
du -sh ~/registry/data
In our test, deleting a 400 MB image and collecting took the data from 672 MB to 291 MB in under a second. Multi-arch images survive collection as long as their index is tagged.
Disk and backups#
Everything is in ~/registry: data/ holds the images, the rest is a
few small config files. Check how full the disk is with df -h /, and
grow it from your computer:
ssh exe.dev resize my-registry --disk=100GB
then on the VM sudo resize2fs $(findmnt -no SOURCE /).
Image layers never change once written, so a copy only needs the new files each time. On your computer, or another VM with room:
rsync -a --delete my-registry.exe.xyz:registry/ ./registry-backup/
To restore, copy registry/ back to a VM set up with "Install by hand"
while its containers are stopped (docker compose down), then
docker compose up -d. If your images can all be rebuilt from source,
back up just the config files and treat the data as a cache.
Use zot instead#
zot is an OCI-native registry with a built-in web UI and search, and retention policies that delete old tags for you. It sits behind exe.dev the same way. On the VM:
mkdir -p ~/zot/data && cd ~/zot
cat > config.json <<'EOF'
{
"distSpecVersion": "1.1.1",
"storage": {
"rootDirectory": "/var/lib/registry",
"dedupe": true,
"gc": true,
"gcDelay": "1h",
"gcInterval": "24h",
"retention": {
"delay": "24h",
"policies": [
{
"repositories": ["**"],
"deleteReferrers": true,
"deleteUntagged": true,
"keepTags": [{ "mostRecentlyPushedCount": 10 }]
}
]
}
},
"http": { "address": "0.0.0.0", "port": "5000" },
"log": { "level": "info" },
"extensions": {
"search": { "enable": true },
"ui": { "enable": true }
}
}
EOF
cat > compose.yaml <<'EOF'
services:
zot:
image: ghcr.io/project-zot/zot:v2.1.23
restart: unless-stopped
ports:
- "8003:5000"
volumes:
- ./config.json:/etc/zot/config.json:ro
- ./data:/var/lib/registry
EOF
docker compose up -d
The policy keeps the 10 most recently pushed tags of every repository
and deletes the rest a day later. Its UI is https://my-registry.exe.xyz:8003/,
and the registry is the same address (docker login my-registry.exe.xyz:8003).
To make zot your only
registry, put it on port 8000 instead and stop the Distribution stack
(cd ~/registry && docker compose down). We tested zot 2.1.23 with
Docker 29 pushes and pulls through exe.dev.
The nuts and bolts#
Install by hand
Create the VM#
On your computer (pick another name if my-registry is taken):
ssh exe.dev new --name=my-registry
ssh my-registry.exe.xyz
The rest runs on the VM, as exedev.
Start the registry#
Docker starts at boot so the registry does too:
sudo systemctl enable --now docker.service
mkdir -p ~/registry/data && cd ~/registry
cat > config.yml <<'EOF'
version: 0.1
log:
level: info
storage:
filesystem:
rootdirectory: /var/lib/registry
delete:
enabled: true
cache:
blobdescriptor: inmemory
http:
addr: :5000
relativeurls: true
health:
storagedriver:
enabled: true
interval: 10s
threshold: 3
EOF
cat > compose.yaml <<EOF
services:
registry:
image: registry:3.1.2
restart: unless-stopped
ports:
- "8000:5000"
volumes:
- ./config.yml:/etc/distribution/config.yml:ro
- ./data:/var/lib/registry
ui:
image: joxit/docker-registry-ui:2.6.0
restart: unless-stopped
ports:
- "8001:80"
environment:
SINGLE_REGISTRY: "true"
NGINX_PROXY_PASS_URL: http://registry:5000
REGISTRY_TITLE: $(hostname)
DELETE_IMAGES: "true"
SHOW_CATALOG_NB_TAGS: "true"
ENABLE_VERSION_NOTIFICATION: "false"
depends_on: [registry]
EOF
docker compose up -d
docker compose ps
relativeurls keeps upload locations relative, so pushes work through
exe.dev's proxy, an integration and localhost alike.
Check it#
Push, pull and delete a test image from the VM itself (plain HTTP is
allowed on localhost):
docker pull -q alpine:3.22
docker tag alpine:3.22 localhost:8000/smoke:1
docker push -q localhost:8000/smoke:1
curl -s localhost:8000/v2/_catalog; echo
curl -s -o /dev/null -w 'delete %{http_code}\n' -X DELETE localhost:8000/v2/smoke/manifests/1
curl -s -o /dev/null -w 'ui %{http_code}\n' localhost:8001/
Expect {"repositories":["smoke"]}, delete 202 and ui 200.
Weekly garbage collection#
sudo tee /etc/systemd/system/registry-gc.service >/dev/null <<'EOF'
[Unit]
Description=Garbage-collect the registry
After=docker.service
Requires=docker.service
[Service]
Type=oneshot
User=exedev
WorkingDirectory=/home/exedev/registry
ExecStart=/usr/bin/docker compose stop registry
ExecStart=/usr/bin/docker compose run --rm --no-deps registry garbage-collect --delete-untagged /etc/distribution/config.yml
ExecStopPost=/usr/bin/docker compose start registry
EOF
sudo tee /etc/systemd/system/registry-gc.timer >/dev/null <<'EOF'
[Unit]
Description=Garbage-collect the registry weekly
[Timer]
OnCalendar=Sun 04:00 UTC
Persistent=true
[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now registry-gc.timer
sudo systemctl start registry-gc.service
journalctl -u registry-gc --no-pager | grep -E 'marked|eligible' | tail -3
sleep 3; curl -s localhost:8000/v2/smoke/tags/list; echo
The journal lists the smoke image's layers as eligible for deletion, and
smoke has no tags left ({"name":"smoke","tags":[]}). The UI is at
https://<vm>.exe.xyz:8001/: printf 'https://%s.exe.xyz:8001/\n' "$(hostname)".
Update
The images are pinned. To move to a newer
Distribution release
or Docker Registry UI release,
change the tag in ~/registry/compose.yaml, then on the VM:
cd ~/registry
docker compose pull && docker compose up -d
curl -s localhost:8000/v2/_catalog
Do it when nobody is pushing; a push cut off by the restart has to be run again. Read the release notes before a major version.
Troubleshooting
Start with the logs, on the VM:
cd ~/registry
docker compose ps
docker compose logs --tail=50 registry
401 Unauthorizedfromdocker login: the token is for another VM, expired or was revoked. Make a new one with--vm=my-registry.no basic auth credentialson pull or push: this machine hasn't logged in tomy-registry.exe.xyz, or logged in under another name (my-registry.exe.xyz:8000is a different registry to Docker).- Down after a reboot?
sudo systemctl enable --now docker.service. - Disk full: delete old tags, run
sudo systemctl start registry-gc.service, and grow the disk (see Disk and backups). - The UI shows no images:
docker compose logs ui; it reaches the registry throughhttp://registry:5000.
Frequently asked questions#
Do I need TLS certificates or a password file?
No. exe.dev's HTTPS proxy serves the certificate and checks who's calling; the registry runs with no auth of its own and is reachable only through that proxy. docker login takes an exe.dev token as the password.
How much disk does it need?
Layers are stored once however many tags use them. A new VM's 25 GB holds a few dozen typical app images; grow it any time with ssh exe.dev resize my-registry --disk=100GB. Disks are billed by what's used, not their size. See exe.dev pricing.
Can I give a machine pull-only access?
Tokens from generate-api-key can push. For a read-only token, sign one yourself with a ctx such as {"registry":"pull"} (local signing); exe.dev passes it to the VM as an X-ExeDev-Token-Ctx header the holder can't change. Then ask Shelley to put nginx in front of the registry that refuses POST, PUT, PATCH and DELETE when that header says pull.
Distribution or zot?
Distribution (registry:3) is the reference registry that Docker Hub grew from: small, boring and everywhere. zot is OCI-native and has its own UI, search and tag-retention policies that delete old tags for you. Both work the same way behind exe.dev; see Use zot instead.
Can I make it public, for anonymous pulls?
ssh exe.dev share set-public my-registry would make port 8000 open to anyone, pushes included, because the registry has no auth of its own. For public images, use Docker Hub or GHCR, or put registry htpasswd auth in front before you do.
Published Nov 21, 2026 · Updated Nov 21, 2026 · tested end to end Nov 21, 2026 · Markdown · manifest.json · Something wrong? Tell us