Servers and the panel
Cloud servers
Add server can make the machine as well, at Hetzner Cloud or DigitalOcean: it boots, installs the agent and joins by itself. Server pools go further, making and destroying servers as the fleet's load needs.
Connecting an account
Settings → System → Cloud providers (admins), or
POST /api/cloud-providers {"name", "kind": "hetzner"|"digitalocean", "token"}:
- Hetzner: a project's API token with Read & Write (Hetzner Console → the project → Security → API tokens). Machines are made in that project.
- DigitalOcean: a personal access token with write scope. It reaches
every project in the account, so pick the project new droplets go to: the
Project field on Add server (or in a pool's form), kept on the provider
(
PUT /api/cloud-providers/{id} {"project_id"}; the ids are in its options). A droplet that can't be moved into it is destroyed, and the server isn't made.
The token is checked before it's kept, sealed like other secrets. A provider can be removed once no server made with it remains: stackd needs its token to destroy those machines.
Making a server
Add server → A new cloud server: a name (it becomes the machine's name and
hostname), a region, a size and, optionally, SSH keys already in the
provider's account for root. With no key, the provider emails the root
password. The regions, sizes and prices come from the provider
(GET /api/cloud-providers/{id}/options), only what can be made where now:
types sold out, retired or not sold in a region are left out.
Or with the API:
POST /api/cloud-providers/{id}/servers {"name", "region", "size", "ssh_keys": [ids]}.
The machine runs Ubuntu 24.04 (on Hetzner's Arm types too) and installs the agent at first boot. Its provider, machine id, region and size show on the server's page. The agent usually connects 2 to 4 minutes later; the join token is valid for an hour.
If the provider refuses (a wrong size, quota, a read-only token) nothing is kept, and its reason is shown.
The machine must reach the panel: at STACKD_PUBLIC_URL when set, else at
the address you opened the panel at, which can't be localhost or 127.*.
Its agent connects to STACKD_PUBLIC_HUB, as any server's does.
Removing
Removing a server made this way offers to destroy its machine too
(DELETE /api/servers/{id}?destroy=true). The server is only removed once
the provider has destroyed the machine (one already gone counts), so
neither is left without the other. Drain it first, as any server. Without
destroy, the machine keeps running, and billing, at the provider.
Server pools
A pool makes and destroys servers at one provider as the fleet's load needs
(Settings → System → Server pools, /api/server-pools). Admins only.
- What a pool is. A provider account, a region, a size and SSH keys for
its machines, the fewest and most servers (0 to 20), and targets for the
fleet's CPU and memory (20% to 95%; 70% and 80% by default). Its servers
are named
<pool>-xxxxand showpool <name>on their pages. - The load it looks at is the whole fleet's: the cores and memory of every server online and not draining, and what they used, averaged over 5 and 15 minutes. A pool's servers take apps' replicas as any server does.
- Replicas wanting servers. Each of an app's replicas runs on a server of its own, so an app that wants more replicas than there are servers gets fewer. The pool looks at the most any running app wants: what its autoscaler wants (Autoscaling), else its replica count, and its processes' too.
- Up. Below its fewest, with an app wanting more replicas than there are servers (online, not draining or rebooting), or with the 5-minute CPU or memory over its target, a pool makes a server. One at a time: the next waits until it has joined, and 5 minutes after the last change. One that hasn't joined in 15 minutes is destroyed, and the pool says why.
- Down. Above its fewest, 15 minutes after the last change, a pool takes its newest server that's up and holds no database member (nor a panel replica). Only if the fleet's 15-minute CPU and memory without it would stay under 70% of the targets, and every app would still have a server for each replica it wants, is it drained and then deleted, its machine destroyed. A drain that fails puts the server back, and the pool says why.
- What it did. The pool shows its last change and why ("Made web-8f2a: CPU 84% over 5 minutes, above the 70% target"), and its last error; both are in the audit log as the Server autoscaler's.
- Needs
STACKD_PUBLIC_URL, the address new machines join at. A pool can't be made or turned on without one. - Changing a pool changes what its next servers get; the ones it has stay as they are. Its provider can't change. Paused, it does nothing. Deleting it leaves its servers as servers made by hand.
Limitations
- No firewall, private network, volumes or snapshots at the provider: stackd's own firewall and WireGuard mesh apply as on any server.
- A machine deleted in the provider's console shows as an offline server.
- Pools don't look at disk.