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

  1. Sign up at Hetzner Cloud. New accounts may be asked to verify their identity before they can create servers.
  2. Create a project, then select Add Server.
  3. Location: one near you, for example Falkenstein, Nuremberg or Helsinki.
  4. Image: Ubuntu 24.04.
  5. 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.
  6. Networking: keep Public IPv4 switched on. Webhooks from GitHub and Bitbucket need an IPv4 address.
  7. SSH keys: add your public key. You then log in as root with the key, without a password.
  8. Firewalls: you can create one here or in step 2.
  9. 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.

  1. In the project, open Firewalls and select Create Firewall.
  2. Inbound rules:
    • TCP 22 from your IP address only. Edit the default rule, which allows SSH from everywhere.
    • TCP 80 from any IPv4 and IPv6.
    • TCP 443 from any IPv4 and IPv6.
    • UDP 443 from any IPv4 and IPv6.
  3. Leave Outbound empty (everything allowed).
  4. Under Apply to, select your server, and create the firewall.

Step 3: Get a DuckDNS name

  1. Sign in at duckdns.org and create a subdomain, for example archguard-yourname. Your address is archguard-yourname.duckdns.org.
  2. 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: ufw if it is active, or iptables rules 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

  1. In the Auth0 dashboard, open Applications and create a Regular Web Application named ArchGuard.
  2. 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
  3. Copy the Domain, Client ID and Client Secret.

Create roles and assign them

  1. Open User Management, then Roles, and create archguard-admins, archguard-architects and archguard-viewers.
  2. 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: to postgres or redis. Ports published by Docker bypass the server's own firewall (ufw or iptables) 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_app database role. Only the one-off migrate task gets the database owner password.
  • Work as the deploy user rather than root.
  • 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.