diff options
| author | Claude <noreply@anthropic.com> | 2026-08-06 23:22:03 -0500 |
|---|---|---|
| committer | Claude <noreply@anthropic.com> | 2026-08-06 23:22:03 -0500 |
| commit | f34ba20fc566ab861179a8ac2fd55eaabbc6a327 (patch) | |
| tree | f3b421a59cff06d1fa83ae3f75065971dcc750df /USER_GUIDE.md | |
| parent | fc0c6951d7ac36dd8f30ace929991197dc99ae54 (diff) | |
Add skiff config set/unset/list, backed by /app/env in the app's dataset
Config vars are plain env vars, injected into both the running app (via
rc.d) and the release phase, and versioned on the same ZFS snapshot
timeline as deploys - a bad config change gets the same automatic
snapshot/restart/health-check/rollback guarantee a bad deploy already
gets. Extracts deploy.go's health check into internal/health so both
paths share it.
Verified end-to-end against a FreeBSD VM: config set/unset, automatic
rollback on a health-check failure, and explicit `skiff rollback` all
correctly carry the env file along with the rest of the dataset.
Diffstat (limited to 'USER_GUIDE.md')
| -rw-r--r-- | USER_GUIDE.md | 40 |
1 files changed, 33 insertions, 7 deletions
diff --git a/USER_GUIDE.md b/USER_GUIDE.md index 5ff93f1..04ec92e 100644 --- a/USER_GUIDE.md +++ b/USER_GUIDE.md @@ -104,13 +104,35 @@ Skiff has no opinion on your language - the entire build/run contract is a care how the target is defined, only whether bmake thinks it exists. - Persistent state: `/app/data.db` and `/app/env` (jail-relative paths, - siblings of `/app/current`) are meant to be your durable state, - untouched by any single release's checkout/build. In practice today - this is a *convention*, not something Skiff actively manages for you - - there's no automatic env-var injection or database provisioning. If you - want a SQLite file that survives every deploy, just open it at - `/app/data.db` yourself and it'll sit outside the `releases/<sha>` - directories that get replaced on every push. + siblings of `/app/current`) are your durable state, untouched by any + single release's checkout/build. If you want a SQLite file that + survives every deploy, just open it at `/app/data.db` yourself and + it'll sit outside the `releases/<sha>` directories that get replaced on + every push. + + `/app/env` is actively managed by Skiff via `skiff config`: + + ``` + # skiff config set --app myapp GREETING=Howdy SECRET=abc123 + # skiff config list --app myapp + # skiff config unset --app myapp SECRET + ``` + + `set` merges into the existing config (keys you don't mention are left + alone); `unset` removes the keys you name. Multiple `KEY=VALUE` pairs + in one `set` call are applied atomically. Every var is plumbed in as a + plain environment variable - `os.Getenv("GREETING")` in Go, no bespoke + file format for your app to parse - and reaches both the running app + and any release-phase Makefile target. + + A config change carries the exact same safety guarantee as a code + deploy: Skiff snapshots the app's dataset first, restarts the jail, + waits for the health check, and automatically rolls back to the + pre-change snapshot if the app doesn't come back healthy. There's no + weaker, second-tier safety story for config versus code - `skiff + rollback --list` shows both `pre-<sha>` (deploy) and `precfg-<epoch>` + (config) snapshots interleaved, and `skiff rollback --to` reverts + either kind. ### Deploying @@ -403,4 +425,8 @@ skiff deploy --app <app> --new <sha> [--ref refs/heads/main] [--old <sha>] skiff rollback --app <app> --list skiff rollback --app <app> --to <snapshot-tag> + +skiff config set --app <app> KEY=VALUE [KEY=VALUE...] +skiff config unset --app <app> KEY [KEY...] +skiff config list --app <app> ``` |
