okengine 0.9.1 → 0.10.1

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

@@ -0,0 +1,125 @@
+---
+title: "Dragonfly"
+description: "Multi-threaded Redis-wire runtime — OKE_STORE_KV_PASSWORD, memlock ulimit, no maxmemory-policy flag."
+icon: "Zap"
+source: "docs/spec/unified-theory.md"
+---
+
+Dragonfly is a multi-threaded, memory-efficient reimplementation of the Redis protocol —
+same `redis://` wire format, different engine. Slots behind the same `redis` driver with
+zero Flow changes.
+
+<Callout title="The one rule">
+  Driver id stays `redis`. Dragonfly is an image choice — every KV call through `fx.store` behaves
+  identically to Redis or Valkey at the protocol layer.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the image
+
+```typescript title="oke.config.ts"
+images: {
+  "store.kv": "docker.dragonflydb.io/dragonflydb/dragonfly",
+},
+```
+
+</Step>
+
+<Step>
+### Password + memory
+
+```bash
+OKE_STORE_KV_PASSWORD=…
+OKE_STORE_KV_MAXMEMORY=256mb   # optional; recipe passes --maxmemory
+REDIS_URL=redis://:…@127.0.0.1:6379
+```
+
+Command: `dragonfly --requirepass "$OKE_STORE_KV_PASSWORD" --maxmemory "…"`.
+
+Unlike Redis/Valkey, this recipe does **not** pass `--maxmemory-policy` — Dragonfly's
+own defaults apply.
+
+</Step>
+
+<Step>
+### memlock ulimit
+
+The recipe sets `ulimits.memlock: -1` — required for Dragonfly's shared-nothing design.
+If the host forbids unlimited memlock, the container may fail to start.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                 | Required?     | Meaning                                             |
+| ------------------------ | ------------- | --------------------------------------------------- |
+| `OKE_STORE_KV_PASSWORD`  | **Yes**       | `--requirepass`                                     |
+| `REDIS_URL`              | **Yes** (app) | `redis://` URL for the driver                       |
+| `OKE_STORE_KV_MAXMEMORY` | Optional      | `--maxmemory` (default `0` in the command template) |
+| `HEALTHCHECK_PORT`       | Set by recipe | `6379` — used by the image's healthcheck script     |
+
+## Data and backup
+
+No named volume — ephemeral by default, same as Redis/Valkey. **Backup means:** do not
+treat this container as durable storage until you add a volume and Dragonfly persistence
+settings; rebuild from SQL/files, or use [Dragonfly Cloud](/docs/providers/dragonfly-cloud).
+
+## Production note
+
+BSL 1.1 — converts to Apache 2.0 on a published change date per release. Free for
+self-hosting; the BSL terms restrict offering Dragonfly itself as a commercial managed
+service to third parties — running it for your own app is unaffected.
+
+Multi-threaded architecture makes better use of multi-core hosts than single-threaded
+Redis under heavy concurrent load. For a managed endpoint with TLS + passkey, see
+[Dragonfly Cloud](/docs/providers/dragonfly-cloud).
+
+## What the recipe configures
+
+| Field          | Value                                                 |
+| -------------- | ----------------------------------------------------- |
+| Container port | `6379`                                                |
+| `ulimits`      | `memlock: -1`                                         |
+| Healthcheck    | `/usr/local/bin/healthcheck.sh`, every 5s, 10 retries |
+| Connection URL | `redis://:pass@host:6379`                             |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Container exits — cannot lock memory / memlock">
+
+Host `ulimit -l` is too low. The recipe requests unlimited memlock. Raise the Docker
+daemon / systemd limit, or run on a host that allows `memlock: -1`.
+
+</Accordion>
+<Accordion title="oke boot: redis driver needs REDIS_URL">
+
+Same driver failure as Redis — export `REDIS_URL` or let docker mode write it. Wrong
+password yields Redis-protocol `NOAUTH` / `WRONGPASS` from the server.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Store · KV](/docs/elements/store#kv) — full Redis-protocol image license table
+- [Dragonfly Cloud](/docs/providers/dragonfly-cloud) — the managed equivalent
+- [Redis](/docs/recipes/redis) · [Valkey](/docs/recipes/valkey) — the other two peers
+
+## Next
+
+<Cards>
+  <Card
+    title="Dragonfly Cloud"
+    description="Managed Dragonfly."
+    href="/docs/providers/dragonfly-cloud"
+  />
+  <Card title="Valkey" description="Permissive-licensed peer." href="/docs/recipes/valkey" />
+  <Card title="PgDog" description="Pooling for the SQL side." href="/docs/recipes/pgdog" />
+</Cards>

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

@@ -0,0 +1,146 @@
+---
+title: "Recipes"
+description: "Docker recipes already shipped in oke docker — SQL (including Cockroach, Yugabyte, Timescale), KV, proxy, and services."
+icon: "Container"
+source: "docs/spec/unified-theory.md"
+---
+
+Every recipe below is already wired into `oke docker` — pin an image in `oke.config.ts`
+and get env, healthcheck, and a connection URL for free.
+
+<Callout title="The one rule">
+  Vendor choice lives in `images[…]` — never in `drivers.*`, which only ever say protocol ids
+  (`postgres`, `redis`, `s3`, `smtp`, `openbao`, `meilisearch`, `openai-compatible`, `ollama`, …).
+</Callout>
+
+## SQL
+
+<Cards>
+  <Card
+    title="Postgres"
+    description="Default store.sql — POSTGRES_*, PGDATA, DATABASE_URL."
+    href="/docs/recipes/postgres"
+  />
+  <Card
+    title="Supabase"
+    description="supabase/postgres extension bundle only."
+    href="/docs/recipes/supabase-docker"
+  />
+  <Card
+    title="CockroachDB"
+    description="Self-hosted single-node — port 26257, COCKROACH_*."
+    href="/docs/recipes/cockroachdb"
+  />
+  <Card
+    title="YugabyteDB"
+    description="Self-hosted YSQL — port 5433, YSQL_*."
+    href="/docs/recipes/yugabytedb"
+  />
+  <Card
+    title="Timescale"
+    description="Postgres + hypertables — same POSTGRES_* contract."
+    href="/docs/recipes/timescale"
+  />
+</Cards>
+
+## KV
+
+Driver id stays `redis` for every image below.
+
+<Cards>
+  <Card
+    title="Redis"
+    description="Default store.kv — requirepass + maxmemory."
+    href="/docs/recipes/redis"
+  />
+  <Card title="Valkey" description="BSD-licensed Redis-wire fork." href="/docs/recipes/valkey" />
+  <Card
+    title="Dragonfly"
+    description="Multi-threaded Redis-wire runtime."
+    href="/docs/recipes/dragonfly"
+  />
+</Cards>
+
+## Proxy
+
+Opt-in via `images.proxy` — leave unset until you need HTTPS or `--scale app=N`.
+
+<Cards>
+  <Card title="Caddy" description="Automatic-HTTPS, single instance." href="/docs/recipes/caddy" />
+  <Card
+    title="Traefik"
+    description="Docker-label discovery + socket-proxy."
+    href="/docs/recipes/traefik"
+  />
+</Cards>
+
+## Services
+
+<Cards>
+  <Card title="PgDog" description="Transaction pooler on :6432." href="/docs/recipes/pgdog" />
+  <Card
+    title="RustFS"
+    description="S3-compatible store.files — /data volume."
+    href="/docs/recipes/rustfs"
+  />
+  <Card title="Mailpit" description="SMTP catcher — UI on :8025." href="/docs/recipes/mailpit" />
+  <Card title="OpenBao" description="Raft vault — unseal key SPOF." href="/docs/recipes/openbao" />
+  <Card
+    title="Meilisearch"
+    description="Full-text store.index on :7700."
+    href="/docs/recipes/meilisearch"
+  />
+</Cards>
+
+## AI (local / self-hosted)
+
+Default local pin is **llama.cpp**. Ollama stays fully supported. vLLM / SGLang
+are production-tier self-host options — most apps still use a managed provider.
+
+| Workload                         | Recipe                                         |
+| -------------------------------- | ---------------------------------------------- |
+| Single-user / dev (lightest)     | [llama.cpp](/docs/recipes/llama-cpp) (default) |
+| Local library UX                 | [Ollama](/docs/recipes/ollama)                 |
+| Multi-user GPU concurrency       | [vLLM](/docs/recipes/vllm)                     |
+| Structured / agent GPU workloads | [SGLang](/docs/recipes/sglang)                 |
+| Managed cloud                    | Anthropic / OpenAI / … (no `images.ai`)        |
+
+All four recipes **loopback-publish only** and pin explicit tags (never
+`latest`). Load models from curated registries — never arbitrary untrusted GGUF.
+
+<Cards>
+  <Card
+    title="llama.cpp"
+    description="Default local AI — OpenAI /v1, lightest footprint."
+    href="/docs/recipes/llama-cpp"
+  />
+  <Card
+    title="Ollama"
+    description="Fully supported alternative — library pull UX."
+    href="/docs/recipes/ollama"
+  />
+  <Card title="vLLM" description="Self-hosted multi-user GPU serving." href="/docs/recipes/vllm" />
+  <Card
+    title="SGLang"
+    description="Self-hosted structured / agent GPU serving."
+    href="/docs/recipes/sglang"
+  />
+</Cards>
+
+## Learn more
+
+- [Providers](/docs/providers) — managed cloud alternatives
+- [Docker](/docs/deployment/docker) — compose derivation, PgDog, reverse proxy
+- [Store](/docs/elements/store) — `sql` / `kv` / `files` / `index` facets
+
+## Next
+
+<Cards>
+  <Card
+    title="Postgres"
+    description="Start with the default SQL recipe."
+    href="/docs/recipes/postgres"
+  />
+  <Card title="Providers" description="Managed cloud alternatives." href="/docs/providers" />
+  <Card title="Deployment" description="Compose, Swarm, or Kubernetes." href="/docs/deployment" />
+</Cards>

package/site/content/docs/recipes/llama-cpp.mdx

@@ -0,0 +1,153 @@
+---
+title: "llama.cpp"
+description: "Default local AI image — OpenAI-compatible llama-server, loopback-only publish, pinned build ≥ b8146."
+icon: "Bot"
+source: "docs/spec/unified-theory.md"
+---
+
+llama.cpp is the default `images.ai` pin for local inference. It runs
+`llama-server` with an OpenAI-compatible `/v1` API — lightest resource footprint
+for single-user / dev. Driver id stays `openai-compatible`.
+
+<Callout title="The one rule">
+  Pin a verified build ≥ `b8146`, publish only on loopback, and load models only from curated
+  registries (Docker Hub `ai/`) — never arbitrary untrusted GGUF.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin driver + image
+
+```typescript title="oke.config.ts"
+drivers: {
+  ai: { local: "openai-compatible", docker: "openai-compatible", test: "mock" },
+},
+images: {
+  ai: "ghcr.io/ggml-org/llama.cpp:server-b10290", // never :latest
+},
+```
+
+Or `oke ai setup --provider llama-cpp` (TTY: banner → Ultra Fast / Fast /
+Balanced / Smart → up to 20 curated Docker Hub `ai/` picks per tier) / `--yes`
+for `smollm2`.
+
+</Step>
+
+<Step>
+### Env written by the stack
+
+```bash title="docker/.env.docker"
+OKE_AI_URL=http://127.0.0.1:8080/v1
+OKE_AI_MODEL=smollm2
+```
+
+`OKE_AI_MODEL` is a Docker Hub `ai/<id>` model. The recipe writes
+`docker/llama-entrypoint.py`, which Hub-pulls into the cache volume (native
+`llama download -dr`, then a CNCF `model.weight` fallback for newer tags like
+gemma4), then starts `llama-server -m <gguf> --alias <id>` (single-model — not
+router `--models-preset` / bare `--docker-repo`, which hang on b10290+). Never
+set `LLAMA_ARG_MODELS_PRESET` / `LLAMA_ARG_DOCKER_REPO` in the container env.
+
+`oke dev -d` shows the model id in the hero / Docker summary and polls
+`/v1/models` in the background until status is `ready` (first boot may take
+minutes while the Hub image downloads).
+
+</Step>
+
+<Step>
+### Ask through the OpenAI-compatible driver
+
+```typescript
+import { ai } from "okengine";
+
+export const smart = ai.model("smart", {
+  provider: "openai-compatible",
+  model: process.env.OKE_AI_MODEL ?? "smollm2",
+});
+```
+
+</Step>
+
+</Steps>
+
+## Security (hard requirements)
+
+| Control              | Requirement                                                                  |
+| -------------------- | ---------------------------------------------------------------------------- |
+| Host publish         | `127.0.0.1:8080:8080` only — never `0.0.0.0`                                 |
+| Image pin            | Explicit build ≥ **b8146** (CVE-2026-27940 / CVE-2026-33298); never `latest` |
+| Model source         | Docker Hub [`ai/`](https://hub.docker.com/u/ai) namespace (or known HF GGUF) |
+| Untrusted GGUF       | **Forbidden** — crafted files can RCE the parser on unpatched builds         |
+| RPC / extra backends | Not published — OpenAI HTTP only                                             |
+
+Inside the container the server listens on `0.0.0.0` so the Compose network and
+loopback map work. The **host** bind is loopback — same isolation idea as
+Postgres/Redis, stricter on the published interface because of GGUF CVE risk.
+
+## Required env
+
+| Variable       | Required?         | Meaning                                 |
+| -------------- | ----------------- | --------------------------------------- |
+| `OKE_AI_URL`   | **Yes** in docker | Base URL including `/v1`                |
+| `OKE_AI_MODEL` | Recommended       | Docker Hub `ai/` id (default `smollm2`) |
+
+## What the recipe configures
+
+| Field          | Value                                                           |
+| -------------- | --------------------------------------------------------------- |
+| Container port | `8080`                                                          |
+| Host publish   | `127.0.0.1:8080:8080`                                           |
+| Healthcheck    | `GET /health`, every 5s, 24 retries, 900s start                 |
+| Connection URL | `http://host:8080/v1`                                           |
+| Model load     | `llama-entrypoint.py` → Hub pull (incl. CNCF weights) then `-m` |
+
+## When to choose something else
+
+| Workload                                   | Prefer                                  |
+| ------------------------------------------ | --------------------------------------- |
+| Single-user / dev, lightest footprint      | **llama.cpp** (this recipe)             |
+| Local DX with library pull UX              | [Ollama](/docs/recipes/ollama)          |
+| Multi-user / production concurrency on GPU | [vLLM](/docs/recipes/vllm)              |
+| Structured / agent workloads on GPU        | [SGLang](/docs/recipes/sglang)          |
+| Managed cloud                              | Anthropic / OpenAI / … (no `images.ai`) |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Connection refused on :8080">
+
+Confirm compose published `127.0.0.1:8080:8080` (not bare `8080:8080` on all
+interfaces). `OKE_AI_URL` must include `/v1`.
+
+</Accordion>
+<Accordion title="Model fails to load / slow first boot">
+
+First start Hub-pulls the curated `ai/` model into the named cache volume
+(see logs: `oke ai: ensuring…` / download %). Prefer `oke ai setup` tiers
+(Ultra Fast → `smollm2`) for smoke tests. Confirm `OKE_AI_MODEL` is active in
+`.env.local` / `docker/.env.docker`. Watch `oke dev` (`AI … — waiting…` →
+`ready`). If status stays `loading` forever on an old stack that still uses
+`--models-preset`, regenerate `docker/` and recreate AI. Newer Hub tags use
+CNCF weight layers — the entrypoint falls back when native `llama download`
+cannot find `vnd.docker.ai.gguf.v3`. Do not mount random GGUF files. Never put
+`LLAMA_ARG_MODELS_PRESET` / `LLAMA_ARG_DOCKER_REPO` in the container env.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [AI](/docs/elements/ai) — `fx.ask`, prompts, drivers
+- [Ollama](/docs/recipes/ollama) — fully supported alternative
+- [Environment variables](/docs/reference/environment-variables) — `OKE_AI_*`
+
+## Next
+
+<Cards>
+  <Card title="Ollama" description="Library UX alternative." href="/docs/recipes/ollama" />
+  <Card title="vLLM" description="Production GPU serving." href="/docs/recipes/vllm" />
+  <Card title="AI" description="Prompts, models, guardrails." href="/docs/elements/ai" />
+</Cards>

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

@@ -0,0 +1,136 @@
+---
+title: "Mailpit"
+description: "Local SMTP catcher for channel.email — SMTP_URL on :1025, UI on :8025, MAILPIT_UI_URL."
+icon: "Mail"
+source: "docs/spec/unified-theory.md"
+---
+
+Mailpit is the docker-mode email catcher — every message the `smtp` channel driver sends
+lands in a web UI instead of a real inbox. Pin it as `images["channel.email"]` when
+`drivers.channel.email.docker` is `smtp`.
+
+<Callout title="The one rule">
+  Docker ≈ prod for the **SMTP protocol** — same `SMTP_URL` shape. Mailpit is not a production MTA;
+  swap the image / URL for a real relay when you leave local docker.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the image (templates already do)
+
+```typescript title="oke.config.ts"
+drivers: {
+  channel: {
+    email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
+  },
+},
+images: {
+  "channel.email": "axllent/mailpit:v1.22.3",
+},
+```
+
+</Step>
+
+<Step>
+### Connect the smtp driver
+
+```bash title="docker/.env.docker (written by oke docker)"
+SMTP_URL=smtp://127.0.0.1:1025
+MAILPIT_UI_URL=http://127.0.0.1:8025
+```
+
+No `SMTP_USER` / `SMTP_PASSWORD` required for Mailpit's open local listener.
+
+</Step>
+
+<Step>
+### Send and inspect
+
+Trigger any flow that uses `fx.email` / channel email. Open `MAILPIT_UI_URL` (port
+**8025**) to read the caught message — subject, body, headers.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                      | Required?                  | Meaning                                                 |
+| ----------------------------- | -------------------------- | ------------------------------------------------------- |
+| `SMTP_URL`                    | **Yes** (app, smtp driver) | `smtp://host:1025` — boot fails without it              |
+| `OKE_CHANNEL_EMAIL_URL`       | Alternative                | Same role as `SMTP_URL`                                 |
+| `MAILPIT_UI_URL`              | Written by stack           | Browser UI — not read by the smtp driver                |
+| `SMTP_USER` / `SMTP_PASSWORD` | No for Mailpit             | Used when pointing `SMTP_URL` at an authenticated relay |
+
+## Data and backup
+
+Mailpit declares **no volume**. Caught messages live in container memory/disk for that
+instance only.
+
+**Backup means:** nothing durable to back up — this is a catcher. For forensic copies,
+export from the UI before recreate. Production mail never uses this image as the store of
+record.
+
+## Production note
+
+Templates set `prod: "smtp"` but still pin Mailpit in `images` for docker. In real prod,
+point `SMTP_URL` at your provider and set `SMTP_USER` / `SMTP_PASSWORD` as needed.
+
+Leaving Mailpit reachable on a public host exposes an open relay UI — bind to the compose
+network only.
+
+Healthcheck probes `http://127.0.0.1:8025/api/v1/info` — UI down ⇒ service unhealthy even
+if SMTP still accepts mail.
+
+## What the recipe configures
+
+| Field          | Value                                               |
+| -------------- | --------------------------------------------------- |
+| SMTP port      | `1025` (published)                                  |
+| Extra port     | `8025` → UI                                         |
+| Healthcheck    | `wget` against `/api/v1/info`, every 5s, 10 retries |
+| Connection URL | `smtp://host:1025`                                  |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="oke boot: smtp driver needs SMTP_URL">
+
+The smtp binder refuses to start without `SMTP_URL` (or `OKE_CHANNEL_EMAIL_URL`). In
+docker mode the error asks whether `oke dev -d` wrote `docker/.env.docker`. Also rejects
+non-`smtp://` schemes: `oke boot: SMTP_URL must use smtp://`.
+
+</Accordion>
+<Accordion title="Messages send but UI is empty">
+
+Wrong UI port, or you opened a different instance's Mailpit. Confirm `MAILPIT_UI_URL`
+matches the published `8025` mapping for **this** compose project (instance-id offsets
+shift the host port).
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Channel](/docs/elements/channel) — email delivery physics
+- [Environment variables](/docs/reference/environment-variables) — `SMTP_*` map
+- [Configuration](/docs/reference/configuration) — default `channel.email` image pin
+
+## Next
+
+<Cards>
+  <Card
+    title="RustFS"
+    description="S3-compatible files for the same stack."
+    href="/docs/recipes/rustfs"
+  />
+  <Card
+    title="OpenBao"
+    description="Vault recipe for docker/prod secrets."
+    href="/docs/recipes/openbao"
+  />
+  <Card title="Channel" description="How fx.email reaches humans." href="/docs/elements/channel" />
+</Cards>