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 = 900See 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 appsStarting from what runs
stackd export web api > stackd.tomlVariables 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 }}