Start here

Architecture

stackd is a self-hosted platform as a service: you bring servers (bare metal or VPS), and stackd deploys apps to them and keeps those apps healthy and reachable. This page covers the parts you deal with: the panel, the agent on each server and the CLI.

The parts

  • The panel. The web UI and the HTTP API, with its own PostgreSQL. You install it on one server:

    curl -fsSL https://get.stackd.sh/install.sh | sudo sh -s -- \
      --domain panel.example.com --email [email protected] --with-agent

    --with-agent also makes that server one that runs apps. The first visitor creates the admin account; admins invite everyone else (Roles and projects).

  • The agent. A daemon on every server that runs apps. It runs the containers with Docker, the proxy that serves your domains, and sends logs and metrics to the panel. Add a server from Add server in the panel, which gives you the command to run on it, or let stackd make the machine at a cloud provider (Cloud servers).

  • The CLI. stackd, for your terminal and CI. It talks to the same HTTP API as the web UI, with an API token (The stackd CLI).

The API is documented at /api/openapi.json on your panel. Browsers sign in with a session; the CLI and scripts send Authorization: Bearer stk_… API tokens (STACKD_TOKEN).

How servers connect

  • Agents only dial out to the panel, so a server opens no inbound port for the panel to reach it.
  • Servers share a private WireGuard mesh for traffic between them (databases, volumes, load-balanced apps). It's the one inbound port a server opens for stackd: UDP 51820, for the other servers only. Database replication only listens on the mesh.
  • Agents update themselves when the panel is updated. To opt a server out, set STACKD_AUTO_UPDATE=false in /etc/stackd/agent.env.

What a server needs

  • Ports 80 and 443 open to the internet, for the proxy that serves your apps' domains.
  • UDP 51820 reachable from your other servers, for the mesh.
  • Outbound access to the panel.

Some other ports are taken by stackd on every server and can't be used by apps (Ports).

Domains and certificates

Each server's proxy (Traefik) serves the domains of the apps on it, with Let's Encrypt certificates (HTTP-01, which also works behind Cloudflare's proxy). Certificates need STACKD_ACME_EMAIL on the panel (the installer's --email); STACKD_ACME_STAGING=1 uses Let's Encrypt's staging CA while you test. A hostname without a certificate yet gets a self-signed one. See Domains.

Apps see the visitor's address in X-Forwarded-For (first entry) and X-Real-Ip, whether or not Cloudflare's proxy is in front. Forwarded headers are only trusted from Cloudflare's published ranges, so a direct visitor can't forge them.

Every app is also behind a web application firewall, and its visitors are classified on the Traffic page (Traffic intelligence).

Traffic between servers

By default each server's proxy sends an app's domains to the replica on that server, so traffic follows DNS: point the domain at the servers running the app.

With Load balance on (per app, applied at the next deploy), every server running a replica spreads requests round-robin over all of the app's healthy replicas, its own and the others' over the mesh. A request that can't reach a replica within 2 seconds is retried on another. Servers outside the mesh only serve their own replica.

Sticky sessions (per load-balanced app, applied within seconds) keep each visitor on the replica that served them first, for apps that keep sessions in memory or on local disk. They use a cookie, stackd_<app> (secure, httpOnly, SameSite=Lax), that works whichever server a request arrives at. A visitor whose replica goes away gets errors until stackd drops it from the routes (about 10 seconds for a stopped container, longer for a server that died), then moves to another replica.

Both are also settings in stackd.toml (load_balance, sticky_sessions).

High availability

Apps keep running if the panel's server goes down, but nothing can be deployed until it's back. To avoid that, run the panel on 3 or more servers (A highly available panel); otherwise, back up its database off-site (Panel backups).