okengine 0.9.1 → 0.10.0

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>

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

@@ -0,0 +1,106 @@
+---
+title: "vLLM"
+description: "Production-tier self-hosted inference — OpenAI-compatible GPU serving when you run inference yourself."
+icon: "Cpu"
+source: "docs/spec/unified-theory.md"
+---
+
+vLLM is for **multi-user / production concurrency on real GPU hardware** when
+you choose to self-host inference instead of a managed provider. Driver id stays
+`openai-compatible`. Most apps should prefer Anthropic / OpenAI / … in prod.
+
+<Callout title="The one rule">
+  Pin an explicit image tag (never `latest`), publish only on loopback, and treat this as “I run
+  production inference myself” — not the default create path.
+</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: "vllm/vllm-openai:v0.26.0", // never :latest
+},
+```
+
+Or `oke ai setup --provider vllm --yes`.
+
+</Step>
+
+<Step>
+### Env + GPU
+
+```bash title="docker/.env.docker"
+OKE_AI_URL=http://127.0.0.1:8000/v1
+OKE_AI_MODEL=Qwen/Qwen3-0.6B
+```
+
+The recipe sets `ipc: host` and an NVIDIA device reservation. Host needs the
+NVIDIA Container Toolkit.
+
+</Step>
+
+<Step>
+### Decide deliberately
+
+| Path                                 | When                                         |
+| ------------------------------------ | -------------------------------------------- |
+| Managed provider                     | Default for most production apps             |
+| **vLLM** (this recipe)               | Self-hosted multi-user GPU serving           |
+| [SGLang](/docs/recipes/sglang)       | Self-hosted structured / agent GPU workloads |
+| [llama.cpp](/docs/recipes/llama-cpp) | Single-user / dev (default local)            |
+
+</Step>
+
+</Steps>
+
+## Security
+
+| Control      | Requirement                                   |
+| ------------ | --------------------------------------------- |
+| Host publish | `127.0.0.1:8000:8000` 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 | `8000`                                                |
+| Host publish   | `127.0.0.1:8000:8000`                                 |
+| `ipc`          | `host`                                                |
+| GPU            | `deploy.resources.reservations.devices` (nvidia, all) |
+| Healthcheck    | `GET /health`, long start period for model load       |
+| Connection URL | `http://host:8000/v1`                                 |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="GPU not visible / container exits">
+
+Install the NVIDIA Container Toolkit on the host. CPU-only hosts should use
+[llama.cpp](/docs/recipes/llama-cpp) or [Ollama](/docs/recipes/ollama) instead.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [llama.cpp](/docs/recipes/llama-cpp) — default local AI
+- [SGLang](/docs/recipes/sglang) — structured / agent GPU path
+- [AI](/docs/elements/ai) — drivers and `fx.ask`
+
+## Next
+
+<Cards>
+  <Card title="SGLang" description="Agent / structured GPU serving." href="/docs/recipes/sglang" />
+  <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/yugabytedb.mdx

@@ -0,0 +1,135 @@
+---
+title: "YugabyteDB"
+description: "Self-hosted single-node YSQL — YSQL_* env, port 5433, driver stays postgres."
+icon: "Database"
+source: "docs/spec/unified-theory.md"
+---
+
+YugabyteDB's **YSQL** API speaks Postgres wire. Pin `yugabytedb/yugabyte` as
+`store.sql` and `oke docker` derives a single-node `yugabyted` service —
+credentials, healthcheck, and `DATABASE_URL`. Driver id stays `postgres`.
+
+<Callout title="The one rule">
+  Use the YSQL API only — never treat YCQL as `store.sql`. Vendor choice lives in
+  `images["store.sql"]`; host maps `:5432` → container `:5433`.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the image
+
+```typescript title="oke.config.ts"
+images: {
+  "store.sql": "yugabytedb/yugabyte:2025.1.0.0-b100", // pin a real tag
+},
+```
+
+</Step>
+
+<Step>
+### Bring the stack up
+
+```bash
+oke dev --docker
+```
+
+`oke docker` injects `YSQL_USER` / `YSQL_PASSWORD` / `YSQL_DB` from `OKE_STORE_SQL_*`
+(password presence turns authentication on), runs
+`bin/yugabyted start --background=false`, and publishes YSQL on host `:5432`.
+
+</Step>
+
+<Step>
+### Connect
+
+```bash
+echo "$DATABASE_URL"
+# postgres://oke:…@127.0.0.1:5432/oke
+```
+
+First healthy state is slower than plain Postgres — the healthcheck allows a long
+start period.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                 | Who sets it            | Meaning                          |
+| ------------------------ | ---------------------- | -------------------------------- |
+| `OKE_STORE_SQL_USER`     | `oke docker` → compose | → `YSQL_USER`                    |
+| `OKE_STORE_SQL_PASSWORD` | `oke docker` → compose | → `YSQL_PASSWORD` (enables auth) |
+| `OKE_STORE_SQL_DB`       | `oke docker` → compose | → `YSQL_DB`                      |
+| `DATABASE_URL`           | stack env for the app  | Host `:5432` → container `:5433` |
+
+## Data and backup
+
+| Path                     | What lives there                                     |
+| ------------------------ | ---------------------------------------------------- |
+| `/home/yugabyte/yb_data` | Named volume `store-sql-data` — `yugabyted` base dir |
+
+**Backup means:** volume backup of `store-sql-data`, or Yugabyte's backup tooling.
+Losing that volume loses the universe data.
+
+## Production note
+
+Single-node `yugabyted` is for local and small self-hosted use. For managed Aeon
+clusters, use the [YugabyteDB provider](/docs/providers/yugabytedb). Pin a concrete
+tag; the image is large and cold-start is slower than Postgres.
+
+## What the recipe configures
+
+| Field          | Value                                                 |
+| -------------- | ----------------------------------------------------- |
+| Container port | `5433` (host publishes `5432`)                        |
+| Command        | `bin/yugabyted start --base_dir=… --background=false` |
+| Healthcheck    | `ysqlsh … SELECT 1` (90s `start_period`)              |
+| Connection URL | `postgres://user:pass@host:5432/db`                   |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="store-sql unhealthy for a long time">
+
+Yugabyte cold-start is slow. Wait through the healthcheck `start_period`, then read
+`docker compose … logs store-sql`.
+
+macOS AirPlay on `:7000` can conflict with Yugabyte's master UI — stop AirPlay
+Receiver or remap that port in `compose.override.yml` if you need the UI.
+
+</Accordion>
+<Accordion title="password authentication failed">
+
+`YSQL_PASSWORD` must match `DATABASE_URL`. Regenerate `docker/.env.docker` with
+`oke dev --docker`. Auth is off only when `YSQL_PASSWORD` is unset — this recipe
+always sets it.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [YugabyteDB (provider)](/docs/providers/yugabytedb) — managed Aeon Connect flow
+- [CockroachDB](/docs/recipes/cockroachdb) — self-hosted distributed peer
+- [Postgres](/docs/recipes/postgres) — default SQL recipe
+- [Store · SQL](/docs/elements/store#sql) — schema workflows
+
+## Next
+
+<Cards>
+  <Card
+    title="YugabyteDB Aeon"
+    description="Managed cloud alternative."
+    href="/docs/providers/yugabytedb"
+  />
+  <Card
+    title="CockroachDB"
+    description="Self-hosted Cockroach recipe."
+    href="/docs/recipes/cockroachdb"
+  />
+  <Card title="Postgres" description="The default store.sql image." href="/docs/recipes/postgres" />
+</Cards>