Setup guide
Self-host Hoardr in a few minutes.
1. Run it (Docker Compose)
Copy this into docker-compose.yml, set a strong master token, then
docker compose up -d. The ./data mount holds your blobs and database —
that one folder is your whole registry, so back it up.
services:
hoardr:
image: ghcr.io/bernhardpollerspoeck/hoardr:latest
container_name: hoardr
restart: unless-stopped
ports:
- "8080:8080"
environment:
Hoardr__MasterToken: "change-me" # use a long random secret
Hoardr__DataRoot: "/data"
Hoardr__Retention__KeepMin: "10"
Hoardr__Retention__MaxAgeDays: "30"
volumes:
- ./data:/data # blobs + database -> back this up
Prefer a one-liner? docker run works too:
docker run -d --name hoardr -p 8080:8080 -e Hoardr__MasterToken=change-me -e Hoardr__DataRoot=/data -v "$(pwd)/data:/data" ghcr.io/bernhardpollerspoeck/hoardr:latest
Configuration
All settings are environment variables (double underscore = nested):
| Variable | Default | Purpose |
|---|---|---|
| Hoardr__MasterToken | — | Admin token (full access). Required. |
| Hoardr__DataRoot | ./data | Where blobs + database live. |
| Hoardr__Retention__KeepMin | 10 | Newest tags always kept per repo. |
| Hoardr__Retention__MaxAgeDays | 30 | Older tags beyond KeepMin are removed (0 = never). |
2. Port & HTTPS
Hoardr serves HTTP on 8080 by default. Change the port or switch on built-in HTTPS with these
variables — no reverse proxy required (one still works if you prefer it). Docker requires HTTPS for any
registry that isn't localhost.
| Variable | Default | Purpose |
|---|---|---|
| Hoardr__Http__Port | 8080 | HTTP listen port |
| Hoardr__Https__Enabled | false | turn on HTTPS |
| Hoardr__Https__Port | 8443 | HTTPS listen port |
| Hoardr__Https__CertPath | — | a PFX bundle, or your .cer/.pem certificate |
| Hoardr__Https__CertKeyPath | — | private .key when using cert + key |
| Hoardr__Https__CertPassword | — | password for a PFX bundle |
Two ways to give a certificate: a single PFX (CertPath + CertPassword),
or a separate .cer + .key (CertPath + CertKeyPath — PEM or DER, RSA or EC).
With HTTPS on and no certificate, a self-signed dev cert is used (local testing only).
services:
hoardr:
image: ghcr.io/bernhardpollerspoeck/hoardr:latest
ports:
- "8443:8443"
environment:
Hoardr__MasterToken: "change-me"
Hoardr__Https__Enabled: "true"
Hoardr__Https__CertPath: "/certs/registry.cer"
Hoardr__Https__CertKeyPath: "/certs/registry.key"
volumes:
- ./data:/data
- ./certs:/certs:ro
3. Log in & push
docker login registry.example.com -u master -p <your-master-token>
docker tag myapp registry.example.com/team/myapp:1.0
docker push registry.example.com/team/myapp:1.0
4. Create accounts & permissions
Open the web UI, click Login, sign in with username master and your token.
In Admin → Accounts create users and grant per-repository pull / push /
delete. Give CI a push-only account so it can't delete tags.
5. Tag retention
Set a global default with the Hoardr__Retention__* variables, then override per repository under
Admin → Tag Retention. Hoardr keeps the newest tags and ages out the rest automatically.
6. Disk-space alerts (optional)
Under Admin → ntfy, enable alerts, set your ntfy server + topic (and token if private), and a threshold. Hoardr pushes a warning when storage crosses it.