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-agentalso 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=falsein/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).