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.jsoncdeclares the Durable Object bindings (SHARD, andSCHEDULERif you schedule work), the D1 database for.global()tables, and the R2 bucket for file storage; see the reference config in Deployment. - The
migrationsblock lists your DO classes undernew_sqlite_classes(Durable Object class migrations are wrangler config, not SQL). -
lunora verifypasses. It validateswrangler.jsonc, dry-runs codegen, and runstsc --noEmitwithout writing files; a stale_generated/or a mistyped binding fails here instead of at runtime. -
lunora doctoris clean: it preflights the project's wrangler bindings, placeholder values, and dev secrets.lunora doctor --fixcreates the D1 databases the config names (reusing any that already exist) and writes their ids in, and mints the local.dev.varssecrets. It refuses to write.dev.varsunless git ignores it.--fix --dry-runprints 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_date2026-10-01(flagdurable_object_io_tasks_prevent_eviction), a pending timer,waitUntilor 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. ALunoraClientor anEventsSyncpoll 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 withdurable_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) untilclose()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.examplehas a production value:wrangler secret put NAME --env production, or push in bulk withlunora env push --prod. -
LUNORA_RELAY_SECRETis set on the Worker and on every Durable Object namespace whenever you run more than one shard, read replicas, anEventLogDO, or a shard registry. It signs the internal control channel between Durable Objects. Read replicas,EventLogDOand 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 generatemints 32-byte-hex values for everything locally generatable; provider keys (Resend, Stripe, …) come from the provider dashboard. -
lunora env doctorexits zero; it checks.dev.varsagainst 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 deployaborts 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_TOKENis set as a production secret and is at least 24 characters (theadmin-token-weaksecurity advisor flags shorter ones; see Security). - It is stored only in your secret manager/CI, never in
wrangler.jsoncvarsor 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 alnat.<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 needLUNORA_ADMIN_TOKEN. Revoke one withlunora 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 (solunora importof a blob above the verified-upload cap), the auth jurisdiction copy and purge, and every auth admin op except the reads and the ones that only take access away (ban, revoke a session or invitation). Named tokens requireLUNORA_ADMIN_TOKENto 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 malformedlnat.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 asADMIN_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
Authorizationheader, 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 viaPOST /_lunora/admin/ws-token(itself gated by the master token in theAuthorizationheader). 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 theAuthorizationheader, 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_BEARERis set, a client sends it in theconnectframe, never in?token=, so it is not recorded on every reconnect. A socket that does not present it is closed with4003. See protocol §6.
Rate limiting and abuse
- Public mutations that create users, send mail, or consume credits are
wrapped in
@lunora/ratelimitmiddleware; thepublic_mutation_without_ratelimitadvisor lint finds the gaps. - Consider
protectPublic({ rateLimit, captcha })from@lunora/serverto 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) stampsctx.authon every call; see Authentication. -
authAdminis set if you use the Studio's auth panel (the deprecatedauthIntrospectoroption 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. Nothing applies them: the runtime provisions global tables from the schema on first use (CREATE TABLE IF NOT EXISTS+ additiveADD COLUMN), so any hand-written SQL in a generated file must be applied yourself (wrangler d1 execute <DB> --remote --file=…) before the deploy. - Data migrations (
lunora migrate create <name> --table <table>, run withlunora migrate up) have been dry-run against a copy where the change is destructive. Runs are admin-gated: setLUNORA_ADMIN_TOKENor pass--token. - DO class changes are reflected in the
migrationsblock ofwrangler.jsonc.
Observability
- An observability sink is configured on
createWorker:otlpSinkto a collector,webhookSinkto an error tracker (Sentry, PostHog, …),analyticsEngineSink, or several viacombineSinks. 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
traceparentitself and you want end-to-end waterfalls,trustInboundTraceContextis 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 logstails a deployed worker live; durable retention needs atail_consumersWorker 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/healthis the aggregate probe. It runs every registered check and returns200when all critical dependencies (the Durable Object namespace, D1) are up,503when any critical dependency is down. A non-critical failure (a presence gap on R2, a queue) degrades the reportedstatusto"degraded"but keeps the200, since the deployment still serves traffic. The body'sstatusis one of"healthy","degraded", or"unhealthy".GET /_lunora/health/readyis the readiness gate. It runs only the readiness checks and returns503whenever 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/readyfor 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#2suffix if a kind repeats) plusup/down, so the operator's real binding keys never reach an anonymous caller. Set it to"admin"to bearer-gate the endpoint (viaLUNORA_ADMIN_TOKEN) and include the runtime-authored per-checkmessages and the fullkind:keybinding names to aid an operator, but a monitor polling it must then send the token. - Tune
cacheTtlMsif 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 to5000ms in the"public"posture and0in"admin", while/_lunora/health/readydefaults to0in both — a load-balancer readiness poll must see a dependency drop on the very next poll. An explicitcacheTtlMsoverrides the default for both endpoints, so damping the aggregate probe also starts caching the readiness gate; set0to 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/healthand fails the run on a red status. The flag is opt-in, so a plainlunora verifystays 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 devsave 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
- Deployment: the deploy flow this page gates.
- Security: the secure-by-default posture in detail.
- Versioning & stability: what you're pinning when you pin a version.