okengine 0.18.5 → 0.19.0

package/site/content/docs/deployment/kubernetes.mdx

@@ -1,176 +0,0 @@
----
-title: Kubernetes
-description: Run an OKE app as a plain Deployment — PgDog, readiness vs liveness probes, graceful SIGTERM, shared drivers, and honest multi-instance limits.
-icon: Container
-source: README.md
----
-
-OKE apps are safe to run as more than one replica when shared drivers back
-Clock, Journal, Gate, and Store. Kubernetes is full orchestration with the
-largest ecosystem — use a **Deployment**, never a StatefulSet.
-
-<Callout title="The one rule">
-  Treat every replica as replaceable. Put durable state in Postgres / Redis / S3, probe `GET
-  /_/ready` for readiness and app `GET /health` for liveness, and set
-  `terminationGracePeriodSeconds` high enough for lease release on SIGTERM.
-</Callout>
-
-## Quick start
-
-<Steps>
-
-<Step>
-### Deploy as a Deployment
-
-Use a plain Kubernetes **Deployment** (or compatible replica set). Do **not**
-use a StatefulSet — there is no per-pod volume identity, ordered startup, or
-sticky network id to preserve. Scale with `replicas: N`.
-
-</Step>
-
-<Step>
-### Share backing services
-
-Pin `dev`/`prod` drivers to shared stores:
-
-| Concern                       | Driver                       | Shared backend                                    |
-| ----------------------------- | ---------------------------- | ------------------------------------------------- |
-| SQL / durable journal / clock | `postgres`                   | Postgres (optionally via PgDog)                   |
-| Gate rate counters            | `redis` (`drivers.store.kv`) | Redis / Valkey / Dragonfly (`images["store.kv"]`) |
-| Files                         | `s3`                         | S3-compatible object store                        |
-| Signal                        | see known limits below       | —                                                 |
-
-</Step>
-
-<Step>
-### Probe readiness and liveness
-
-- **Readiness:** `GET /_/ready` — returns `200 { ready: true }` only after boot and the durable orphan scan finish. While booting or scanning orphans it returns `503 { ready: false, reason: "booting" | "orphan_scan" }`.
-- **Liveness:** app-authored `GET /health` (create-oke ships one) — cheap “process is alive,” not orphan-scan aware.
-
-Wire `readinessProbe` to `/_/ready` and `livenessProbe` to `/health`.
-
-</Step>
-
-</Steps>
-
-## PgDog pooling
-
-Bun.SQL defaults to **10** connections per process — fine for one pod.
-Scale the Deployment and `N × pool` can exceed Postgres `max_connections`.
-
-When both `store.sql` and `pgdog` are pinned (`dev`/`prod` default in templates),
-`DATABASE_URL` points at PgDog on port `6432` — transaction pooling, wire-protocol
-transparent to Bun.SQL / Drizzle. Point the cluster Service at that pooler.
-
-**Why PgDog.** Transaction pooling fixes the connection math. Naive poolers can
-leak session state (`SET`, RLS vars, `LISTEN`/`NOTIFY`) across clients; PgDog
-re-applies those under transaction mode.
-
-Read-replica routing (`BEGIN READ ONLY` → replica) is documented readiness —
-not configured as a generated Kubernetes manifest this round.
-
-## Redis-protocol images (Redis · Valkey · Dragonfly)
-
-`images["store.kv"]` defaults to Redis (most mature). Pin Valkey or Dragonfly
-the same way — driver id stays `redis`, same `REDIS_URL`. Image table + one-line
-licenses: [Store · KV](/docs/elements/store#kv).
-
-## Readiness vs liveness
-
-| Endpoint       | Role                                                   | Kubernetes                                       |
-| -------------- | ------------------------------------------------------ | ------------------------------------------------ |
-| `GET /_/ready` | Kernel readiness (`booting` → `orphan_scan` → `ready`) | `readinessProbe` — no traffic until Ready        |
-| `GET /health`  | App liveness (create-oke) — cheap “process alive”      | `livenessProbe` — restart if the process is dead |
-
-**Consequence:** orphan scan delays Ready (and traffic) on purpose so a new
-pod is not hit mid-takeover. Do not point liveness at `/_/ready` — a long orphan
-resume would kill the pod instead of waiting.
-
-## Graceful shutdown
-
-On `SIGTERM` / `SIGINT`, `installGracefulShutdown` (wired by `oke dev`’s app
-runner; call it next to `createBunRuntime().serve` in custom entries):
-
-1. Stops accepting new connections
-2. Releases **Clock** cron leases and **Journal** run leases held by this instance
-3. Closes element runtimes and exits
-
-Signal message leases have no proactive release today — survivors reclaim after
-the visibility TTL (default 30s). Set `terminationGracePeriodSeconds` ≥ your
-longest lease TTL (typically ≥ 30s) so release finishes before kubelet SIGKILL.
-
-## Ingress (TLS / routing)
-
-Use cluster-native **Ingress** or Gateway API for HTTPS.
-Compose `images.proxy` recipes (Caddy / Traefik / nginx) target plain Docker and Swarm —
-see [Reverse proxy](/docs/deployment/reverse-proxy) when you are not on Kubernetes.
-
-Still set serve `allowedHosts` to the public hostname
-([Security](/docs/reference/security)).
-
-## Known multi-instance limits
-
-Be honest about what is still process-local:
-
-| Surface                                  | Multi-instance today                                                                                       |
-| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| Clock (`postgres` / shared `file`)       | Shared leader election                                                                                     |
-| Journal (`postgres` / shared `file`)     | Shared durable runs + orphan resume                                                                        |
-| Gate rates (`drivers.store.kv: redis`)   | Shared counters                                                                                            |
-| Store SQL / KV redis / files `s3`        | Shared                                                                                                     |
-| Store files `fs`                         | **Per-instance filesystem** — boot warns; use `s3` when scaled                                             |
-| Signal `redis`                           | Emit relays to Redis; **consume / `live` / `drain` are process-local outbox** until Streams consume ships  |
-| Channel suppression / consent / receipts | **Default stores are process-local** — opt-out on replica A is invisible to B until a durable driver ships |
-
-## Troubleshooting
-
-<Accordions>
-<Accordion title="Pods pass liveness but get no traffic after deploy">
-
-Check readiness: `/_/ready` stays `503` with `reason: "orphan_scan"` until the
-durable orphan resume finishes. A long resume delays Ready; that is intentional
-so traffic does not hit a pod mid-takeover.
-
-</Accordion>
-<Accordion title="Rate limits look twice as high after scaling to 2">
-
-`drivers.store.kv` must be `redis` with `REDIS_URL` set. A missing URL now
-**fails boot** (no silent memory fallback). Declaring `memory` for local is fine;
-`dev`/`prod` should stay on redis.
-
-</Accordion>
-<Accordion title="Files uploaded on pod A are missing on pod B">
-
-`drivers.store.files: "fs"` is single-host. Switch `dev`/`prod` to `s3`
-(create-oke templates already do).
-
-</Accordion>
-<Accordion title="Pod killed during orphan scan">
-
-Liveness is pointed at `/_/ready`. Move liveness to `/health`; keep readiness
-on `/_/ready` so the pod stays Alive while Waiting for Ready.
-
-</Accordion>
-</Accordions>
-
-## Learn more
-
-- [Deployment](/docs/deployment) — choose compose, Swarm, or Kubernetes
-- [Docker](/docs/deployment/docker) — plain compose
-- [Docker Swarm](/docs/deployment/docker-swarm) — `docker stack deploy`
-- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik / nginx (non-K8s)
-- [Store](/docs/elements/store) — PgDog and facets
-- [Clock](/docs/elements/clock) — shared CronStore / leader election
-- [Flow](/docs/elements/flow) — durable journal
-- [Signal](/docs/elements/signal) — delivery modes and redis honesty
-- [Channel](/docs/elements/channel) — suppression process-local limit
-- [CLI](/docs/reference/cli) — `oke docker --prod`, `oke start`
-
-## Next
-
-<Cards>
-  <Card title="Deployment" href="/docs/deployment" />
-  <Card title="Docker" href="/docs/deployment/docker" />
-  <Card title="Docker Swarm" href="/docs/deployment/docker-swarm" />
-</Cards>

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

@@ -1,5 +0,0 @@
-{
-  "title": "Deployment",
-  "icon": "Server",
-  "pages": ["index", "docker", "docker-swarm", "kubernetes", "reverse-proxy"]
-}

package/site/content/docs/deployment/reverse-proxy.mdx

@@ -1,234 +0,0 @@
----
-title: Reverse proxy
-description: Opt-in Caddy, Traefik, or nginx for edge routing on plain Docker and Swarm — custom domains, Let's Encrypt, and the socket-proxy security model.
-icon: Globe
-source: README.md
----
-
-Pin `images.proxy` when you need an edge in front of the app on plain `docker compose` or
-Docker Swarm. Kubernetes uses cluster Ingress / Gateway API instead — this page
-is for the compose recipes.
-
-<Callout title="The one rule">
-  Leave the no-proxy default until you need an edge on compose. Then pick **Caddy** (automatic
-  HTTPS), **Traefik** (`--scale app=N`), or **nginx** (HTTP; TLS elsewhere). Never mount raw
-  `docker.sock` into Traefik.
-</Callout>
-
-## Quick start
-
-<Steps>
-
-<Step>
-### Opt in (pick one)
-
-```typescript title="oke.config.ts"
-images: {
-  "store.sql": "postgres:18-alpine",
-  // …
-  proxy: "caddy:2-alpine", // or "traefik:v3.7" / "nginx:1.31-alpine"
-},
-```
-
-Pin **one** proxy image — never two. `create-oke` asks **Add a reverse proxy…?** (or
-`--proxy`). Re-run `oke docker --prod`.
-
-</Step>
-
-<Step>
-### Set the public host and ACME email
-
-```bash title=".env.local"
-OKE_PROXY_HOST=app.example.com
-OKE_PROXY_ACME_EMAIL=admin@example.com
-```
-
-`.env.local` is preserved across regeneration. Point DNS `A`/`AAAA` at the host.
-
-</Step>
-
-<Step>
-### Bring the stack up
-
-```bash
-cd docker
-docker compose -f compose.yml -f compose.store.sql.yml \
-  -f compose.proxy.yml -f compose.prod.yml up -d
-```
-
-Pass every `-f` file `oke docker` listed. The edge publishes `80`/`443`; `app`
-stays on the internal `oke` network (no host bind on `6530`).
-
-Add your public hostname to serve `allowedHosts`
-([Security](/docs/reference/security)).
-
-</Step>
-
-</Steps>
-
-## Which proxy?
-
-| Choice                          | Best for                                                   | How routing works                                                  |
-| ------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
-| **Caddy** (`caddy:2-alpine`)    | hello / minimal / standard — single instance, simplest TLS | Generated `Caddyfile` → `reverse_proxy app:6530`; automatic HTTPS  |
-| **Traefik** (`traefik:v3.7`)    | Horizontally scaled plain compose                          | Docker labels on `app`; replicas auto-discovered and load-balanced |
-| **nginx** (`nginx:1.31-alpine`) | Static HTTP edge; TLS elsewhere                            | Generated `nginx.conf` → `proxy_pass` to `app:6530` on `:80`       |
-| _(omit `images.proxy`)_         | Local / private networks                                   | App publishes `6530` — **default, unchanged**                      |
-
-**Consequence:** Caddy is the recommended default when you just need a certificate.
-Choose Traefik when `docker compose up --scale app=N` is the deployment shape.
-Choose nginx when another edge already terminates TLS.
-
-## Caddy
-
-Emits `docker/Caddyfile`:
-
-```text
-{$OKE_PROXY_HOST:localhost} {
-	reverse_proxy app:6530
-}
-```
-
-| Setting                | What it does                                                                                                                                 |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `OKE_PROXY_HOST`       | Site address. `localhost` → local TLS; a public DNS name → Let's Encrypt HTTP-01                                                             |
-| `OKE_PROXY_ACME_EMAIL` | Written into `.env.local` for the proxy role. Traefik consumes it; for Caddy, add a global `email` block if you want a specific ACME contact |
-
-Custom domain:
-
-1. DNS for `app.example.com` → this host
-2. `OKE_PROXY_HOST=app.example.com` in `.env.local`
-3. Ports `80`/`443` reachable from the public internet
-4. `allowedHosts` includes `app.example.com`
-
-Override the file via `compose.override.yml` or replace `docker/Caddyfile` —
-`oke docker` regenerates the default on the next run.
-
-## Traefik
-
-Generated `compose.proxy.yml` labels `app`:
-
-| Label                                                     | Meaning                                      |
-| --------------------------------------------------------- | -------------------------------------------- |
-| `traefik.enable=true`                                     | Advertise this service to Traefik            |
-| `traefik.http.routers.app.rule=Host(…)`                   | Match `OKE_PROXY_HOST` (default `localhost`) |
-| `traefik.http.routers.app.entrypoints=websecure`          | HTTPS entrypoint                             |
-| `traefik.http.routers.app.tls.certresolver=letsencrypt`   | ACME via Let's Encrypt                       |
-| `traefik.http.services.app.loadbalancer.server.port=6530` | Upstream port on the compose network         |
-
-HTTP (`:80`) redirects to HTTPS. ACME email comes from
-`OKE_PROXY_ACME_EMAIL` (default `admin@example.com`) on the Traefik command line.
-
-Scaled replicas need no label edits — `docker compose up --scale app=N` registers
-every replica through the Docker provider.
-
-## nginx
-
-| Piece          | Meaning                                                                 |
-| -------------- | ----------------------------------------------------------------------- |
-| Generated file | `docker/nginx.conf` — `proxy_pass` to `app:6530` on `:80`               |
-| TLS            | None in-container — put Cloudflare / an ALB in front, or switch recipes |
-| Full recipe    | [nginx](/docs/recipes/nginx)                                            |
-
-## Why docker-socket-proxy (Traefik)
-
-Traefik's Docker provider watches the Engine API for containers and labels.
-The naive setup mounts `/var/run/docker.sock` into Traefik itself.
-
-That socket is root-equivalent for the host Docker daemon. If the edge process
-is compromised (public `80`/`443`), an attacker with the raw socket can start
-privileged containers, mount the host filesystem, or escape the container.
-
-Traefik [documents this risk](https://doc.traefik.io/traefik/reference/install-configuration/providers/docker/)
-and recommends a filtered proxy. OKE **never** mounts `docker.sock` into Traefik —
-a companion `tecnativa/docker-socket-proxy` mounts it read-only and exposes only:
-
-| Flag         | Why Traefik needs it       |
-| ------------ | -------------------------- |
-| `CONTAINERS` | List / inspect for labels  |
-| `EVENTS`     | Watch start/stop for scale |
-| `PING`       | Health of the Engine API   |
-| `VERSION`    | API negotiation            |
-| `NETWORKS`   | Network membership         |
-
-Destructive Engine calls (`images`, `volumes`, exec, swarm admin, …) stay denied.
-Traefik uses `--providers.docker.endpoint=tcp://socket-proxy:2375` on the
-internal `oke` network only — do **not** publish `2375` on the host.
-
-**Consequence:** a compromised Traefik still talks to a narrow API surface, not
-the full Docker control plane.
-
-## Environment
-
-| Variable               | Default             | Used by                                   |
-| ---------------------- | ------------------- | ----------------------------------------- |
-| `OKE_PROXY_HOST`       | `localhost`         | Caddy site address; Traefik `Host()` rule |
-| `OKE_PROXY_ACME_EMAIL` | `admin@example.com` | Traefik ACME account email                |
-
-## Where this applies
-
-| Surface                                       | Edge / ingress                                           |
-| --------------------------------------------- | -------------------------------------------------------- |
-| [Docker](/docs/deployment/docker)             | Opt-in Caddy / Traefik / nginx (`images.proxy`)          |
-| [Docker Swarm](/docs/deployment/docker-swarm) | Same proxy recipes + Swarm routing mesh                  |
-| [Kubernetes](/docs/deployment/kubernetes)     | Ingress / Gateway API (cluster-native — not this recipe) |
-
-## Troubleshooting
-
-<Accordions>
-<Accordion title="compose up --scale app=N fails with port already allocated">
-
-You still have `6530:6530` on `app`. Confirm `images.proxy` is set and
-`compose.proxy.yml` is in the `-f` list so derivation omitted the host bind.
-
-</Accordion>
-<Accordion title="Let's Encrypt challenge fails">
-
-`OKE_PROXY_HOST` must be a public DNS name pointing at this host; ports `80`/`443`
-reachable. Set `OKE_PROXY_ACME_EMAIL` for Traefik. For localhost-only smoke tests, prefer Caddy.
-
-</Accordion>
-<Accordion title="Traefik starts but never routes to app">
-
-Confirm app labels are present (`traefik.enable=true`) in `compose.proxy.yml`,
-containers share the `oke` network, and `socket-proxy` is healthy. Traefik must
-not mount `docker.sock` itself.
-
-</Accordion>
-<Accordion title="oke dev: service app has neither an image nor a build context">
-
-`oke dev` starts infra only; the app stays on the host at `:6530`.
-Proxy recipes route to a Compose `app` service — use `oke docker` for that.
-Re-run `oke dev` after upgrading so compose drops the label-only `app`.
-
-</Accordion>
-<Accordion title="Host header rejected (403)">
-
-Serve validates `Host`. Add your public hostname to `allowedHosts`
-([Security](/docs/reference/security)).
-
-</Accordion>
-<Accordion title="Caddy serves localhost certs on my public host">
-
-`OKE_PROXY_HOST` is still `localhost` (or unset). Set the public DNS name in
-`.env.local` and recreate the proxy container so it reloads the Caddyfile.
-
-</Accordion>
-</Accordions>
-
-## Learn more
-
-- [Deployment](/docs/deployment) — pick compose, Swarm, or Kubernetes
-- [Docker](/docs/deployment/docker) — plain compose path (includes proxy opt-in)
-- [Docker Swarm](/docs/deployment/docker-swarm) — `docker stack deploy`
-- [CLI](/docs/reference/cli) — `oke docker`, `oke docker --prod`
-- [Configuration](/docs/reference/configuration) — `images` pins
-- [Security](/docs/reference/security) — `allowedHosts` behind a reverse proxy
-
-## Next
-
-<Cards>
-  <Card title="Deployment" href="/docs/deployment" />
-  <Card title="Docker" href="/docs/deployment/docker" />
-  <Card title="Docker Swarm" href="/docs/deployment/docker-swarm" />
-</Cards>