okengine 0.9.1 → 0.10.0

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

@@ -0,0 +1,139 @@
+---
+title: "Meilisearch"
+description: "Full-text store.index image — OKE_STORE_INDEX_URL, OKE_STORE_INDEX_KEY / MEILI_MASTER_KEY, /meili_data volume."
+icon: "Search"
+source: "docs/spec/unified-theory.md"
+---
+
+Meilisearch backs the `meilisearch` index driver — typo-tolerant full-text search over
+HTTP. Pin `images["store.index"]` and set `drivers.store.index` to `meilisearch` where
+you need it (index does **not** auto-promote in docker).
+
+<Callout title="The one rule">
+  Index stays `memory` in every environment until you set the driver map explicitly — there is no
+  silent docker fallback to Meilisearch or pgvector.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Declare driver + image
+
+```typescript title="oke.config.ts"
+drivers: {
+  store: {
+    index: { local: "memory", docker: "meilisearch", prod: "meilisearch" },
+  },
+},
+images: {
+  "store.index": "getmeili/meilisearch:v1.14",
+},
+```
+
+</Step>
+
+<Step>
+### Keys written by oke docker
+
+```bash title="docker/.env.docker"
+OKE_STORE_INDEX_URL=http://127.0.0.1:7700
+OKE_STORE_INDEX_KEY=…          # also accepted as MEILI_MASTER_KEY
+```
+
+Recipe injects into the container:
+
+- `MEILI_MASTER_KEY=${OKE_STORE_INDEX_KEY}`
+- `MEILI_ENV=${OKE_MEILI_ENV:-production}`
+- `MEILI_NO_ANALYTICS=true`
+
+</Step>
+
+<Step>
+### Search from a flow
+
+Use `store.index(…)` without `{ dims }` for full-text (vector dims select pgvector /
+libsql). Writes wait on Meilisearch tasks before returning.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable              | Required?            | Meaning                                          |
+| --------------------- | -------------------- | ------------------------------------------------ |
+| `OKE_STORE_INDEX_URL` | **Yes**              | Base URL — boot fails without it                 |
+| `OKE_STORE_INDEX_KEY` | **Yes** (production) | Master/API key; falls back to `MEILI_MASTER_KEY` |
+| `MEILI_MASTER_KEY`    | Alternate            | Same secret, container-side name                 |
+| `OKE_MEILI_ENV`       | Optional             | Passed as `MEILI_ENV` (default `production`)     |
+
+## Data and backup
+
+| Volume             | Path          | What it stores               |
+| ------------------ | ------------- | ---------------------------- |
+| `store-index-data` | `/meili_data` | Indexes, documents, settings |
+
+**Backup means:** snapshot/restore that named volume (or Meilisearch dumps). Recreating
+the container **keeps** data if the volume remains; deleting the volume wipes every index.
+
+The master key is **not** inside the volume — it lives in `.env.docker` / secrets.
+Losing the key without a backup blocks admin API access even if data remains.
+
+## Production note
+
+Always set a non-empty `OKE_STORE_INDEX_KEY` when `MEILI_ENV=production` — Meilisearch
+refuses insecure production mode without a master key. Prefer network isolation (compose
+network only) plus the key; do not publish `:7700` on the public internet without auth.
+
+Vector `ai.embed` into a meilisearch index fails loud — embeddings need `pgvector` /
+`libsql`, not FTS. See [Store · Index](/docs/elements/store#index).
+
+## What the recipe configures
+
+| Field          | Value                                          |
+| -------------- | ---------------------------------------------- |
+| Container port | `7700`                                         |
+| Healthcheck    | `wget` against `/health`, every 5s, 12 retries |
+| Connection URL | `http://host:7700`                             |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="oke boot: meilisearch index needs OKE_STORE_INDEX_URL">
+
+No silent memory fallback. Re-run `oke dev --docker` or export `OKE_STORE_INDEX_URL`.
+Docker-mode wording asks whether `docker/.env.docker` was written.
+
+</Accordion>
+<Accordion title="meilisearch index: GET/POST … failed (403) — or master key errors">
+
+`OKE_STORE_INDEX_KEY` does not match `MEILI_MASTER_KEY` inside the container, or the key
+was rotated without updating the app env. Align both sides and restart. Unreachable host
+surfaces as `meilisearch index: unreachable at <url> — …`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Store · Index](/docs/elements/store#index) — FTS vs vector drivers
+- [Environment variables](/docs/reference/environment-variables) — index URL / key
+- [Configuration](/docs/reference/configuration) — `drivers.store.index` union
+
+## Next
+
+<Cards>
+  <Card
+    title="llama.cpp"
+    description="Default local AI for the same stack."
+    href="/docs/recipes/llama-cpp"
+  />
+  <Card
+    title="Postgres"
+    description="pgvector alternative for embeddings."
+    href="/docs/recipes/postgres"
+  />
+  <Card title="Store" description="Index facet API." href="/docs/elements/store" />
+</Cards>

package/site/content/docs/recipes/meta.json

@@ -0,0 +1,31 @@
+{
+  "title": "Recipes",
+  "icon": "Container",
+  "pages": [
+    "index",
+    "---SQL---",
+    "postgres",
+    "supabase-docker",
+    "cockroachdb",
+    "yugabytedb",
+    "timescale",
+    "---KV---",
+    "redis",
+    "valkey",
+    "dragonfly",
+    "---Proxy---",
+    "caddy",
+    "traefik",
+    "---Services---",
+    "pgdog",
+    "rustfs",
+    "mailpit",
+    "openbao",
+    "meilisearch",
+    "---AI---",
+    "llama-cpp",
+    "ollama",
+    "vllm",
+    "sglang"
+  ]
+}

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

@@ -0,0 +1,142 @@
+---
+title: "Ollama"
+description: "Fully supported local AI alternative — OKE_AI_URL, pinned ≥ 0.17.1, loopback-only publish, library models only."
+icon: "Bot"
+source: "docs/spec/unified-theory.md"
+---
+
+Ollama remains a **fully supported** local model server (not deprecated). The
+default local pin is [llama.cpp](/docs/recipes/llama-cpp); choose Ollama when you
+want its library pull UX. Pin `images.ai` and set `drivers.ai` to `ollama`.
+
+<Callout title="The one rule">
+  Pin ≥ `0.17.1` (never `latest`), publish only on loopback, and load models only from Ollama’s
+  library — never arbitrary untrusted GGUF via `/api/create`.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin driver + image
+
+```typescript title="oke.config.ts"
+drivers: {
+  ai: { local: "ollama", docker: "ollama", test: "mock" }, // prod: set deliberately
+},
+images: {
+  ai: "ollama/ollama:0.32.6", // never :latest — floor 0.17.1 (CVE-2026-7482)
+},
+```
+
+Or run `oke ai setup --provider ollama --yes`.
+
+</Step>
+
+<Step>
+### Env written by the stack
+
+```bash title="docker/.env.docker"
+OKE_AI_URL=http://127.0.0.1:11434
+OKE_AI_MODEL=qwen3.5:9b
+```
+
+Host publish is `127.0.0.1:11434:11434`. Inside the container
+`OLLAMA_HOST=0.0.0.0:11434` so Docker networking works.
+
+</Step>
+
+<Step>
+### Boot pulls against the container API
+
+After compose is healthy, `oke dev -d` shows `OKE_AI_MODEL` in the hero / Docker
+summary, POSTs `/api/pull` to **this container’s**
+loopback URL when the recipe is Ollama — never a host `ollama` CLI.
+
+</Step>
+
+</Steps>
+
+## Security (hard requirements)
+
+| Control        | Requirement                                                                |
+| -------------- | -------------------------------------------------------------------------- |
+| Host publish   | `127.0.0.1:11434:11434` only — never `0.0.0.0`                             |
+| Image pin      | Explicit tag ≥ **0.17.1** (CVE-2026-7482); never `latest`                  |
+| Model source   | [Ollama library](https://ollama.com/library) only                          |
+| Untrusted GGUF | **Forbidden** — `/api/create` with crafted files is the CVE-2026-7482 path |
+
+Ollama and llama.cpp share GGUF-parser risk; Ollama also has its own Go loader
+CVE. Network exposure of `:11434` turns that into a remote attack.
+
+<Callout type="warn" title="Host `ollama` CLI is unrelated">
+  A host `ollama pull` often talks to a separately installed daemon. Trust boot ensure against
+  `OKE_AI_URL`.
+</Callout>
+
+## Required env
+
+| Variable                                     | Required?         | Meaning                                                            |
+| -------------------------------------------- | ----------------- | ------------------------------------------------------------------ |
+| `OKE_AI_URL`                                 | **Yes** in docker | Base URL — `oke boot: ollama driver needs OKE_AI_URL` when missing |
+| `OKE_AI_MODEL`                               | Recommended       | Model tag to pull/serve (default `qwen3.5:9b`)                     |
+| `OLLAMA_HOST`                                | Set by recipe     | `0.0.0.0:11434` inside the container                               |
+| `OKE_AI_VISION_MODEL` / `OKE_AI_EMBED_MODEL` | Optional          | Written by `oke ai setup` for logical models                       |
+
+## Data and backup
+
+| Volume    | Path            | What it stores                         |
+| --------- | --------------- | -------------------------------------- |
+| `ai-data` | `/root/.ollama` | Pulled model weights + Ollama metadata |
+
+## Production note
+
+Local Ollama is for docker/dev (and air-gapped prod you deliberately choose).
+For multi-user GPU self-hosting see [vLLM](/docs/recipes/vllm) /
+[SGLang](/docs/recipes/sglang). Cloud drivers stay separate.
+
+PII egress rules treat `ollama` as local — see [AI · PII](/docs/elements/ai).
+
+## What the recipe configures
+
+| Field          | Value                                          |
+| -------------- | ---------------------------------------------- |
+| Container port | `11434`                                        |
+| Host publish   | `127.0.0.1:11434:11434`                        |
+| Entrypoint     | Image default (`ollama serve`)                 |
+| Healthcheck    | `ollama list`, every 5s, 24 retries, 10s start |
+| Connection URL | `http://host:11434`                            |
+| Model pull     | Host-side `POST /api/pull` after healthy       |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="oke boot: ollama driver needs OKE_AI_URL">
+
+Docker mode expects `OKE_AI_URL` from `docker/.env.docker` when `images.ai` is pinned.
+Locally the default is `http://127.0.0.1:11434`. Prefer `oke ai setup` to wire everything
+in one pass.
+
+</Accordion>
+<Accordion title="Model missing / I already ran ollama pull on the host">
+
+The host CLI likely filled a **different** Ollama. Check `GET $OKE_AI_URL/api/tags`,
+then recreate with `oke dev -d`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [llama.cpp](/docs/recipes/llama-cpp) — default local AI
+- [AI](/docs/elements/ai) — `fx.ask`, prompts, evals
+- [CLI · oke ai setup](/docs/reference/cli) — non-interactive provider wiring
+
+## Next
+
+<Cards>
+  <Card title="llama.cpp" description="Default local AI." href="/docs/recipes/llama-cpp" />
+  <Card title="Meilisearch" description="Full-text index peer." href="/docs/recipes/meilisearch" />
+  <Card title="AI" description="Prompts, models, guardrails." href="/docs/elements/ai" />
+</Cards>

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>