Repository navigation
Getting Started
Spotcraft runs on one server: your apps, the dashboard, Postgres and the monitoring. It deploys nothing itself: each release ships a verified bundle, and you run it on a server you own. Then you add apps from the dashboard.
You need: a GitHub account, a domain for the dashboard, and a Debian/Ubuntu server with at least 8 GB of memory. A Cloudflare account is optional: with it, the server hides behind Cloudflare and DNS is set up for you.
kodentuzo/hetzner is a template repository that does
everything from here to a running dashboard: it creates the server on Hetzner Cloud (an ARM
cax21, Debian 13, firewalled), deploys the Spotcraft version you pin, and keeps its OpenTofu
state encrypted in your own Hetzner Object Storage. Use the template and follow its guide.
Updating is bumping one version.
Prepare a server that meets the server's requirements, and deploy a release's bundle as that page describes. kodentuzo/hetzner's Deploy workflow is a working example to copy.
Pick a domain for the dashboard (e.g. dash.example.com) and, optionally, an apps domain
(e.g. example.com): every app is then served at <name>.example.com without any DNS work
per app. The apps domain must be a zone's apex (the root of a domain you own), so one
certificate covers every app.
Without Cloudflare, create these records yourself:
- A and AAAA records for the dashboard's domain, pointing at the server.
- With an apps domain, a wildcard A and AAAA record (
*.example.com) pointing at the server.
If your DNS is on Cloudflare but you don't use the module below, leave the records DNS only (not proxied). Caddy then gets the certificates itself, and the dashboard sees visitors' real addresses for its login lockout.
With Cloudflare, kodentuzo/hetzner's cloudflare/ root does it instead: a Cloudflare Tunnel
to the server, the wildcard and dashboard records, TLS and WAF settings, a rate limit on the
login page and, optionally, Cloudflare Access in front of the dashboard.
In the dashboard, choose Add app and fill in:
-
Name: lower-case letters, digits and dashes, e.g.
blog. -
Image and tag: a public image on Docker Hub, e.g.
you/blogand1.0.0. Recent tags are suggested. -
Custom domain: optional with an apps domain, since the app is always served at
<name>.<apps domain>. A root domain likeexample.comalso getswww.redirected.- Without Cloudflare: point the domain's A and AAAA records at the server, or a CNAME
at
<name>.<apps domain>. - With the Cloudflare agent settings: a domain in your Cloudflare account is set up for you. Tick Take over existing DNS records if it still points at an old server; while ticked, every deploy may replace records Spotcraft didn't make. For any other domain, the app's page shows the CNAME (and any TXT records) to add where its DNS is hosted.
- Without Cloudflare: point the domain's A and AAAA records at the server, or a CNAME
at
- Require sign-in: with Cloudflare Access, visitors must sign in as one of the owners first, for example for a staging app.
- Container port, memory and CPU limits, and environment variables.
- Analytics: on by default; turn it off for an app that mustn't count visits.
Every app gets its own schema in the instance's database, as DATABASE_URL, and the rest of
the app contract. Removing the app keeps its schema unless you also choose to
delete it.
Deploy pulls the image, waits until the app is healthy and switches traffic to it. If anything fails, you see why, and the previous version keeps running. Without Cloudflare, the certificate arrives on the first HTTPS request once DNS points at the server; behind Cloudflare, Cloudflare holds the certificates.
Apps run with a read-only filesystem by default; turn it off for apps that write outside
/tmp.
To check that everything an app gets works, deploy whoami first.
To upgrade Spotcraft, read the changelog for the new version, then deploy it:
with kodentuzo/hetzner, bump spotcraft.version and run Deploy. To roll back, deploy the
previous version. Your apps keep running
throughout; they are only restarted when a release says so.
To update an app, edit it in the dashboard and pick the new tag. To roll an app back, pick the old tag.
To move a running instance behind Cloudflare with only a few minutes' outage, follow Moving an existing instance in kodentuzo/hetzner's Cloudflare page.
- Using the dashboard: every page, for all apps and for one.
- Backups and restoring: set up nightly backups before you need them.
- Build apps: for the developers of your apps, what Spotcraft gives an app and how to work on one locally.
- Security model: what Spotcraft trusts and the risks it accepts.
Published from docs/. Edit the files there; changes here are overwritten.