okengine 0.9.0 → 0.10.0

package/site/content/docs/providers/yugabytedb.mdx

@@ -0,0 +1,95 @@
+---
+title: "YugabyteDB"
+description: "Distributed SQL (YSQL) — Connect → Application, port 5433, CA cert, YSQL vs YCQL."
+icon: "Database"
+source: "docs/spec/unified-theory.md"
+---
+
+YugabyteDB Aeon exposes a Postgres-compatible query layer (**YSQL**). That is the only
+API oke's `postgres` driver targets — not YCQL.
+
+<Callout title="The one rule">
+  In **Connect → Connect to your Application**, choose **YSQL** and download the CA cert. Port
+  **5433** is the YSQL default — not Postgres's 5432.
+</Callout>
+
+## Find credentials (current console)
+
+1. YugabyteDB Aeon → **Clusters** → select the cluster.
+2. Click **Connect**.
+3. Click **Connect to your Application**.
+4. Click **Download CA Cert** and install it where the app can read it.
+5. Select API **YSQL** (not YCQL).
+6. Pick address mode: **Private Address** / **Private Service Endpoint** if VPC-peered;
+   **Public Address** only if **Settings → Network Access → Public Access** is enabled
+   (not recommended for production).
+7. Copy **Connection String** (or Parameters) into `DATABASE_URL`.
+
+```bash title="process env"
+DATABASE_URL=postgresql://admin:…@….aws.yugabyte.cloud:5433/yugabyte?ssl=true&sslmode=verify-full&sslrootcert=/path/to/root.crt
+```
+
+Also add your app's IPs (or peered VPC) to the cluster **IP allow list** before
+connecting.
+
+## Production guidance
+
+| Topic   | Guidance                                                                      |
+| ------- | ----------------------------------------------------------------------------- |
+| API     | **YSQL only** — YCQL is Cassandra-wire, useless to `postgres`                 |
+| TLS     | `sslmode=verify-full` + downloaded CA                                         |
+| Network | Prefer private / PSE; public access is an explicit opt-in                     |
+| License | Core is **Apache 2.0** (including once-enterprise features in the core build) |
+
+No Neon-style pooled hostname toggle — connection limits and load balancing are
+cluster/VPC topology concerns. Smart drivers want a peered VPC; otherwise they probe
+unreachable nodes first and add latency.
+
+## Real gotcha — wrong API tab
+
+Copying **YCQL** parameters (port **9042**) into `DATABASE_URL` fails immediately —
+different protocol. Always confirm the Connect dialog shows **YSQL** and port **5433**.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Connection timed out / could not connect to server">
+
+IP allow list or Public Access. Add the client IP under network settings, or use the
+private address from a peered VPC. Public hostname stays dark until Public Access is on.
+
+</Accordion>
+<Accordion title="SSL error with verify-full">
+
+CA not downloaded or `sslrootcert` path wrong. Re-run **Download CA Cert** from the
+Connect dialog and point the URI at that file.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [CockroachDB](/docs/providers/cockroachdb) — license / feature comparison
+- [YugabyteDB (self-hosted)](/docs/recipes/yugabytedb) — single-node Docker recipe
+- [Postgres (image)](/docs/recipes/postgres) — driver this backs
+- [Store · SQL](/docs/elements/store#sql) — schema workflows
+
+## Next
+
+<Cards>
+  <Card
+    title="CockroachDB"
+    description="Compare licensing and features."
+    href="/docs/providers/cockroachdb"
+  />
+  <Card
+    title="Supabase"
+    description="Managed single-node option."
+    href="/docs/providers/supabase"
+  />
+  <Card
+    title="Redis Cloud"
+    description="Managed Redis-side pair."
+    href="/docs/providers/redis-cloud"
+  />
+</Cards>

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

@@ -0,0 +1,128 @@
+---
+title: "Caddy"
+description: "Automatic-HTTPS reverse proxy — OKE_PROXY_HOST, Caddyfile, /data certificate volume, single-instance compose."
+icon: "Lock"
+source: "docs/spec/unified-theory.md"
+---
+
+Caddy is the simplest TLS path — automatic HTTPS from a generated `Caddyfile`, no
+certificate management by hand. Right choice for a single app instance without `--scale`.
+
+<Callout title="The one rule">
+  Leave `images.proxy` unset until you need HTTPS at the edge or `--scale app=N`. Once set, `app`
+  stops publishing its host port directly — Caddy (or Traefik) does.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the proxy
+
+```typescript title="oke.config.ts"
+images: {
+  proxy: "caddy:2-alpine",
+},
+```
+
+</Step>
+
+<Step>
+### Set the public hostname
+
+```bash title="docker/.env.docker"
+OKE_PROXY_HOST=app.example.com
+```
+
+Unset defaults to `localhost` — Caddy issues a **local** TLS cert instead of Let's Encrypt.
+
+</Step>
+
+<Step>
+### Include the proxy layer
+
+```bash
+docker compose -f compose.yml -f compose.proxy.yml … up -d
+```
+
+Generated `Caddyfile`: `{$OKE_PROXY_HOST:localhost} { reverse_proxy app:6530 }`.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                | Required?   | Meaning                                                                     |
+| ----------------------- | ----------- | --------------------------------------------------------------------------- |
+| `OKE_PROXY_HOST`        | Recommended | Public hostname for ACME; default `localhost` → local TLS only              |
+| `allowedHosts` (config) | Production  | Must include the public hostname — see [Security](/docs/reference/security) |
+
+Caddy has no separate ACME email env in this recipe (unlike Traefik's
+`OKE_PROXY_ACME_EMAIL`).
+
+## Data and backup
+
+| Volume         | Path                                      | What it stores                  |
+| -------------- | ----------------------------------------- | ------------------------------- |
+| `proxy-data`   | `/data`                                   | ACME certificates, account keys |
+| `proxy-config` | `/config`                                 | Caddy runtime config            |
+| Bind mount     | `./Caddyfile` → `/etc/caddy/Caddyfile:ro` | Generated site block            |
+
+**Backup means:** preserve the `proxy-data` named volume (and ideally `proxy-config`) so
+Let's Encrypt rate limits and cert renewals survive recreates. Losing `/data` forces
+re-issuance. The `Caddyfile` is regenerated by `oke docker`.
+
+## Production note
+
+Caddy has **no** service-discovery story for multiple `app` replicas. Once you run
+`docker compose up --scale app=N`, switch to [Traefik](/docs/recipes/traefik) — it
+discovers replicas from Docker labels instead of a static `reverse_proxy` target.
+
+Also set `allowedHosts` to your public hostname before exposing the edge — see
+[Reverse proxy](/docs/deployment/reverse-proxy).
+
+## What the recipe configures
+
+| Field          | Value                                        |
+| -------------- | -------------------------------------------- |
+| Ports          | `80` + `443` published; `app` stays internal |
+| Healthcheck    | `caddy version`, every 10s, 5 retries        |
+| Connection URL | `https://<host>`                             |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="ACME fails — connection refused / challenge timeout">
+
+`OKE_PROXY_HOST` must be a DNS name that resolves to this host on ports 80/443. Localhost
+never gets a public Let's Encrypt cert — that path uses Caddy's local CA. Check firewall
+and that nothing else binds `:80`.
+
+</Accordion>
+<Accordion title="Browser trust errors on localhost">
+
+Expected with the local CA. Install Caddy's local root for that machine, or set a real
+`OKE_PROXY_HOST` with public DNS when you need a public cert.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy vs Traefik rationale
+- [Docker · Reverse proxy](/docs/deployment/docker#reverse-proxy) — compose layer order
+- [Security](/docs/reference/security) — `allowedHosts`
+
+## Next
+
+<Cards>
+  <Card title="Traefik" description="Multi-replica alternative." href="/docs/recipes/traefik" />
+  <Card
+    title="PgDog"
+    description="Pool Postgres behind the same stack."
+    href="/docs/recipes/pgdog"
+  />
+  <Card title="Redis" description="The default store.kv image." href="/docs/recipes/redis" />
+</Cards>

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

@@ -0,0 +1,127 @@
+---
+title: "CockroachDB"
+description: "Self-hosted single-node Cockroach — COCKROACH_* env, port 26257, DB Console on :8080, driver stays postgres."
+icon: "Database"
+source: "docs/spec/unified-theory.md"
+---
+
+CockroachDB speaks Postgres wire closely enough that `drivers.store.sql` stays
+`postgres`. Pin `cockroachdb/cockroach` as `store.sql` and `oke docker` derives a
+single-node compose service — credentials, healthcheck, and `DATABASE_URL`.
+
+<Callout title="The one rule">
+  The driver id stays `postgres` — vendor choice lives in `images["store.sql"]`, not in
+  `drivers.store.sql`. Host maps `:5432` → container `:26257` so local apps keep the usual Postgres
+  port.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the image
+
+```typescript title="oke.config.ts"
+images: {
+  "store.sql": "cockroachdb/cockroach:v25.2.0", // pin a real tag
+},
+```
+
+</Step>
+
+<Step>
+### Bring the stack up
+
+```bash
+oke dev --docker
+```
+
+`oke docker` injects `COCKROACH_USER` / `COCKROACH_PASSWORD` / `COCKROACH_DATABASE`
+from `OKE_STORE_SQL_*`, starts `start-single-node --accept-sql-without-tls`, and
+publishes SQL on host `:5432` plus the DB Console on `:8080`.
+
+</Step>
+
+<Step>
+### Connect
+
+```bash
+echo "$DATABASE_URL"
+# postgres://oke:…@127.0.0.1:5432/oke?sslmode=require
+```
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                 | Who sets it            | Meaning                              |
+| ------------------------ | ---------------------- | ------------------------------------ |
+| `OKE_STORE_SQL_USER`     | `oke docker` → compose | → `COCKROACH_USER` (first boot only) |
+| `OKE_STORE_SQL_PASSWORD` | `oke docker` → compose | → `COCKROACH_PASSWORD`               |
+| `OKE_STORE_SQL_DB`       | `oke docker` → compose | → `COCKROACH_DATABASE`               |
+| `DATABASE_URL`           | stack env for the app  | Includes `sslmode=require`           |
+
+## Data and backup
+
+| Path                        | What lives there                              |
+| --------------------------- | --------------------------------------------- |
+| `/cockroach/cockroach-data` | Named volume `store-sql-data` — cluster store |
+
+**Backup means:** volume backup of `store-sql-data`, or Cockroach's backup tooling
+against a running node. Losing that volume loses the cluster.
+
+## Production note
+
+This recipe is a **single-node** cluster — fine for local and small self-hosted apps,
+not multi-region HA. For managed multi-region, use the
+[CockroachDB provider](/docs/providers/cockroachdb). Prefer a pinned tag, not `latest`.
+
+## What the recipe configures
+
+| Field          | Value                                        |
+| -------------- | -------------------------------------------- |
+| Container port | `26257` (host publishes `5432`)              |
+| Extra port     | `8080` — DB Console                          |
+| Command        | `start-single-node --accept-sql-without-tls` |
+| Healthcheck    | `GET /health?ready=1` on `:8080`             |
+| Connection URL | `postgres://…?sslmode=require`               |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="oke boot: postgres driver needs DATABASE_URL">
+
+Re-run `oke dev --docker` so the stack writes `docker/.env.docker`, or export
+`DATABASE_URL` yourself when pointing at a remote Cockroach host.
+
+</Accordion>
+<Accordion title="store-sql unhealthy / healthcheck never ready">
+
+First boot can take longer than Postgres. Check
+`docker compose … logs store-sql` for SQL ready. Empty `${OKE_STORE_SQL_PASSWORD}`
+in `.env.docker` leaves the init user broken — regenerate the stack env.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [CockroachDB (provider)](/docs/providers/cockroachdb) — managed Cloud Connect flow
+- [YugabyteDB](/docs/recipes/yugabytedb) — Apache-2.0 self-hosted alternative
+- [Postgres](/docs/recipes/postgres) — default SQL recipe
+- [Store · SQL](/docs/elements/store#sql) — schema push / generate / migrate
+
+## Next
+
+<Cards>
+  <Card
+    title="CockroachDB Cloud"
+    description="Managed multi-region alternative."
+    href="/docs/providers/cockroachdb"
+  />
+  <Card title="YugabyteDB" description="Self-hosted YSQL peer." href="/docs/recipes/yugabytedb" />
+  <Card title="Postgres" description="The default store.sql image." href="/docs/recipes/postgres" />
+</Cards>

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>