okengine 0.9.0 → 0.10.0

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

@@ -0,0 +1,105 @@
+---
+title: "SGLang"
+description: "Production-tier self-hosted inference for structured and agent workloads on GPU."
+icon: "Cpu"
+source: "docs/spec/unified-theory.md"
+---
+
+SGLang is for **structured generation and agent-heavy workloads on real GPU
+hardware** when you self-host inference. Prefer a managed provider for most
+production apps. For general multi-user serving, prefer [vLLM](/docs/recipes/vllm).
+
+<Callout title="The one rule">
+  Pin an explicit runtime tag (never `latest`), publish only on loopback, and pick SGLang only when
+  structured / agent throughput is the reason you self-host.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin driver + image
+
+```typescript title="oke.config.ts"
+drivers: {
+  ai: { docker: "openai-compatible", prod: "openai-compatible", test: "mock" },
+},
+images: {
+  ai: "lmsysorg/sglang:v0.5.16-runtime", // never :latest
+},
+```
+
+Or `oke ai setup --provider sglang --yes`.
+
+</Step>
+
+<Step>
+### Env + GPU
+
+```bash title="docker/.env.docker"
+OKE_AI_URL=http://127.0.0.1:30000/v1
+OKE_AI_MODEL=Qwen/Qwen3-0.6B
+```
+
+Same NVIDIA reservation pattern as vLLM (`ipc: host` + device reservation).
+
+</Step>
+
+<Step>
+### Decision matrix
+
+| Workload                         | Recipe                                                                           |
+| -------------------------------- | -------------------------------------------------------------------------------- |
+| Single-user / dev                | [llama.cpp](/docs/recipes/llama-cpp) (default) or [Ollama](/docs/recipes/ollama) |
+| Multi-user GPU serving           | [vLLM](/docs/recipes/vllm)                                                       |
+| Structured / agent GPU workloads | **SGLang** (this recipe)                                                         |
+| Managed cloud                    | Anthropic / OpenAI / …                                                           |
+
+</Step>
+
+</Steps>
+
+## Security
+
+| Control      | Requirement                                    |
+| ------------ | ---------------------------------------------- |
+| Host publish | `127.0.0.1:30000:30000` only — never `0.0.0.0` |
+| Image pin    | Explicit version tag — never `latest`          |
+| Model source | Trusted Hugging Face repos / your own weights  |
+
+## What the recipe configures
+
+| Field          | Value                                                 |
+| -------------- | ----------------------------------------------------- |
+| Container port | `30000`                                               |
+| Host publish   | `127.0.0.1:30000:30000`                               |
+| `ipc`          | `host`                                                |
+| GPU            | `deploy.resources.reservations.devices` (nvidia, all) |
+| Healthcheck    | `GET /health`, long start period for model load       |
+| Connection URL | `http://host:30000/v1`                                |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="GPU not visible / container exits">
+
+Install the NVIDIA Container Toolkit. Without a GPU, use
+[llama.cpp](/docs/recipes/llama-cpp) for local smoke tests.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [vLLM](/docs/recipes/vllm) — general production GPU serving
+- [llama.cpp](/docs/recipes/llama-cpp) — default local AI
+- [AI](/docs/elements/ai) — drivers and `fx.ask`
+
+## Next
+
+<Cards>
+  <Card title="vLLM" description="General multi-user GPU serving." href="/docs/recipes/vllm" />
+  <Card title="llama.cpp" description="Default local AI." href="/docs/recipes/llama-cpp" />
+  <Card title="AI" description="Prompts and guardrails." href="/docs/elements/ai" />
+</Cards>

package/site/content/docs/recipes/supabase-docker.mdx

@@ -0,0 +1,145 @@
+---
+title: "Supabase"
+description: "Pin supabase/postgres as store.sql — extension bundle (pgvector, …) without Auth, Storage, Realtime, or Studio."
+icon: "Database"
+source: "docs/spec/unified-theory.md"
+---
+
+Supabase publishes `supabase/postgres` — plain Postgres with a bundled extension set
+(`pgvector`, `pg_graphql`, `pg_cron`, `wrappers`, and more). `oke docker` matches that
+image ahead of the generic Postgres recipe.
+
+<Callout title="Not the full Supabase platform">
+  This recipe does **not** start GoTrue, PostgREST, Kong, Realtime, Storage, or Studio. Auth, files,
+  and realtime delivery are already covered by [Vault](/docs/elements/vault), [Store ·
+  files](/docs/elements/store#files), and [Signal](/docs/elements/signal).
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the image
+
+```typescript title="oke.config.ts"
+images: {
+  "store.sql": "supabase/postgres:15.8.1.049", // pin a real tag from Supabase's registry
+},
+```
+
+</Step>
+
+<Step>
+### Same env shape as Postgres
+
+`oke docker` injects the same `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB`
+refs from `OKE_STORE_SQL_*`. Driver id stays `postgres`.
+
+</Step>
+
+<Step>
+### Use pgvector when you need it
+
+```typescript
+drivers: {
+  store: {
+    index: { local: "memory", docker: "pgvector", prod: "pgvector" },
+  },
+},
+```
+
+`CREATE EXTENSION IF NOT EXISTS vector` runs when the `pgvector` index driver opens —
+the extension ships in this image.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                 | Meaning                                   |
+| ------------------------ | ----------------------------------------- |
+| `OKE_STORE_SQL_USER`     | → `POSTGRES_USER`                         |
+| `OKE_STORE_SQL_PASSWORD` | → `POSTGRES_PASSWORD`                     |
+| `OKE_STORE_SQL_DB`       | → `POSTGRES_DB`                           |
+| `DATABASE_URL`           | App connection (`postgres://…:5432/…`)    |
+| `PGDATA`                 | Default `/var/lib/postgresql/data/pgdata` |
+
+Identical credential contract to [Postgres](/docs/recipes/postgres) — only the image
+(and its extension bundle) differs.
+
+## Data and backup
+
+| Path                                      | What lives there                           |
+| ----------------------------------------- | ------------------------------------------ |
+| `$PGDATA`                                 | Cluster data, including extension catalogs |
+| Image `VOLUME` `/var/lib/postgresql/data` | Persistence mount                          |
+
+Same backup story as plain Postgres: `pg_dump` or volume backup of
+`/var/lib/postgresql/data`. Losing that volume loses tables **and** which extensions
+were created.
+
+## Production note
+
+Want managed Supabase (Auth / Storage / Realtime included)? Use the
+[Supabase provider](/docs/providers/supabase) and set `DATABASE_URL` — do not run this
+image and the cloud project as if they were the same deployment.
+
+For self-hosted production, prefer a pinned tag (not `latest`) and the same
+shared-store guidance as [Postgres](/docs/recipes/postgres#production-note). Free-tier
+cloud pausing does not apply to this Docker image — you own uptime.
+
+## What the recipe configures
+
+| Field          | Value                                                |
+| -------------- | ---------------------------------------------------- |
+| Match          | `supabase/postgres` before generic `postgres`        |
+| 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='Extension "vector" is not available'>
+
+You pinned a plain `postgres:` image, not `supabase/postgres`, or the tag predates the
+bundle. Confirm the image reference contains `supabase/postgres`, then re-derive.
+With the right image, `CREATE EXTENSION vector` succeeds without a separate install.
+
+</Accordion>
+<Accordion title="Looking for Studio / the REST API">
+
+Those services are not part of this recipe. Use the
+[managed Supabase provider](/docs/providers/supabase) for the full platform, or oke's
+own Vault / Store · files / Signal for those concerns.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Supabase (provider)](/docs/providers/supabase) — managed cloud alternative
+- [Postgres](/docs/recipes/postgres) — generic recipe this one takes precedence over
+- [Store · Index](/docs/elements/store#index) — `pgvector`-backed vector search
+
+## Next
+
+<Cards>
+  <Card
+    title="Supabase"
+    description="Managed cloud, same wire protocol."
+    href="/docs/providers/supabase"
+  />
+  <Card
+    title="PgDog"
+    description="Add pooling in front of this recipe too."
+    href="/docs/recipes/pgdog"
+  />
+  <Card
+    title="Postgres"
+    description="The plain image this specializes."
+    href="/docs/recipes/postgres"
+  />
+</Cards>

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

@@ -0,0 +1,129 @@
+---
+title: "Timescale"
+description: "Self-hosted TimescaleDB — same POSTGRES_* contract as Postgres, hypertables included, driver stays postgres."
+icon: "Database"
+source: "docs/spec/unified-theory.md"
+---
+
+TimescaleDB is Postgres plus hypertables and time-series tooling. Pin a
+`timescale/timescaledb` image as `store.sql` and `oke docker` uses the Timescale
+recipe — same `POSTGRES_*` contract as plain Postgres. Driver id stays `postgres`.
+
+<Callout title="The one rule">
+  The driver id stays `postgres` — vendor choice lives in `images["store.sql"]`. Create the
+  `timescaledb` extension in SQL when you need hypertables; the image ships it.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the image
+
+```typescript title="oke.config.ts"
+images: {
+  "store.sql": "timescale/timescaledb:latest-pg17", // pin a real tag
+},
+```
+
+</Step>
+
+<Step>
+### Bring the stack up
+
+```bash
+oke dev --docker
+```
+
+Same credential contract as [Postgres](/docs/recipes/postgres):
+`POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` from `OKE_STORE_SQL_*`.
+
+</Step>
+
+<Step>
+### Enable the extension when you need it
+
+```sql
+CREATE EXTENSION IF NOT EXISTS timescaledb;
+```
+
+Then create hypertables with Timescale's usual DDL — Flows still talk through
+`fx.store` / Drizzle like any other Postgres.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                 | Who sets it            | Meaning                           |
+| ------------------------ | ---------------------- | --------------------------------- |
+| `OKE_STORE_SQL_USER`     | `oke docker` → compose | → `POSTGRES_USER`                 |
+| `OKE_STORE_SQL_PASSWORD` | `oke docker` → compose | → `POSTGRES_PASSWORD`             |
+| `OKE_STORE_SQL_DB`       | `oke docker` → compose | → `POSTGRES_DB`                   |
+| `DATABASE_URL`           | stack env for the app  | `postgres://…:5432/…`             |
+| `PGDATA`                 | stack default          | `/var/lib/postgresql/data/pgdata` |
+
+## Data and backup
+
+| Path                                      | What lives there                           |
+| ----------------------------------------- | ------------------------------------------ |
+| `$PGDATA`                                 | Cluster data, including Timescale catalogs |
+| Image `VOLUME` `/var/lib/postgresql/data` | Persistence mount                          |
+
+Same backup story as plain Postgres: `pg_dump` / volume backup of
+`/var/lib/postgresql/data`. Losing that volume loses tables and extension state.
+
+## Production note
+
+Pin a concrete tag (image + Postgres major). For multi-replica apps, keep one
+shared SQL backend — see
+[Postgres · Production note](/docs/recipes/postgres#production-note).
+
+Managed time-series hosts still use `DATABASE_URL` and
+`drivers.store.sql: "postgres"`.
+
+## What the recipe configures
+
+| Field          | Value                                   |
+| -------------- | --------------------------------------- |
+| Match          | `timescale` ahead of generic `postgres` |
+| Container port | `5432`                                  |
+| Healthcheck    | `pg_isready -U $POSTGRES_USER`          |
+| Connection URL | `postgres://user:pass@host:5432/db`     |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title='extension "timescaledb" is not available'>
+
+You pinned a plain `postgres:` image. Confirm the reference contains `timescale`,
+re-derive, then `CREATE EXTENSION timescaledb`.
+
+</Accordion>
+<Accordion title="oke boot: postgres driver needs DATABASE_URL">
+
+Same as Postgres — re-run `oke dev --docker` or export `DATABASE_URL` for a remote
+host.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Postgres](/docs/recipes/postgres) — generic recipe this specialises
+- [Store · SQL](/docs/elements/store#sql) — schema workflows
+- [Environment variables](/docs/reference/environment-variables) — `DATABASE_URL`
+
+## Next
+
+<Cards>
+  <Card title="Postgres" description="Plain Postgres recipe." href="/docs/recipes/postgres" />
+  <Card
+    title="Supabase"
+    description="Postgres + extension bundle."
+    href="/docs/recipes/supabase-docker"
+  />
+  <Card title="PgDog" description="Transaction pooling in front." href="/docs/recipes/pgdog" />
+</Cards>

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

@@ -0,0 +1,136 @@
+---
+title: "Traefik"
+description: "Docker-label auto-discovery proxy — OKE_PROXY_HOST, OKE_PROXY_ACME_EMAIL, socket-proxy, ACME volume."
+icon: "Lock"
+source: "docs/spec/unified-theory.md"
+---
+
+Traefik discovers `app` replicas from Docker labels instead of a static upstream, so
+`docker compose up --scale app=N` load-balances without reconfiguring the proxy.
+
+<Callout title="The one rule">
+  Traefik never mounts the raw Docker socket. A filtered `tecnativa/docker-socket-proxy` companion
+  exposes only containers / events / ping / version / networks on the internal compose network.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the proxy
+
+```typescript title="oke.config.ts"
+images: {
+  proxy: "traefik:v3.3",
+},
+```
+
+</Step>
+
+<Step>
+### Hostname + ACME email
+
+```bash title="docker/.env.docker"
+OKE_PROXY_HOST=app.example.com
+OKE_PROXY_ACME_EMAIL=admin@example.com
+```
+
+`OKE_PROXY_ACME_EMAIL` defaults to `admin@example.com` if unset — set a real mailbox
+before production ACME.
+
+</Step>
+
+<Step>
+### Scale the app
+
+```bash
+docker compose … up -d --scale app=3
+```
+
+App labels: `traefik.http.routers.app.rule=Host(...)`, TLS cert resolver `letsencrypt`,
+load-balancer port `6530`.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                | Required?            | Meaning                                        |
+| ----------------------- | -------------------- | ---------------------------------------------- |
+| `OKE_PROXY_HOST`        | **Yes** (production) | Host rule + ACME identity; default `localhost` |
+| `OKE_PROXY_ACME_EMAIL`  | **Yes** (production) | Let's Encrypt account email                    |
+| `allowedHosts` (config) | Production           | Must include the public hostname               |
+
+## Data and backup
+
+| Volume              | Path                      | What it stores                                    |
+| ------------------- | ------------------------- | ------------------------------------------------- |
+| `proxy-letsencrypt` | `/letsencrypt`            | `acme.json` — certificates + ACME account         |
+| Socket proxy only   | `/var/run/docker.sock:ro` | **Only** the `socket-proxy` companion mounts this |
+
+**Backup means:** preserve the `proxy-letsencrypt` volume (especially `acme.json`). Losing
+it forces re-issuance and can hit Let's Encrypt rate limits. The socket-proxy has no
+durable state.
+
+## Production note
+
+Security posture is intentional: Traefik talks to `tcp://socket-proxy:2375` with a
+filtered API (`CONTAINERS`, `EVENTS`, `PING`, `VERSION`, `NETWORKS` only). Never mount
+raw `docker.sock` on Traefik — see [Reverse proxy](/docs/deployment/reverse-proxy).
+
+HTTP entrypoint redirects to `websecure`. For a single instance with no scale plans,
+[Caddy](/docs/recipes/caddy) is simpler (no labels, no companion).
+
+## What the recipe configures
+
+| Field       | Value                                              |
+| ----------- | -------------------------------------------------- |
+| Ports       | `80` + `443`                                       |
+| Providers   | Docker via socket-proxy, `exposedbydefault=false`  |
+| Companion   | `tecnativa/docker-socket-proxy:v0.5.0`             |
+| Healthcheck | `traefik healthcheck --ping`, every 10s, 5 retries |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="404 / no backend — Traefik cannot see app">
+
+Usually `socket-proxy` is down, or `app` lacks Traefik labels. Confirm
+`depends_on: socket-proxy` and that `compose.proxy.yml` merged the app labels.
+
+Logs showing Docker provider connection errors point at the socket-proxy, not Traefik
+config syntax.
+
+</Accordion>
+<Accordion title="ACME email rejected / rate limited">
+
+Replace the default `admin@example.com` with a real `OKE_PROXY_ACME_EMAIL`. If you wiped
+`proxy-letsencrypt`, you may be rate-limited — restore `acme.json` from backup instead of
+re-issuing repeatedly.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Reverse proxy](/docs/deployment/reverse-proxy) — Docker-socket-proxy security rationale
+- [Docker · Reverse proxy](/docs/deployment/docker#reverse-proxy) — compose layer order
+- [Security](/docs/reference/security) — `allowedHosts`
+
+## Next
+
+<Cards>
+  <Card title="Caddy" description="Single-instance alternative." href="/docs/recipes/caddy" />
+  <Card
+    title="PgDog"
+    description="Pool Postgres behind the same stack."
+    href="/docs/recipes/pgdog"
+  />
+  <Card
+    title="Redis Cloud"
+    description="A managed backing store."
+    href="/docs/providers/redis-cloud"
+  />
+</Cards>

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

@@ -0,0 +1,121 @@
+---
+title: "Valkey"
+description: "BSD-licensed Redis-wire fork — same redis driver, OKE_STORE_KV_PASSWORD, valkey-server command."
+icon: "Zap"
+source: "docs/spec/unified-theory.md"
+---
+
+Valkey is the Linux Foundation's BSD-3-Clause fork of Redis, forked after Redis's 2024
+license change. Same wire protocol — pin the image and nothing in Flow code moves.
+
+<Callout title="The one rule">
+  Driver id stays `redis`. Valkey is an image choice, not a driver. `REDIS_URL` and every KV call
+  through `fx.store` work exactly as they do against Redis.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the image
+
+```typescript title="oke.config.ts"
+images: {
+  "store.kv": "valkey/valkey:8-alpine",
+},
+```
+
+</Step>
+
+<Step>
+### Same password contract as Redis
+
+```bash
+OKE_STORE_KV_PASSWORD=…
+REDIS_URL=redis://:…@127.0.0.1:6379
+```
+
+Command becomes `valkey-server --requirepass "$OKE_STORE_KV_PASSWORD" …` — healthcheck
+uses `valkey-cli`.
+
+</Step>
+
+<Step>
+### Optional memory caps
+
+Same knobs as Redis: `OKE_STORE_KV_MAXMEMORY`, `OKE_STORE_KV_MAXMEMORY_POLICY`.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                        | Required?     | Meaning                                             |
+| ------------------------------- | ------------- | --------------------------------------------------- |
+| `OKE_STORE_KV_PASSWORD`         | **Yes**       | `--requirepass` for `valkey-server`                 |
+| `REDIS_URL`                     | **Yes** (app) | Still `redis://` scheme — protocol name, not vendor |
+| `OKE_STORE_KV_MAXMEMORY`        | Optional      | Memory cap                                          |
+| `OKE_STORE_KV_MAXMEMORY_POLICY` | Optional      | Eviction policy                                     |
+
+## Data and backup
+
+No named volume in the recipe — same ephemeral default as [Redis](/docs/recipes/redis).
+**Backup means:** do not assume durability until you add a volume + persistence config;
+treat the default as a shared cache rebuilt from durable stores.
+
+## Production note
+
+Choose Valkey when RSAL/SSPL managed-service terms on Redis ≥8 matter to your legal
+posture — BSD-3-Clause carries no such restriction. Feature parity with Redis 7/8 stays
+close since the fork tracks upstream.
+
+DigitalOcean's managed product moved onto Valkey after Aiven stepped back from Redis —
+see [DigitalOcean Managed Caching](/docs/providers/digitalocean-caching).
+
+## What the recipe configures
+
+| Field          | Value                                                              |
+| -------------- | ------------------------------------------------------------------ |
+| Container port | `6379`                                                             |
+| Command        | `valkey-server --requirepass … --maxmemory … --maxmemory-policy …` |
+| Healthcheck    | `valkey-cli -a <password> ping`, every 5s, 10 retries              |
+| Connection URL | `redis://:pass@host:6379`                                          |
+| License        | BSD-3-Clause                                                       |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="oke boot: redis driver needs REDIS_URL">
+
+Same loud failure as Redis — the driver id is still `redis`. Export `REDIS_URL` or let
+`oke dev --docker` write it.
+
+</Accordion>
+<Accordion title="Healthcheck uses redis-cli and fails">
+
+You still have the Redis recipe matched (image ref contains `redis`). Valkey images must
+match `/valkey/i` so the healthcheck binary is `valkey-cli`. Pin `valkey/valkey:…`
+explicitly.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Store · KV](/docs/elements/store#kv) — full Redis-protocol image license table
+- [Redis](/docs/recipes/redis) · [Dragonfly](/docs/recipes/dragonfly) — the other two peers
+- [DigitalOcean Managed Caching](/docs/providers/digitalocean-caching) — managed Valkey
+
+## Next
+
+<Cards>
+  <Card
+    title="Dragonfly"
+    description="Multi-threaded Redis-wire peer."
+    href="/docs/recipes/dragonfly"
+  />
+  <Card title="Redis" description="The mature default." href="/docs/recipes/redis" />
+  <Card title="Upstash" description="Managed alternative." href="/docs/providers/upstash" />
+</Cards>