Skip to content
DocsDocumentation

Production checklist

Everything to verify before a Lunora app takes real traffic — bindings, secrets, admin tokens, rate limits, RLS, migrations, observability.

Last updated:

A pre-deploy checklist for taking a Lunora app to production. Each section links to the page that covers the topic in depth; this page is the gate, not the manual. The mechanics of deploying (wrangler config, the deploy flow, containers, log drains) live in Deployment.

Bindings and wrangler config

  • wrangler.jsonc declares the Durable Object bindings (SHARD, and SCHEDULER if you schedule work), the D1 database for .global() tables, and the R2 bucket for file storage; see the reference config in Deployment.
  • The migrations block lists your DO classes under new_sqlite_classes (Durable Object class migrations are wrangler config, not SQL).
  • lunora verify passes. It validates wrangler.jsonc, dry-runs codegen, and runs tsc --noEmit without writing files; a stale _generated/ or a mistyped binding fails here instead of at runtime.
  • lunora doctor is clean: it preflights the project's wrangler bindings, placeholder values, and dev secrets. lunora doctor --fix creates the D1 databases the config names (reusing any that already exist) and writes their ids in, and mints the local .dev.vars secrets. It refuses to write .dev.vars unless git ignores it. --fix --dry-run prints the same changes without making them. R2 buckets and queues are not created by it.
  • You know what keeps a Durable Object awake. From compatibility_date 2026-10-01 (flag durable_object_io_tasks_prevent_eviction), a pending timer, waitUntil or outbound call blocks idle eviction for up to 15 minutes per operation, and that time is billed. Lunora's own shards arm timers only while a live stream is open. A LunoraClient or an EventsSync poll created inside a Durable Object keeps heartbeat and poll timers armed while idle, so that Durable Object never evicts. Run such clients in a Worker, or opt out with durable_object_io_tasks_do_not_prevent_eviction.
  • A single-page app calls client.close() when it tears the client down. Unsubscribing every query releases a shard's socket after a short idle window, but the default shard's socket is the client's home connection and stays open (with its heartbeat) until close() or page unload.

Secrets

Local secrets live in .dev.vars (gitignored); production secrets are Cloudflare Worker secrets, set per environment. wrangler deploy never pushes .dev.vars values. Full flow in Deployment → Secrets.

  • Every key in .dev.vars.example has a production value: wrangler secret put NAME --env production, or push in bulk with lunora env push --prod.
  • LUNORA_RELAY_SECRET is set on the Worker and on every Durable Object namespace whenever you run more than one shard, read replicas, an EventLogDO, or a shard registry. It signs the internal control channel between Durable Objects. Read replicas, EventLogDO and the shard registry refuse every request without it; the relay alone falls back to trusting any caller inside the Durable Object namespace.
  • Generated secrets are strong. lunora env generate mints 32-byte-hex values for everything locally generatable; provider keys (Resend, Stripe, …) come from the provider dashboard.
  • lunora env doctor exits zero; it checks .dev.vars against the example for missing keys, still-unset placeholders, and stray extras, and works as a CI gate.
  • If you use Cloudflare Secrets Store bindings, functions read them with ctx.secrets.get(name); confirm the store binding exists in the target environment.
  • CI deploys rely on the built-in guard: a non-interactive lunora deploy aborts when a required secret is missing on the target worker.

LUNORA_ADMIN_TOKEN and the admin plane

The admin token gates every /_lunora/admin/* route plus /_lunora/migrate: data export/import, migrations, the Studio, scheduled-job admin.

  • LUNORA_ADMIN_TOKEN is set as a production secret and is at least 24 characters (the admin-token-weak security advisor flags shorter ones; see Security).
  • It is stored only in your secret manager/CI, never in wrangler.jsonc vars or the repo. Rotating it also invalidates every outstanding ephemeral WS sub-token, so rotation is your kill switch.
  • CI jobs and teammates use named admin tokens, not the root token. lunora admin-token create ci-deploy --prod --url … (or Settings → Admin tokens in the Studio) prints a lnat.<name>.<secret> bearer once; the worker stores only its SHA-256. A named token works for the HTTP admin API operations that are not root-only (CLI --token, the MCP server), and the shard audit log records its name. The root-only operations listed below need LUNORA_ADMIN_TOKEN. A pipeline that runs deploy --migrate runs migrate apply as its first step: give that pipeline a token minted with --scope migrations, which runs only additive SQL, and keep the root token for a file that drops or rewrites rows or adds a unique index (a .unique() field generates one). Revoke one with lunora admin-token revoke <name>: the revoking isolate refuses it at once, and every other isolate within 30 seconds (its verification cache); an expiring token stops at its expiry everywhere. Anything that would outlive a revocation needs the root token: managing tokens, admin WebSockets and WS sub-tokens (so the Studio's live panels), pitrRestore, runAs, storage signed URLs (so lunora import of a blob above the verified-upload cap), the auth jurisdiction copy and purge, every auth admin op except the reads and the ones that only take access away (ban, revoke a session or invitation). Named tokens require LUNORA_ADMIN_TOKEN to be set (the worker signs its hop to the shard with it), but rotating it does not revoke them — revoke each by name. Token digests live in a reserved table no SQL console, data browser or export can read, for any caller. A malformed lnat. bearer is refused before any lookup, and each isolate allows only a small burst of lookups for names it has not confirmed. Once that burst is spent, the isolate asks the store for the list of real token names (at most once every few seconds) instead of looking up each invented one, so a flood cannot hammer the default shard or lock out a real token. A token created in the last few seconds can be refused once on another isolate during such a flood; retry. Revocations are recorded in a small Durable Object of their own (AdminRevocationDO, bound as ADMIN_REVOCATIONS) before the token row is deleted, and checked whenever a token is verified, so restoring the default shard to a point before a revocation (pitrRestore) cannot bring a revoked token back. A Vite-first app gets the binding and its migration automatically. A hand-written worker entry must export the class (export { AdminRevocationDO } from "./lunora/_generated/adminRevocations.js"), bind it, and call .adminRevocations((env) => env.ADMIN_REVOCATIONS); without it no named token can be created and any that exist are refused, leaving the root token as the only admin credential.
  • Ephemeral WS tokens stay enforced. A browser WebSocket cannot set an Authorization header, so admin sockets authenticate via ?token=, which lands in access logs and browser history. Instead of the raw master token, the worker mints a short-lived (60s) HMAC-signed sub-token via POST /_lunora/admin/ws-token (itself gated by the master token in the Authorization header). The worker accepts only a minted sub-token in ?token=, never the master token. It forwards the request as it arrived, and the Durable Object refuses a raw master token or raw session bearer in ?token=. Only minted sub-tokens (or the master token in the Authorization header, which never leaks via URLs) authorize. The Studio mints sub-tokens itself and never falls back to the master token. There is no opt-out. The sub-token itself still rides the URL for up to 60 seconds, so proxy and access logs can record it.
  • The session bearer stays out of the URL. When LUNORA_WS_BEARER is set, a client sends it in the connect frame, never in ?token=, so it is not recorded on every reconnect. A socket that does not present it is closed with 4003. See protocol §6.

Rate limiting and abuse

  • Public mutations that create users, send mail, or consume credits are wrapped in @lunora/ratelimit middleware; the public_mutation_without_ratelimit advisor lint finds the gaps.
  • Consider protectPublic({ rateLimit, captcha }) from @lunora/server to chain a rate limit and a CAPTCHA check onto a public procedure in one .use(); see Middleware.

Auth and row-level security

  • Identity is wired: resolveIdentity (or @lunora/auth's handler) stamps ctx.auth on every call; see Authentication.
  • authAdmin is set if you use the Studio's auth panel (the deprecated authIntrospector option is gone; see the upgrade guide).
  • Tables holding user data have row-level security (RLS) policies, and fields that must never reach other users are masked.
  • The secure-by-default edge (CORS allowlist, CSRF guard, security headers) is not switched off in production; the deployment-level security advisors (cors-wildcard-credentials, security-headers-disabled, csrf-disabled, …) audit the live worker. See Security.

Migrations

Lunora has two migration surfaces; see Migrations.

  • D1 schema migrations for .global() tables are generated (lunora migrate generate) and committed as a review artifact. The runtime provisions additive changes on first use, so the drops and hand-written SQL in a generated file are run with lunora migrate apply --url <worker> --yes before the deploy that depends on them. lunora deploy --migrate runs them after the new code is live, so it is not a substitute for a change the new code needs. A project that predates this tracking records the files that already ran with lunora migrate apply --baseline, or --baseline-through <file> when a later file has not run yet, before its first deploy (see Migrations). migrate apply needs the root admin token, or a token minted with --scope migrations, which runs only additive files (a new table or index, an added column) and refuses anything else. lunora migrate status --sql shows what has run.
  • Data migrations (lunora migrate create <name> --table <table>, run with lunora migrate up) have been dry-run against a copy where the change is destructive. Runs are admin-gated: set LUNORA_ADMIN_TOKEN or pass --token.
  • DO class changes are reflected in the migrations block of wrangler.jsonc.

Observability

  • An observability sink is configured on createWorker: otlpSink to a collector, webhookSink to an error tracker (Sentry, PostHog, …), analyticsEngineSink, or several via combineSinks. Without one, a deployed worker's telemetry goes nowhere. See Observability.
  • You know where errors surface: the Studio groups error events into Issues: deterministic fingerprinting collapses the same error across live events and request-log rows into one issue.
  • If the worker sits behind a gateway or mesh that sets traceparent itself and you want end-to-end waterfalls, trustInboundTraceContext is set. Leave it off on anything an untrusted client can reach directly: the header is caller-supplied, so honouring it lets a client pick which trace its spans and logs join. See Joining a trace from upstream.
  • Log access is sorted: lunora logs tails a deployed worker live; durable retention needs a tail_consumers Worker or "logpush": true. See Deployment → Streaming logs.

Health and readiness endpoint

The worker exposes two public probe routes an uptime monitor or load balancer can poll. They return a small JSON body (a status, per-check up/down, and static app metadata) and never leak a secret, env value, connection string, or binding name.

  • GET /_lunora/health is the aggregate probe. It runs every registered check and returns 200 when all critical dependencies (the Durable Object namespace, D1) are up, 503 when any critical dependency is down. A non-critical failure (a presence gap on R2, a queue) degrades the reported status to "degraded" but keeps the 200, since the deployment still serves traffic. The body's status is one of "healthy", "degraded", or "unhealthy".
  • GET /_lunora/health/ready is the readiness gate. It runs only the readiness checks and returns 503 whenever any is unhealthy, so a load balancer stops routing to a not-yet-ready instance.

Checklist:

  • Point an uptime monitor or a Cloudflare Health Check at /_lunora/health (open in dashboard: Traffic → Health Checks) so a critical-binding outage pages you. Use /_lunora/health/ready for a load balancer's origin health / readiness pool.
  • Decide the auth posture. The default is "public": unauthenticated, message-redacted, and name-redacted: each check surfaces only its probe kind (d1, r2, queue, …, with a #2 suffix if a kind repeats) plus up/down, so the operator's real binding keys never reach an anonymous caller. Set it to "admin" to bearer-gate the endpoint (via LUNORA_ADMIN_TOKEN) and include the runtime-authored per-check messages and the full kind:key binding names to aid an operator, but a monitor polling it must then send the token.
  • Tune cacheTtlMs if needed. The last computed report is reused within the window so repeated probes (or an unauthenticated flood) don't re-hit the bindings on every request. The defaults differ per endpoint: /_lunora/health (aggregate) defaults to 5000 ms in the "public" posture and 0 in "admin", while /_lunora/health/ready defaults to 0 in both — a load-balancer readiness poll must see a dependency drop on the very next poll. An explicit cacheTtlMs overrides the default for both endpoints, so damping the aggregate probe also starts caching the readiness gate; set 0 to always run live.
  • The Studio's Deployment health page (under Observability) reads these same endpoints live: a quick operator view of liveness, readiness, and per-binding status.
  • Optionally gate CI on it: lunora verify --health-url https://<your-app> probes /_lunora/health and fails the run on a red status. The flag is opt-in, so a plain lunora verify stays offline-safe.

Limits

  • You've read Limits and know which Cloudflare ceiling you'll hit first: Durable Object (DO) SQLite size and per-DO request rate are the usual sharding signals, subrequest counts bound fan-out reads.
  • A large app's startup stays well under Cloudflare's 1 s CPU limit (npx wrangler check startup); past it the deploy fails with error 10021. See Worker startup CPU limit.

Advisors as the final gate

  • Codegen's static advisories are clean; they run on every lunora dev save and on deploy, and catch unindexed foreign keys, filters without indexes, unguarded admin routes, and more before they ship.
  • The Studio's Advisors panels (Security, RLS, Insights) show no unaddressed ERROR-level findings against a staging deployment; the runtime lints (hot shards, index utilization, constraint violations) need observed traffic. See Advisors.

See also