---
name: lunora-deploy
description: Deploys a Lunora app to Cloudflare Workers + Durable Objects and gets wrangler.jsonc, remote resources and secrets to line up. Covers `lunora deploy` (and `--env`, `--dry-run`, `--preview`, `--migrate`), the `lunora doctor` / `lunora verify` / `lunora prepare` preflights, Durable Object bindings (SHARD, SHARD_REGISTRY, SCHEDULER), the `DB` D1 binding and its placeholder id, R2 buckets, production secrets (`lunora env push`, `wrangler secret put`) versus `.dev.vars`, the schema-drift gate, the architecture diff, and rollback with `lunora cloudflare deployments`. Use when the user asks to "deploy", "ship to production", "set up a staging environment", wire CI deploys, or when a deploy fails on a binding, a placeholder `database_id`, an unexported Durable Object class, a missing secret, or "schema drift gate blocked deploy".
---

# Lunora Deploy

Deploying a Lunora app means making `wrangler.jsonc`, the remote Cloudflare
resources (D1, R2, secrets) and the worker's exports agree. `lunora deploy`
automates most of that and refuses to ship when they don't.

Local development is `lunora dev` (see `lunora-quickstart`). If the deploy is
blocked by a breaking schema change, stage it with `lunora-migration-helper`
first.

## What `lunora deploy` does

In order, stopping at the first failure:

1. **Codegen** — regenerates `lunora/_generated/`. ERROR-level codegen
   advisories fail the deploy in CI (`--strict-advisories` forces this locally,
   `--no-strict-advisories` turns it off). Nothing here runs `tsc` and wrangler
   strips types, so a project with a type error deploys — gate CI on
   `lunora verify`, which does type-check.
2. **Schema-drift gate** — compares the schema with the committed baseline
   `lunora/.lunora-schema.json` (details below).
3. **Architecture diff** — prints modules and edges (calls, table reads/writes,
   enqueues) added or removed since the last successful deploy. Informational
   only; the manifest is recorded in `.lunora/architecture[.<env>].json` after
   wrangler succeeds.
4. **Binding reconcile** — writes the bindings the code implies into
   `wrangler.jsonc`: Durable Object bindings plus their `new_sqlite_classes`
   migration, the `DB` D1 binding for `.global()` tables, crons, and the
   compatibility date. R2 buckets are not auto-written (the bucket name is
   yours to choose); you get a warning instead.
5. **Read-only checks** — blocks on a D1 `database_id` still set to
   `<replace-with-d1-create-id>`, on a loopback URL (`localhost`, `127.x`,
   `::1`) in `vars`, on a missing container Dockerfile, or on no Docker engine
   when a container builds locally.
6. **Validate `wrangler.jsonc`** — the `SHARD` binding to `ShardDO` (or
   `LunoraDO` for apps that merge their DOs), a minimum `compatibility_date`,
   DO classes registered in `migrations`, and the shape of every binding.
   `compatibility_flags` are not checked; templates ship `nodejs_compat` for
   dependencies that import `node:` builtins.
7. **Secrets gate** — lists the secrets the app's packages need and checks
   which are set on the worker. Interactive runs offer to mint and push the
   generatable ones (`BETTER_AUTH_SECRET`, `LUNORA_ADMIN_TOKEN`, …). In CI a
   missing required secret aborts the deploy. Skipped for `--dry-run` /
   `--preview`, and when the worker doesn't exist yet.
8. **Services, then `wrangler deploy`** — services declared in
   `lunora.config` deploy first (`--skip-services` to skip), then the app.
9. **After a successful deploy** — records the URL as the project link
   (`lunora link`), optionally runs `--migrate` and `--health-check`, and only
   then re-blesses the schema baseline.

`lunora prepare` runs steps 1–6 without deploying (useful in CI), but it takes
no `--env`, so it validates the top-level config only. `lunora verify` runs
validation, a codegen dry run and `tsc --noEmit` without writing files, and does
take `--env`.

Flags worth knowing:

| Flag                       | Effect                                                                          |
| -------------------------- | ------------------------------------------------------------------------------- |
| `--env <name>`             | Deploy a wrangler environment; checks read that env's (non-inherited) bindings. |
| `--dry-run`                | Run every gate and bundle without publishing; `wrangler.jsonc` edits roll back. |
| `--preview`                | Upload a version (`wrangler versions upload`) with a preview URL; no traffic.   |
| `--health-check`           | Probe `/_lunora/health/ready` on the new version; fail if it never answers.     |
| `--prebuilt`               | Skip codegen and the drift gate when `lunora prepare` already ran in this job.  |
| `--migrate`                | Run every declared data migration (`up` is idempotent) against the live worker. |
| `--allow-schema-drift`     | Deploy despite blocked drift; the baseline is not advanced.                     |
| `--update-schema-baseline` | Accept the current schema as the new baseline.                                  |

`--migrate` is checked before wrangler runs, so a missing requirement aborts the
whole deploy:

- `--migrate-yes` — confirms running production data migrations.
- `--migrate-url <https://…>` — required unless this checkout is linked for the
  same `--env` (a previous successful deploy links it automatically).
- An admin token — `--migrate-token` or `LUNORA_ADMIN_TOKEN`.

```bash
lunora deploy --migrate --migrate-yes --migrate-url https://app.example.com
```

## Preflight

```bash
lunora doctor                 # read-only; exits 1 on any FAIL, WARN/INFO don't block
lunora doctor --format json   # each finding carries a stable `code` for CI/agents
lunora verify --env production
```

`lunora doctor` fails on a missing or invalid `wrangler.jsonc`, a missing
`SHARD` binding, a placeholder D1 id (`d1-placeholder-id`), and a binding whose
class the worker doesn't export (`wrangler-class-unexported`), and an Artifacts
namespace in the wrong jurisdiction. It warns on unfilled `.dev.vars` secrets,
placeholder `send_email` destinations, an account near its Durable Object class
cap, and a `cloudflare.config.ts` (`cf-config-present`).

## `wrangler.jsonc`

Templates ship this shape. The `d1_databases` and `r2_buckets` entries are
only needed when the app uses `.global()` tables or auth (D1) and storage (R2):

```jsonc
{
    "name": "my-app",
    "main": "src/server.ts",
    "compatibility_date": "2026-10-01",
    "compatibility_flags": ["nodejs_compat"],
    "durable_objects": {
        "bindings": [
            { "name": "SHARD", "class_name": "ShardDO" },
            { "name": "SHARD_REGISTRY", "class_name": "ShardRegistryDO" },
        ],
    },
    "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ShardDO", "ShardRegistryDO"] }],
    "limits": { "cpu_ms": 30000 },
    "d1_databases": [{ "binding": "DB", "database_name": "my-app", "database_id": "<replace-with-d1-create-id>" }],
    "r2_buckets": [{ "binding": "UPLOADS", "bucket_name": "my-app-uploads" }],
}
```

Reconcile adds `SCHEDULER` → `SchedulerDO` when the app schedules work, and
bindings for generated containers, workflows and agents. Every `class_name`
must be exported by the worker entry or wrangler rejects the deploy.

Lunora writes the bindings but cannot create the remote resources:

```bash
wrangler d1 create my-app              # paste the returned database_id into wrangler.jsonc
wrangler r2 bucket create my-app-uploads
```

When using `--env`, remember that `vars`, `d1_databases`, `durable_objects` and
`containers` do not inherit in wrangler. Each environment needs its own entries,
including its own D1 database.

## Secrets

`.dev.vars` is for development only: it is git-ignored and `wrangler deploy`
never uploads it. Production secrets live in Cloudflare:

```bash
lunora env diff --env production        # keys local-only vs set remotely
lunora env push --env production --yes  # uploads .dev.vars values; refuses placeholders
wrangler secret put RESEND_API_KEY --env production   # set a prod-only value by hand
```

`lunora env push` uploads the values from `.dev.vars`. If production needs
different values than dev (it usually does for provider keys), set those with
`wrangler secret put` instead.

## Schema-drift gate

The gate blocks when the schema changed in a breaking way since
`lunora/.lunora-schema.json` and no new `defineMigration` on the affected table
covers it. The block message lists each change and a paste-ready
`lunora migrate create … --table …` command. Commit the baseline file so CI
and every machine gate against the same shape. It is advanced only after a
successful deploy, so a failed deploy never moves it past a change that didn't
ship.

Reach for `--allow-schema-drift` / `--update-schema-baseline` only when you know
existing data is compatible. Otherwise stage the change with
`lunora-migration-helper`.

## `.global()` table DDL

The runtime provisions `.global()` tables itself on first use
(`CREATE TABLE IF NOT EXISTS` plus additive `ADD COLUMN` / indexes), so additive
changes need no step. `lunora migrate generate` writes a reviewable SQL file for
D1-backed global tables, but no command applies it, `lunora deploy` included.
Destructive or hand-written statements in it (drops, a backfilling `UPDATE`, a
rename) must be applied by hand:

```bash
wrangler d1 execute DB --remote --file=lunora/migrations/<file>.sql
```

See `lunora-migration-helper` for the full flow.

## Rollback

```bash
lunora cloudflare deployments list
lunora cloudflare deployments status             # which versions carry traffic, and how much
lunora cloudflare deployments rollback --yes              # previous version
lunora cloudflare deployments promote <version-id> --yes  # send 100% of traffic to a version
```

A partial rollout (`--percent N --from <live-version-id> --confirm-shared-state`) runs two versions against one Durable Object database. Nothing in `promote` compares the two versions' schemas, so confirm them yourself before using it. Two facts bound the risk: `lunora deploy --preview` runs the schema-drift gate before it uploads, so a version uploaded that way passed it unless `--prebuilt` skipped the gate or `--allow-schema-drift` overrode it; and `wrangler versions upload` refuses a version with a pending Durable Object migration, so that migration reaches traffic only through `deploy`, at 100%. A split whose live version predates a migration the target relies on is not detected by either check.

Rolling back code does not roll back data migrations or D1 DDL.

## Common pitfalls

1. **Placeholder `database_id`.** Reconcile writes
   `<replace-with-d1-create-id>`; deploy refuses it. Run `wrangler d1 create`
   and paste the id.
2. **DO class not exported.** Export `ShardDO` (and any generated container /
   workflow class) from the worker entry; `lunora doctor` names the gap.
3. **Secrets only in `.dev.vars`.** They never reach production. Push or
   `wrangler secret put` them before the first request.
4. **Dev and prod sharing resources.** Give each environment its own D1
   database, R2 buckets and secrets; never point a dev worker at prod data.
5. **Uncommitted schema baseline.** Commit `lunora/.lunora-schema.json` (and
   `lunora/migrations/.snapshot.json` if you use `migrate generate`).
   `lunora/_generated/` is regenerated by deploy; templates git-ignore it.
6. **Using `cf dev` / `cf build` / `cf deploy`.** They read
   `cloudflare.config.ts`, which Lunora never updates
   ([#964](https://github.com/anolilab/lunora/issues/964)). Use `lunora dev` /
   `lunora deploy`; `cf` resource commands (zones, DNS, KV) are fine.

## Checklist

- [ ] `lunora doctor` has no FAIL; `lunora verify --env <name>` passes in CI.
- [ ] D1 / R2 resources created per environment; real ids in `wrangler.jsonc`.
- [ ] Every DO / container / workflow `class_name` is exported by the worker entry.
- [ ] Production secrets set (`lunora env diff --env <name>` shows nothing local-only that prod needs).
- [ ] Breaking schema changes staged with a migration; drift gate green.
- [ ] `lunora deploy --env <name> --health-check` succeeded; `--migrate --migrate-yes` run if backfills were pending.