diff options
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> ``` |