Skip to content
github-actions[bot] edited this page Nov 22, 2026 · 1 revision

The server

What a server needs before Spotcraft can be deployed on it. Spotcraft deploys nothing itself: each release ships a bundle, and something you run puts it on your server. On Hetzner Cloud, kodentuzo/hetzner does all of this for you, and is the recommended way.

Requirements

  • Debian 13 (or 12) or Ubuntu 24.04, 8 GB of memory or more, ARM or x86.
  • Docker with the Compose plugin, from Docker's own apt repository.
  • A deploy user that logs in with an SSH key only, in the docker group. Root and password logins are off.
  • /opt/spotcraft, owned by deploy, with apps/ and sites/ inside it owned by uid and gid 1000 (the agent's user in the image).
  • Open ports: 22 for SSH, and 80 and 443 (TCP, plus UDP 443 for HTTP/3) unless a Cloudflare Tunnel delivers the traffic. Everything else stays closed: only Caddy is published.
  • Optional but recommended: unattended security upgrades, and Docker's json-file logs capped at 3 × 10 MB.

kodentuzo/hetzner's hetzner/cloud-init.yaml sets all of this up at first boot. On another provider, use it as the server's user data, with its placeholder filled in.

The bundle

Each release has spotcraft-X.Y.Z.tar.gz, with SHA256SUMS and a GitHub attestation of its build:

Path What
server/ compose.yaml, Caddyfile, pg_hba.conf, scrape.yaml, blackbox.yml
remote-deploy.sh runs on the server: writes .env, pulls and starts everything, checks it

To deploy a release:

  1. Check it: sha256sum --check SHA256SUMS, and gh attestation verify spotcraft-X.Y.Z.tar.gz --repo kodentuzo/spotcraft.
  2. Copy server/* into /opt/spotcraft as deploy.
  3. Run remote-deploy.sh there over SSH, with its settings as export lines on its standard input, never on the command line. The script's header lists them; SPOTCRAFT_TAG is the same version as the bundle.

kodentuzo/hetzner's Deploy workflow does exactly this.

Clone this wiki locally