Start here

Apps as code: stackd.toml

Keep your apps' settings in a stackd.toml in your repo: stackd apply makes the panel's apps match it, and stackd export writes one from what runs.

Both are CLI commands over the panel's API, so they work from a laptop or CI alike. They need a token that may change the apps: a full one, since deploy tokens can't change settings (Roles and projects).

The file

[app.web]
image = "ghcr.io/acme/web:1.4.2"   # omit for apps built from a repo
port = 8080
replicas = 2
load_balance = true
sticky_sessions = false
project = "shop"                   # a project's name
env_groups = ["shared"]            # variable groups' names
domains = ["shop.example.com", "www.shop.example.com"]
release_command = "bin/migrate"
sleep_after_minutes = 30           # 0: never (see Sleep)

[app.web.env]
RUST_LOG = "info"
STRIPE_KEY = "${STRIPE_KEY}"       # from the environment running apply

[app.web.health_check]
path = "/healthz"
interval_s = 10
timeout_s = 5
retries = 3
start_s = 30

[app.web.resources]
cpu_millis = 1000
memory_mb = 512

[app.web.autoscale]
min = 2
max = 6
target_cpu = 70        # percent; or target_rps, requests a second per replica

[app.web.processes.worker]
command = "bin/worker"
replicas = 1

[[app.web.ports]]                  # raw TCP/UDP, set as a whole (see Ports)
port = 2525
container_port = 25
allow = ["203.0.113.0/24"]

[app.web.jobs.cleanup]
schedule = "0 3 * * *"
command = "bin/cleanup"
timeout_s = 900

See Sleep, Ports, Health checks, Autoscaling, Processes and Jobs for what each section does.

Unknown keys are errors, so a typo doesn't pass silently.

${NAME} in any value is NAME from the environment stackd apply runs in, so secrets stay in CI's secrets rather than the repo. A NAME that isn't set stops the whole apply before anything changes. $ is a literal $.

What apply does

Every app in the file is checked before anything changes, so a mistake in any of them changes nothing. Then, app by app:

  • An app that doesn't exist is made (it needs an image; apps built from a repo are made in the panel first, then managed here).
  • What the file leaves out stays as it is.
  • Settings (image, port, replicas, balancing, project, variable groups), the health check, resources, autoscaling, ports, and the processes with the release command are set as the file says.
  • Variables, domains and jobs are added and changed by name. Those the file doesn't name stay, unless --prune, which removes them.
  • Nothing is sent when nothing differs: applying the same file twice changes nothing the second time.
stackd apply --dry-run          # what would change
stackd apply                    # change it; takes effect at the next deploy
stackd apply --deploy           # and deploy the apps that changed
stackd apply -f infra/stackd.toml web   # another file, one of its apps

Starting from what runs

stackd export web api > stackd.toml

Variables come out as ${NAME} placeholders, to fill from CI's secrets; --with-values writes their values instead. Apps built from a repo come out without an image.

In CI

- run: curl -fsSL https://get.stackd.sh/cli.sh | sh
- run: stackd apply --deploy
  env:
    STACKD_API: https://panel.example.com
    STACKD_TOKEN: ${{ secrets.STACKD_TOKEN }}
    STRIPE_KEY: ${{ secrets.STRIPE_KEY }}