Cloud deployment (Hetzner example)
This guide puts ArchGuard on one Linux server so GitHub or Bitbucket can reach it over HTTPS. It uses Hetzner Cloud as the worked example, with a free DuckDNS name and Auth0's free plan for sign-in. The same files work on any Ubuntu server. See Other clouds.
Use personal or test repositories only. A personal cloud account is outside your company's approved environment. Pull request diffs pass through this server and the language model you configure, so do not connect company repositories or company credentials to it unless that has been approved.
What you will build
| Container | Role | Reachable from the internet |
|---|---|---|
caddy |
HTTPS (automatic Let's Encrypt certificate) and reverse proxy | Yes, ports 80 and 443 |
app |
Web app, dashboard, help, webhook endpoints | Only through Caddy |
worker |
Evaluates pull requests | No |
postgres |
Database (data on a Docker volume) | No |
redis |
Queue and de-duplication | No |
migrate |
One-off task: database changes and first organization | No |
All files are in the archguard folder: Dockerfile, docker-compose.prod.yml, .env.production.example, deploy/Caddyfile and the scripts in deploy/vm/.
Choose a server
You need 2 vCPUs, 4 GB of memory, 30 GB or more of disk, a public IPv4 address and Ubuntu 24.04. Arm and Intel/AMD servers both work. Smaller servers (1 GB) run out of memory while building the image.
| Hetzner server | Size | Cost | Notes |
|---|---|---|---|
| CX23 (Intel/AMD) or CAX11 (Arm) | 2 vCPU, 4 GB, 40 GB | About €5.50 to €6 a month, plus €0.50 for the IPv4 address | Recommended. Prices rose twice in 2026, so check the current price. |
| CPX22 (AMD) | 2 vCPU, 4 GB, 80 GB | Reported at about €19.50 to €20 a month after June 2026 | Works with no changes, but costs roughly three times as much for the same memory. Use it only if CX23 and CAX11 cannot be ordered. |
Prices change often. Check the price shown on the order page before you create a server.
Step 1: Create the server
- Sign up at Hetzner Cloud. New accounts may be asked to verify their identity before they can create servers.
- Create a project, then select Add Server.
- Location: one near you, for example Falkenstein, Nuremberg or Helsinki.
- Image: Ubuntu 24.04.
- Type: Shared vCPU, then either x86 CX23 or Arm64 CAX11 (2 vCPU, 4 GB). If one is not available to order, pick the other. CPX22 also works, at a higher price.
- Networking: keep Public IPv4 switched on. Webhooks from GitHub and Bitbucket need an IPv4 address.
- SSH keys: add your public key. You then log in as
rootwith the key, without a password. - Firewalls: you can create one here or in step 2.
- Select Create & Buy now. Note the IPv4 address. It stays the same for as long as the server exists.
Step 2: Open ports 80 and 443
Open TCP 80 and 443 to everyone (and UDP 443 for HTTP/3), and SSH (TCP 22) only to your own IP address.
Hetzner's Ubuntu image has no host firewall, so you only need a Cloud Firewall, which is free.
- In the project, open Firewalls and select Create Firewall.
- Inbound rules:
- TCP
22from your IP address only. Edit the default rule, which allows SSH from everywhere. - TCP
80from any IPv4 and IPv6. - TCP
443from any IPv4 and IPv6. - UDP
443from any IPv4 and IPv6.
- TCP
- Leave Outbound empty (everything allowed).
- Under Apply to, select your server, and create the firewall.
Step 3: Get a DuckDNS name
- Sign in at duckdns.org and create a subdomain, for example
archguard-yourname. Your address isarchguard-yourname.duckdns.org. - Set its IP to the server's public IPv4 address, and copy your DuckDNS token.
The certificate in step 7 is only issued once this name points at the server. Allow a few minutes after changing it.
Step 4: Prepare the server
Create a normal user first. You start as root. Create a user with sudo rights and your SSH key, then use that user from now on:
ssh root@<server-ip>
adduser --disabled-password --gecos "" deploy
usermod -aG sudo deploy
echo "deploy ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/deploy && chmod 440 /etc/sudoers.d/deploy
rsync --archive --chown=deploy:deploy ~/.ssh /home/deploy
exit
Copy the code. From the folder that contains archguard, on your own computer (Windows 10 and later include tar and scp):
tar --exclude=node_modules --exclude=.next --exclude=.env -czf archguard.tgz archguard
scp archguard.tgz deploy@<server-ip>:~
Add -i <your-key-file> to scp and ssh if your key is not the default one. Alternatively, push the code to a private Git repository and git clone it on the server.
Run the setup script:
ssh deploy@<server-ip>
tar -xzf archguard.tgz && cd archguard
bash deploy/vm/setup-vm.sh
exit # log out and back in so the docker group applies
The script works on any Ubuntu 22.04 or 24.04 server. It:
- installs Docker Engine and the Compose plugin from Docker's official repository (or skips this if they are already installed);
- opens ports 80 and 443 in the host firewall, but only if the server has one:
ufwif it is active, oriptablesrules that reject traffic (used by some cloud images). On Hetzner it reports "No host firewall found", which is expected; - adds a 2 GB swap file on servers with less than 6 GB of memory, so the image build does not run out of memory;
- turns on automatic security updates.
DuckDNS updates are optional. A Hetzner server keeps its IPv4 address, so you can skip this. If your address can change (for example on another provider), run:
printf 'DUCKDNS_SUBDOMAIN=archguard-yourname\nDUCKDNS_TOKEN=<your-token>\n' > ~/.duckdns && chmod 600 ~/.duckdns
(crontab -l 2>/dev/null; echo "*/5 * * * * $HOME/archguard/deploy/vm/duckdns-update.sh >/dev/null 2>&1") | crontab -
Step 5: Set up sign-in with Auth0
ArchGuard signs users in with OpenID Connect. Auth0's free plan works well for a personal trial.
Create the application
- In the Auth0 dashboard, open Applications and create a Regular Web Application named ArchGuard.
- Under Settings, set:
- Allowed Callback URLs:
https://archguard-yourname.duckdns.org/api/auth/callback/oidc - Allowed Logout URLs and Allowed Web Origins:
https://archguard-yourname.duckdns.org
- Allowed Callback URLs:
- Copy the Domain, Client ID and Client Secret.
Create roles and assign them
- Open User Management, then Roles, and create
archguard-admins,archguard-architectsandarchguard-viewers. - Create your user (or sign up once) and assign yourself
archguard-admins.
Put the roles in the sign-in token
Auth0 does not include roles in the ID token by default. Open Actions, then Library, Create Action, and choose the Login / Post Login trigger. Use this code:
exports.onExecutePostLogin = async (event, api) => {
const roles = (event.authorization && event.authorization.roles) || [];
api.idToken.setCustomClaim("https://archguard.app/roles", roles);
};
Deploy it, then open Actions, Triggers, post-login, and drag it into the flow. Auth0 requires custom claims to have a URL-style name. ArchGuard reads the claim named in AUTH_OIDC_GROUPS_CLAIM, which must match. Users without one of the three roles cannot sign in. See Roles and permissions.
Step 6: Configure the environment
On the server, in the archguard folder:
cp .env.production.example .env.production
openssl rand -hex 32 # run once for each: POSTGRES_PASSWORD, APP_DB_PASSWORD, AUTH_SECRET
openssl rand -base64 32 # TOKEN_ENCRYPTION_KEY
nano .env.production
Fill in:
| Variable | Value |
|---|---|
ARCHGUARD_DOMAIN |
archguard-yourname.duckdns.org |
ACME_EMAIL |
Your email, for certificate notices |
APP_BASE_URL, WEBHOOK_PUBLIC_URL, AUTH_URL |
https://archguard-yourname.duckdns.org |
POSTGRES_PASSWORD, APP_DB_PASSWORD |
Two different hex values |
TOKEN_ENCRYPTION_KEY |
The base64 value. Keep a copy somewhere safe: without it, stored tokens cannot be read. |
AUTH_SECRET |
A hex value |
AUTH_OIDC_ISSUER |
https://<your Auth0 domain>/ (keep the trailing slash) |
AUTH_OIDC_CLIENT_ID, AUTH_OIDC_CLIENT_SECRET |
From the Auth0 application |
AUTH_OIDC_GROUPS_CLAIM |
https://archguard.app/roles |
LLM_* |
Your language model endpoint |
The deploy script restricts the file to your user (chmod 600).
Step 7: Deploy
bash deploy/vm/deploy.sh pilot "My Org"
The script builds the image on the server (several minutes on 2 vCPUs), starts Postgres and Redis, applies the database migrations, creates the organization pilot with the five starter rules, and starts the app, the worker and Caddy. Caddy then obtains the HTTPS certificate.
Check it:
curl -s https://archguard-yourname.duckdns.org/api/health
You should see {"status":"ok","db":"up","redis":"up"}. Then open the address in your browser, sign in, and follow Connect GitHub or Connect Bitbucket Cloud.
Step 8: Back up the database
(crontab -l 2>/dev/null; echo "15 2 * * * $HOME/archguard/deploy/vm/backup.sh >> $HOME/archguard-backup.log 2>&1") | crontab -
This keeps 14 days of nightly dumps in archguard/backups. Copy them off the server from time to time. Hetzner also offers automatic server backups as a paid add-on. Keep .env.production safe as well, since the encryption key is in it.
To restore a dump:
docker compose -f docker-compose.prod.yml --env-file .env.production exec -T postgres \
pg_restore -U postgres -d archguard --clean < backups/<file>.dump
Updating ArchGuard
Copy the new code to the server (as in step 4, unpacking over the old folder but keeping .env.production), then run bash deploy/vm/deploy.sh again. Migrations only apply what is new, and the organization step skips what already exists.
Day-to-day commands
Run these from the archguard folder:
| Task | Command |
|---|---|
| Status | docker compose -f docker-compose.prod.yml --env-file .env.production ps |
| Logs (follow) | docker compose -f docker-compose.prod.yml --env-file .env.production logs -f app worker |
| Restart the worker | docker compose -f docker-compose.prod.yml --env-file .env.production restart worker |
| Stop everything | docker compose -f docker-compose.prod.yml --env-file .env.production down (data is kept in volumes) |
| Disk usage | docker system df |
Logs never contain diffs or tokens. See Security and data handling.
Security notes
- Only Caddy publishes ports. Never add
ports:topostgresorredis. Ports published by Docker bypass the server's own firewall (ufworiptables) and would be open to the internet unless a cloud firewall blocks them. - Use the Hetzner Cloud Firewall as the main barrier, and keep SSH limited to your own IP address.
- The app and worker connect as the restricted
archguard_appdatabase role. Only the one-offmigratetask gets the database owner password. - Work as the
deployuser rather thanroot. - Rotate the source-control token before it expires, under Settings.
Troubleshooting the deployment
| Symptom | Likely cause |
|---|---|
| Browser cannot connect at all | Ports 80/443 not open in the Cloud Firewall, or the firewall is not applied to the server. |
| SSH stops working after creating the firewall | Your IP address changed, or the SSH rule has the wrong address. Fix the rule in the Hetzner console. |
| Certificate error, or Caddy logs mention the ACME challenge | DuckDNS does not point at the server yet, or port 80 is closed. Fix it, then run docker compose ... restart caddy. |
502 Bad Gateway right after deploying |
The app is still starting. Wait 30 seconds. |
Health shows db or redis as down |
Run docker compose ... ps and check the postgres and redis logs. |
| Sign-in fails with a callback error | The Auth0 Allowed Callback URL does not match exactly, or AUTH_URL is wrong. |
| Sign-in is refused after login | The roles claim is missing. Check that the Action is in the post-login flow, the user has a role, and AUTH_OIDC_GROUPS_CLAIM matches the claim name. |
| Issuer or configuration error at sign-in | AUTH_OIDC_ISSUER must be the Auth0 domain with https:// and a trailing slash. |
| Build stops with an out-of-memory error | The server has less than 4 GB, or swap was not added. Run free -h and rerun setup-vm.sh. |
Webhook deliveries show 401 |
The repository was enabled before the address changed. Disable and enable it again. |
setup-vm.sh says "supports Ubuntu only" |
Recreate the server with an Ubuntu 22.04 or 24.04 image. |
Other clouds
The same docker-compose.prod.yml and deploy/vm/ scripts run on any Ubuntu server with a public IPv4 address. Only the console steps differ:
| Concept | Hetzner Cloud | AWS | Azure | Google Cloud |
|---|---|---|---|---|
| Server | CX23 / CAX11 (CPX22 also works) | EC2 (for example t4g.medium) |
Virtual Machine | Compute Engine |
| Cloud firewall | Cloud Firewall | Security group | Network security group | VPC firewall rule |
| Fixed public IP | Primary IPv4 (kept while the server exists) | Elastic IP | Static public IP | Static external IP |
| Host firewall | None | None | None | None |
| First login | root |
ubuntu |
the user you chose | your Google user |
Open TCP 80 and 443 to everyone, and SSH to your own IP. Use your own domain or DuckDNS, then follow steps 3 to 8 as written, using the provider's login user instead of deploy if you skip creating one. If the server has a fixed public IP, the DuckDNS updater is optional.