okengine 0.9.0 → 0.10.0

package/site/content/docs/recipes/openbao.mdx

@@ -0,0 +1,141 @@
+---
+title: "OpenBao"
+description: "Durable single-node vault — Raft under /openbao/file, OKE_VAULT_URL / OKE_VAULT_TOKEN, host unseal key SPOF."
+icon: "KeyRound"
+source: "docs/spec/unified-theory.md"
+---
+
+OpenBao is the docker/prod Vault driver target — a real secrets service with Raft
+storage, **not** an in-memory `-dev` server. Templates pin
+`vault: "openbao/openbao:2.6.1"` and `drivers.vault.docker/prod: "openbao"`.
+
+<Callout title="The one rule">
+  Never run OpenBao `-dev` in docker/prod. Data belongs on the Raft volume; init + unseal stay on
+  the host under `.oke/openbao/`.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin driver + image
+
+```typescript title="oke.config.ts"
+drivers: {
+  vault: { local: "env", docker: "openbao", test: "memory", prod: "openbao" },
+},
+images: {
+  vault: "openbao/openbao:2.6.1",
+},
+```
+
+</Step>
+
+<Step>
+### First boot is automatic
+
+`oke dev --docker` initializes OpenBao (Shamir 1-of-1), unseals it, writes a
+least-privilege policy for **declared** secrets only, and mints an app token. You do not
+run raw `bao` commands.
+
+</Step>
+
+<Step>
+### App sees only the least-privilege token
+
+```bash title="docker/.env.docker"
+OKE_VAULT_URL=http://127.0.0.1:8200
+OKE_VAULT_TOKEN=…        # app token — not the root token
+OKE_VAULT_MOUNT=secret   # KV v2 mount (default)
+```
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable           | Who holds it        | Meaning                                  |
+| ------------------ | ------------------- | ---------------------------------------- |
+| `OKE_VAULT_URL`    | App / stack         | OpenBao base URL                         |
+| `OKE_VAULT_TOKEN`  | App (`.env.docker`) | Least-privilege app token                |
+| `OKE_VAULT_MOUNT`  | Optional            | KV v2 mount path (default `"secret"`)    |
+| `BAO_LOCAL_CONFIG` | Container (recipe)  | Listener + Raft JSON — set by the recipe |
+
+Host-only material (mode `0600`, gitignored) — **not** in compose YAML:
+
+| File                      | Holds                                    |
+| ------------------------- | ---------------------------------------- |
+| `.oke/openbao/unseal.key` | Single unseal share                      |
+| `.oke/openbao/root.token` | Root token (CLI policy sync / mint only) |
+| `.oke/openbao/app.token`  | Same least-privilege token the app uses  |
+
+## Data and backup
+
+| Volume       | Path            | What it stores               |
+| ------------ | --------------- | ---------------------------- |
+| `vault-data` | `/openbao/file` | Raft storage (node id `oke`) |
+
+Recipe note: Raft path is `/openbao/file` (the stock entrypoint chowns that directory).
+Healthcheck hits `/v1/sys/init` — **200 even while sealed**; bootstrap owns unseal.
+
+**Backup means two things:**
+
+1. The Raft volume (`/openbao/file`) — encrypted secret store
+2. `.oke/openbao/unseal.key` on the host — without it the volume is unrecoverable
+
+## Production note
+
+<Callout title="Single point of failure — read this once" type="warn">
+  Back up `.oke/openbao/unseal.key` to a separate safe location. Losing it means losing every secret
+  permanently, with no recovery. Restated from [Vault ·
+  OpenBao](/docs/elements/vault#openbao-in-docker-and-prod).
+</Callout>
+
+Self-hosted single-node, Shamir 1-of-1, no cloud KMS — by design. If OpenBao is
+initialized but the key is gone, boot fails with an explicit permanent-loss error; it
+never silently starts empty.
+
+## What the recipe configures
+
+| Field          | Value                                                                                  |
+| -------------- | -------------------------------------------------------------------------------------- |
+| Container port | `8200`                                                                                 |
+| Command        | `server` (with `BAO_LOCAL_CONFIG`)                                                     |
+| TLS            | Disabled on the listener for compose (`tls_disable: true`) — rely on network isolation |
+| Healthcheck    | `wget` `/v1/sys/init`, every 5s, 12 retries                                            |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="openbao vault: GET … failed (… ) — sealed or unauthorized?">
+
+`OpenBaoUnavailableError` — vault sealed, wrong token, or unreachable. Re-run
+`oke dev --docker` so bootstrap unseals with the host key. If the vault is initialized
+but `.oke/openbao/unseal.key` is missing, restore the key from backup.
+
+</Accordion>
+<Accordion title="Permanent-loss / initialized but key missing">
+
+Starting empty would look like “no secrets.” The CLI refuses that path. Restore
+`unseal.key` or treat the Raft volume as destroyed and re-init only if you accept wiping
+secrets.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Vault · OpenBao in docker and prod](/docs/elements/vault#openbao-in-docker-and-prod) —
+  full bootstrap, key table, SPOF callout
+- [Errors](/docs/reference/errors) — `OpenBaoUnavailableError`, `OpenBaoBootstrapError`
+- [CLI · oke vault](/docs/reference/cli) — `set` / `list` / `import`
+
+## Next
+
+<Cards>
+  <Card title="Vault" description="Resolution chain and rotation." href="/docs/elements/vault" />
+  <Card title="Mailpit" description="Local email catcher." href="/docs/recipes/mailpit" />
+  <Card title="RustFS" description="S3-compatible files." href="/docs/recipes/rustfs" />
+</Cards>

package/site/content/docs/recipes/pgdog.mdx

@@ -0,0 +1,137 @@
+---
+title: "PgDog"
+description: "Postgres wire-protocol pooler — transaction mode on :6432, generated pgdog.toml / users.toml, DATABASE_URL rewrite."
+icon: "Package"
+source: "docs/spec/unified-theory.md"
+---
+
+Bun.SQL defaults to **10** connections per process. Scale to several app instances and
+`N × pool` can exceed Postgres `max_connections`. PgDog sits in front of `store.sql` as a
+transaction-pooling proxy — same wire protocol, no app code changes.
+
+<Callout title="The one rule">
+  Pin `pgdog` alongside `store.sql` and `DATABASE_URL` automatically points at the pooler on `:6432`
+  instead of Postgres directly — Bun.SQL and Drizzle see no difference.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin both images
+
+```typescript title="oke.config.ts"
+images: {
+  "store.sql": "postgres:18-alpine",
+  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
+},
+```
+
+</Step>
+
+<Step>
+### Derive compose
+
+```bash
+oke docker
+```
+
+Writes `./pgdog.toml` (listen + one primary database) and `./users.toml` (same
+user/password/database as Postgres). The pooler waits on `store-sql` health before start.
+
+</Step>
+
+<Step>
+### Confirm the rewrite
+
+```bash
+echo "$DATABASE_URL"
+# …@host:6432/db  ← pooler, not :5432
+echo "$OKE_STORE_SQL_URL"   # still the direct Postgres URL when you need it
+```
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                                 | Role                                                             |
+| ---------------------------------------- | ---------------------------------------------------------------- |
+| `OKE_STORE_SQL_USER` / `PASSWORD` / `DB` | Copied into `users.toml` for client + server auth                |
+| `DATABASE_URL`                           | Rewritten to the pooler URL (`:6432`) when PgDog is in the stack |
+| `OKE_PGDOG_URL`                          | Same value as pooled `DATABASE_URL` when both are present        |
+| `OKE_STORE_SQL_URL`                      | Direct Postgres host — bypass the pooler for admin / migrations  |
+
+PgDog itself has no separate credential env — it mounts the generated TOML files read-only.
+
+## Data and backup
+
+| Mount                               | What it is                                                         |
+| ----------------------------------- | ------------------------------------------------------------------ |
+| `./pgdog.toml:/pgdog/pgdog.toml:ro` | Generated listen + `[[databases]]` (host `store-sql`, port `5432`) |
+| `./users.toml:/pgdog/users.toml:ro` | Generated `[[users]]` credentials                                  |
+
+**No database state lives in the PgDog container.** Backing up PgDog means keeping those
+two config files (they are regenerated by `oke docker`). Durable data stays on the
+[Postgres](/docs/recipes/postgres) volume / dump.
+
+## Production note
+
+Pooling mode is `transaction` — set explicitly (also PgDog's upstream default). Naive
+poolers can leak session state (`SET`, RLS vars, `LISTEN`/`NOTIFY`) across clients;
+PgDog re-applies that state per transaction.
+
+**Do not stack** PgDog in front of a managed pooler (Neon `-pooler`, Supabase Supavisor
+`:6543`). Pick one pooler. Use `OKE_STORE_SQL_URL` (direct) for migrations and anything
+that needs session features.
+
+Read-replica routing (`BEGIN READ ONLY` → replica) is documented readiness in PgDog —
+not wired into the generated stack yet.
+
+## What the recipe configures
+
+| Field          | Value                                                   |
+| -------------- | ------------------------------------------------------- |
+| Container port | `6432`                                                  |
+| `dependsOn`    | `store-sql` healthy                                     |
+| Healthcheck    | `pg_isready -h 127.0.0.1 -p 6432`, every 5s, 12 retries |
+| Connection URL | `postgres://user:pass@host:6432/db`                     |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="pgdog unhealthy — pg_isready on :6432 fails">
+
+Usually the backend is not ready, or `users.toml` credentials do not match Postgres.
+Confirm `store-sql` is healthy first, then re-run `oke docker` so TOML matches
+`OKE_STORE_SQL_*`. Logs often show auth failures against `store-sql:5432`.
+
+</Accordion>
+<Accordion title="Session features break through the pooler">
+
+Transaction mode does not preserve session-scoped state the way a direct connection
+does. Point migrations / `LISTEN` / session `SET` at `OKE_STORE_SQL_URL` (direct
+Postgres), keep `DATABASE_URL` on the pooler for app traffic.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Docker · PgDog pooling](/docs/deployment/docker#pgdog-pooling) — compose `-f` layer order
+- [Postgres](/docs/recipes/postgres) — the backend PgDog fronts
+- [Store · SQL](/docs/elements/store#sql) — “Connection pooling is infrastructure”
+
+## Next
+
+<Cards>
+  <Card title="Postgres" description="The backend PgDog fronts." href="/docs/recipes/postgres" />
+  <Card
+    title="Supabase"
+    description="Also Postgres wire — same pooler applies."
+    href="/docs/recipes/supabase-docker"
+  />
+  <Card title="Caddy" description="TLS at the edge, once you need it." href="/docs/recipes/caddy" />
+</Cards>

package/site/content/docs/recipes/postgres.mdx

@@ -0,0 +1,136 @@
+---
+title: "Postgres"
+description: "Default store.sql image — POSTGRES_* env, PGDATA path, and when DATABASE_URL points at PgDog instead."
+icon: "Database"
+source: "docs/spec/unified-theory.md"
+---
+
+Postgres is the default `store.sql` image in docker and prod. `oke docker` matches
+any image whose reference contains `postgres` or `pgvector` (after more specific
+recipes), then derives env, healthcheck, and connection URL.
+
+<Callout title="The one rule">
+  The driver id stays `postgres` no matter which Postgres-wire image you pin — vendor choice lives
+  in `images["store.sql"]`, not in `drivers.store.sql`.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the image
+
+```typescript title="oke.config.ts"
+images: {
+  "store.sql": "postgres:18-alpine", // any Postgres / pgvector image
+},
+```
+
+</Step>
+
+<Step>
+### Bring the stack up
+
+```bash
+oke dev --docker
+```
+
+`oke docker` writes `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` into
+`docker/.env.docker` as `${OKE_STORE_SQL_USER}` / `${OKE_STORE_SQL_PASSWORD}` /
+`${OKE_STORE_SQL_DB}` refs — never literal secrets in compose YAML.
+
+</Step>
+
+<Step>
+### Connect
+
+```bash
+# App reads this (also accepts OKE_STORE_SQL_URL)
+echo "$DATABASE_URL"
+# postgres://oke:…@127.0.0.1:5432/oke
+```
+
+When PgDog is pinned, `DATABASE_URL` points at `:6432` instead — see
+[PgDog](/docs/recipes/pgdog).
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                 | Who sets it            | Meaning                              |
+| ------------------------ | ---------------------- | ------------------------------------ |
+| `OKE_STORE_SQL_USER`     | `oke docker` → compose | Injected as `POSTGRES_USER`          |
+| `OKE_STORE_SQL_PASSWORD` | `oke docker` → compose | Injected as `POSTGRES_PASSWORD`      |
+| `OKE_STORE_SQL_DB`       | `oke docker` → compose | Injected as `POSTGRES_DB`            |
+| `DATABASE_URL`           | stack env for the app  | What Bun.SQL / Drizzle actually open |
+| `PGDATA`                 | stack default          | `/var/lib/postgresql/data/pgdata`    |
+| `POSTGRES_INITDB_ARGS`   | stack default          | `--data-checksums`                   |
+
+## Data and backup
+
+| Path                                          | What lives there                                     |
+| --------------------------------------------- | ---------------------------------------------------- |
+| `$PGDATA` (`/var/lib/postgresql/data/pgdata`) | Cluster data directory                               |
+| Image `VOLUME` `/var/lib/postgresql/data`     | Official image mount — Docker attaches a volume here |
+
+The recipe does **not** declare a named compose volume. Persistence rides the image's
+`VOLUME` (anonymous unless you add a named mount in `compose.override.yml`).
+
+**Backup means:** `pg_dump` / `pg_dumpall`, or a Docker volume backup of
+`/var/lib/postgresql/data`. Losing that volume loses the cluster.
+
+## Production note
+
+For multi-replica apps, keep SQL on a shared Postgres — Clock CronStore and durable
+journal need one backend. See [Clock](/docs/elements/clock#what-the-runtime-guarantees) ·
+[Docker](/docs/deployment/docker#share-backing-services).
+
+Scale out with [PgDog](/docs/recipes/pgdog) so `N × Bun.SQL pool` does not exhaust
+`max_connections`. Do not also stack a managed provider's pooler on the same URL.
+
+## What the recipe configures
+
+| Field          | Value                                                |
+| -------------- | ---------------------------------------------------- |
+| Container port | `5432`                                               |
+| Healthcheck    | `pg_isready -U $POSTGRES_USER`, every 5s, 10 retries |
+| Connection URL | `postgres://user:pass@host:5432/db`                  |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="oke boot: postgres driver needs DATABASE_URL">
+
+The `postgres` driver fails boot when neither `DATABASE_URL` nor `OKE_STORE_SQL_URL` is
+set. Re-run `oke dev --docker` so the stack writes `docker/.env.docker`, or export
+`DATABASE_URL` yourself when pointing at a managed host.
+
+</Accordion>
+<Accordion title="pg_isready fails / store-sql unhealthy">
+
+Wrong `POSTGRES_USER` or the container is still initializing. Check
+`docker compose … logs store-sql` for `database system is ready to accept connections`.
+
+Credential refs must resolve in `.env.docker` — empty `${OKE_STORE_SQL_PASSWORD}` leaves
+Postgres refusing auth.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [PgDog](/docs/recipes/pgdog) — transaction pooling in front of this recipe
+- [Store · SQL](/docs/elements/store#sql) — schema push / generate / migrate
+- [Environment variables](/docs/reference/environment-variables) — `DATABASE_URL` precedence
+- [Neon](/docs/providers/neon) · [Supabase](/docs/providers/supabase) — managed alternatives
+
+## Next
+
+<Cards>
+  <Card title="PgDog" description="Add pooling in front of Postgres." href="/docs/recipes/pgdog" />
+  <Card title="Neon" description="A managed alternative." href="/docs/providers/neon" />
+  <Card title="Redis" description="The default store.kv image." href="/docs/recipes/redis" />
+</Cards>

package/site/content/docs/recipes/redis.mdx

@@ -0,0 +1,130 @@
+---
+title: "Redis"
+description: "Default store.kv image — OKE_STORE_KV_PASSWORD, maxmemory policy, ephemeral data, REDIS_URL."
+icon: "Zap"
+source: "docs/spec/unified-theory.md"
+---
+
+Redis is the default `store.kv` image in docker and prod. `oke docker` matches image
+references containing `redis` or `keydb` and derives a password-required server — no
+unauthenticated instance.
+
+<Callout title="The one rule">
+  The driver id stays `redis` for every Redis-wire image — Redis, Valkey, Dragonfly, or a managed
+  provider. Vendor choice lives in `images["store.kv"]`, never in `drivers.store.kv`.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the image
+
+```typescript title="oke.config.ts"
+images: {
+  "store.kv": "redis:8-alpine",
+},
+```
+
+</Step>
+
+<Step>
+### Required password
+
+```bash title="docker/.env.docker (written by oke docker)"
+OKE_STORE_KV_PASSWORD=…
+REDIS_URL=redis://:…@127.0.0.1:6379
+```
+
+The recipe runs:
+
+`redis-server --requirepass "$OKE_STORE_KV_PASSWORD" --maxmemory … --maxmemory-policy …`
+
+</Step>
+
+<Step>
+### Optional memory caps
+
+| Variable                        | Default in recipe                                       | Meaning  |
+| ------------------------------- | ------------------------------------------------------- | -------- |
+| `OKE_STORE_KV_MAXMEMORY`        | `0` (unlimited) in command; stack often sets `256mb`    | Max RSS  |
+| `OKE_STORE_KV_MAXMEMORY_POLICY` | `noeviction` in command; stack often sets `allkeys-lru` | Eviction |
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                        | Required?     | Meaning                                                            |
+| ------------------------------- | ------------- | ------------------------------------------------------------------ |
+| `OKE_STORE_KV_PASSWORD`         | **Yes**       | `--requirepass` — empty password is not a valid production posture |
+| `REDIS_URL`                     | **Yes** (app) | What the `redis` driver opens (`OKE_STORE_KV_URL` also works)      |
+| `OKE_STORE_KV_MAXMEMORY`        | Optional      | Cap memory                                                         |
+| `OKE_STORE_KV_MAXMEMORY_POLICY` | Optional      | Eviction when at cap                                               |
+
+## Data and backup
+
+The Redis recipe declares **no named volume**. Process memory is the source of truth;
+a container recreate loses keys unless you add persistence yourself
+(`compose.override.yml` + Redis AOF/RDB).
+
+**Backup means (default recipe):** treat KV as a cache — rebuild from SQL / files, or
+add an explicit volume + `SAVE`/`BGSAVE` policy before you rely on durability.
+
+## Production note
+
+<Callout title="License note" type="warn">
+  Redis ≥8 is dual-licensed RSALv2 / SSPLv1 / AGPLv3. Those terms restrict offering Redis itself as
+  a managed service to third parties — running it for your own app is unaffected. Prefer
+  [Valkey](/docs/recipes/valkey) when the managed-service restriction matters.
+</Callout>
+
+Multi-replica Gate rate counters and Signal need a **shared** Redis URL — an in-process
+`memory` driver is per instance. Same shared-store idea as
+[Clock](/docs/elements/clock#what-the-runtime-guarantees) for cron exclusivity.
+
+## What the recipe configures
+
+| Field          | Value                                                |
+| -------------- | ---------------------------------------------------- |
+| Container port | `6379`                                               |
+| Healthcheck    | `redis-cli -a <password> ping`, every 5s, 10 retries |
+| Connection URL | `redis://:pass@host:6379`                            |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="oke boot: redis driver needs REDIS_URL">
+
+Missing `REDIS_URL` fails boot loudly — never a silent fallback to `memory`. Re-run
+`oke dev --docker` or export `REDIS_URL` when using a managed host. In docker mode the
+message asks whether `oke dev -d` wrote `docker/.env.docker`.
+
+</Accordion>
+<Accordion title="NOAUTH Authentication required">
+
+`REDIS_URL` is missing the password, or it does not match `OKE_STORE_KV_PASSWORD`.
+Format must be `redis://:PASSWORD@host:6379` (colon before the password, empty username).
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Store · KV](/docs/elements/store#kv) — TTL physics, per-driver behavior, license table
+- [Valkey](/docs/recipes/valkey) · [Dragonfly](/docs/recipes/dragonfly) — Redis-wire peers
+- [Environment variables](/docs/reference/environment-variables) — `REDIS_URL` precedence
+
+## Next
+
+<Cards>
+  <Card title="Valkey" description="Permissive-licensed alternative." href="/docs/recipes/valkey" />
+  <Card title="Redis Cloud" description="Managed Redis." href="/docs/providers/redis-cloud" />
+  <Card
+    title="Upstash"
+    description="Serverless Redis-protocol option."
+    href="/docs/providers/upstash"
+  />
+</Cards>

package/site/content/docs/recipes/rustfs.mdx

@@ -0,0 +1,148 @@
+---
+title: "RustFS"
+description: "S3-compatible object store — S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY, /data volume, console on :9001."
+icon: "HardDrive"
+source: "docs/spec/unified-theory.md"
+---
+
+RustFS is the default docker `store.files` image — an Apache-2.0 S3-compatible object
+store (MinIO alternative). Driver id stays `s3`; Bun binds `Bun.S3Client` against the
+endpoint.
+
+<Callout title="The one rule">
+  Protocol name is `s3` — vendor choice is the image pin (`rustfs/rustfs:…`) plus `S3_ENDPOINT`.
+  Never invent a `rustfs` driver id.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin driver + image (templates already do)
+
+```typescript title="oke.config.ts"
+drivers: {
+  store: {
+    files: { local: "fs", docker: "s3", test: "memory", prod: "s3" },
+  },
+},
+images: {
+  "store.files": "rustfs/rustfs:1.0.0-beta.11",
+},
+```
+
+</Step>
+
+<Step>
+### Credentials and endpoint
+
+```bash title="docker/.env.docker (written by oke docker)"
+S3_ACCESS_KEY_ID=…
+S3_SECRET_ACCESS_KEY=…
+S3_BUCKET=oke
+S3_ENDPOINT=http://127.0.0.1:9000
+S3_URL=http://…@127.0.0.1:9000/oke
+S3_REGION=us-east-1
+S3_CONSOLE_URL=http://127.0.0.1:9001
+```
+
+Recipe maps:
+
+- `RUSTFS_ACCESS_KEY=${S3_ACCESS_KEY_ID}`
+- `RUSTFS_SECRET_KEY=${S3_SECRET_ACCESS_KEY}`
+- `RUSTFS_CONSOLE_ENABLE=true`
+- `RUSTFS_ADDRESS=:9000`
+- command: `/data`
+
+</Step>
+
+<Step>
+### Put an object
+
+Any flow using `fx.store` files (`put` / `get`) against the `s3` driver talks to this
+endpoint. Open `S3_CONSOLE_URL` for a browser console on port **9001**.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable               | Required?         | Meaning                                    |
+| ---------------------- | ----------------- | ------------------------------------------ |
+| `S3_ACCESS_KEY_ID`     | **Yes**           | Access key → `RUSTFS_ACCESS_KEY`           |
+| `S3_SECRET_ACCESS_KEY` | **Yes**           | Secret key → `RUSTFS_SECRET_KEY`           |
+| `S3_BUCKET`            | **Yes** (app)     | Bucket name the driver opens               |
+| `S3_ENDPOINT`          | **Yes** (non-AWS) | Origin `http://host:9000`                  |
+| `S3_REGION`            | Optional          | Default `us-east-1` in stack env           |
+| `S3_SESSION_TOKEN`     | Optional          | Temporary creds                            |
+| `S3_CONSOLE_URL`       | Written by stack  | UI on `:9001` — not required by the driver |
+| `S3_URL`               | Written by stack  | Credentialed URL form                      |
+
+## Data and backup
+
+| Volume             | Path    | What it stores                 |
+| ------------------ | ------- | ------------------------------ |
+| `store-files-data` | `/data` | Object bytes + RustFS metadata |
+
+**Backup means:** snapshot that named volume (or `aws s3 sync` against the API).
+Deleting the volume deletes every object.
+
+Credentials live in `.env.docker`, not in `/data` — rotate keys without wiping objects.
+Losing both volume and keys means full restore from backup only.
+
+## Production note
+
+For cloud prod, point the same `s3` driver at real S3 / R2 / GCS interop by changing
+`S3_ENDPOINT` + keys — keep the driver id. Self-hosted RustFS on a single node is a
+durability SPOF: put the `/data` volume on reliable disks and back it up.
+
+Do not publish `:9000` / `:9001` on the public internet without TLS and network policy —
+the recipe enables the console for local ops.
+
+## What the recipe configures
+
+| Field          | Value                                                                   |
+| -------------- | ----------------------------------------------------------------------- |
+| API port       | `9000`                                                                  |
+| Extra port     | `9001` → console                                                        |
+| Healthcheck    | `curl -f http://127.0.0.1:9000/health`, every 5s, 12 retries, 10s start |
+| Connection URL | `http://user:pass@host:9000/bucket`                                     |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="oke boot: redis / meilisearch / S3 URL missing — S3_BUCKET">
+
+Files on the `s3` driver need `S3_BUCKET` (or `OKE_STORE_FILES_DB`). Without it the
+facet cannot open. Re-run `oke dev --docker` so stack env fills `S3_*`, or export them
+for a managed bucket.
+
+</Accordion>
+<Accordion title="Access Denied / signature errors against :9000">
+
+`S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY` do not match `RUSTFS_*` inside the
+container, or `S3_ENDPOINT` points at the wrong host/port. Align `.env.docker` with the
+running service; confirm health at `/health` before debugging client signatures.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Store · Files](/docs/elements/store#files) — facet API and drivers
+- [Environment variables](/docs/reference/environment-variables) — full `S3_*` map
+- [Installation](/docs/get-started/installation) — docker env cheat sheet
+
+## Next
+
+<Cards>
+  <Card
+    title="Mailpit"
+    description="SMTP catcher for the same stack."
+    href="/docs/recipes/mailpit"
+  />
+  <Card title="OpenBao" description="Vault for secrets." href="/docs/recipes/openbao" />
+  <Card title="Store" description="Files facet details." href="/docs/elements/store" />
+</Cards>