# Production Deploys

> Deploy production to your own Cloudflare account: API token, first deploy, Worker secrets, Workers Builds, branch protection, rollback and DATABASE_URL.

*Canonical: https://makerkit.dev/docs/void-cloudflare/deployment/production*

---

Production deploys from `main` to the Worker `web` on your Cloudflare account. You set it up in this order: the first deploy runs from your machine, then Workers Builds takes over.

This page is part of the [Deployment documentation](./overview).

## Before You Start

- A Cloudflare account on **Workers Paid** ($5/month), with a `workers.dev` subdomain (Workers & Pages → your subdomain, for example `my-team`). The kit needs Paid to run reliably: Free can't send email to your users (verification, password reset), and password hashing at sign-in and sign-up can exceed Free's 10 ms CPU limit.
- Your email sender set in `apps/web/void.config.ts` (`email: { from: 'Acme <noreply@mail.acme.com>' }`), on a domain in your Cloudflare account; a mail subdomain keeps existing mail on the root domain. The first deploy offers to set up Email Sending for it; if it needs onboarding after upgrading, run `pnpm --filter web exec void email setup --platform cloudflare` once.
- A **PostgreSQL 17 or newer** database reachable from Cloudflare. Its URL is the deploy's `DATABASE_URL`. The background jobs outbox needs 17 (`transaction_timeout`); the deploy refuses an older server before it migrates anything.
- A clean checkout of the commit you want to deploy, with migrations committed (`void db generate`).

### Choosing a Database

Any hosted PostgreSQL 17 or newer works. If you don't have one yet:

| Provider | Plan | Notes |
|---|---|---|
| [PlanetScale](https://planetscale.com) | From $5/month | **Recommended.** Cloudflare's dashboard has a one-click setup for it |
| [Neon](https://neon.com) | Free plan | Good for trying the kit out |
| [Supabase](https://supabase.com) | Free plan | Good for trying the kit out. Use it as a database only: auth and storage are the kit's |

Create the database in the region closest to most of your visitors. A Worker that runs far from its database pays for the distance on every query: [CPU and Database](../operations/cpu-and-database#where-the-database-is) explains how to place the Worker near it. Cloudflare's [PlanetScale guide](https://developers.cloudflare.com/workers/databases/third-party-integrations/planetscale/) covers the same for PlanetScale. Skip that guide's Hyperdrive step: the kit's deploy creates the Hyperdrive config from `DATABASE_URL`.

Pick PostgreSQL 17 or newer when you create the database (18, the latest, is the best choice), and copy its connection URL: that is the deploy's `DATABASE_URL`. You don't need a hosted database for local development: the kit runs its own.

## Create the API Token

In Cloudflare: My Profile → API Tokens → Create Token → Custom token. Scope it to your account.

| Permission | Needed for |
|---|---|
| Account → Workers Scripts: Edit | Uploading and activating the Worker, its secrets and versions |
| Account → Hyperdrive: Edit | Creating the Hyperdrive config from `DATABASE_URL` |
| Edit access to each product Void provisions | Only when your app uses it: Workers KV Storage, Workers R2 Storage, Queues and so on |
| Email Routing: Edit, Email Sending: Edit | Only when your app sends email |

Void's rule is "Workers Scripts: Edit, read access to bound resources, and edit access to products Void provisions". Add a permission when you add a resource. If a deploy stops on a permission error, add the permission Cloudflare names in the message and run it again.

## Database Role Settings

Once, as the database owner, for the role `DATABASE_URL` connects as (background jobs need the first; [Deploying the Outbox](../outbox/deployment)):

```sql
ALTER ROLE app_role SET idle_in_transaction_session_timeout = '60s';
ALTER ROLE app_role SET lock_timeout = '5s';
```

## First Deploy From Your Machine

Workers Builds never makes the first deploy. The deploy creates resources and writes their IDs to `apps/web/void.lock.json`, and a build can't commit that file. The Worker must also exist before you can connect it.

```bash
pnpm --filter web exec void cloudflare login
# or: export CLOUDFLARE_API_TOKEN=… CLOUDFLARE_ACCOUNT_ID=…

pnpm --filter web exec void secret put SITE_URL      # your production URL
pnpm --filter web exec void secret put PRODUCT_NAME
pnpm --filter web exec void secret put BETTER_AUTH_SECRET   # openssl rand -base64 32

# migrates the database and creates its Hyperdrive config
DATABASE_URL='postgresql://…' pnpm --filter web exec vp run deploy

# once: turn off Hyperdrive's query cache (id: "hyperdrive" in apps/web/void.lock.json)
pnpm --filter web exec wrangler hyperdrive update <hyperdrive-id> --caching-disabled true

git add apps/web/void.lock.json && git commit -m "chore: production lock"
```

The Worker is `web`, from `apps/web/package.json`. Push the lock to `main` before connecting Workers Builds.

`apps/web/.void/project.json` (`{"platform": "cloudflare"}`) is committed, the only file in `.void/` that is: without it, `void secret` and other plain `void` commands take Void's hosted path.

## Worker Secrets

Runtime values are Worker secrets, set from your machine. Builds never set them.

| Command | |
|---|---|
| Set one (prompts) | `pnpm --filter web exec void secret put <KEY>` |
| Set many (dotenv file) | `pnpm --filter web exec void secret sync <file>` |
| List names | `pnpm --filter web exec void secret list` |
| Delete | `pnpm --filter web exec void secret delete <KEY>` |

- Keep sync files **outside the repository** (`~/secrets/production.env`), as an absolute path. Any `.env.*` file in `apps/web` stops Void.
- A sync file holds only keys declared in `env.ts`. Never put `DATABASE_URL` in it.
- Every key, its default and its allowed values are in [Environment Variables](../configuration/environment-variables#reference). Keys with a default can stay unset.
- `void deploy` refuses to deploy while a required key is missing remotely, so a new required key in `env.ts` needs its secret set before you push.

## Connect Workers Builds

In Cloudflare: Workers & Pages → `web` → Settings → Build → Connect. Install the Cloudflare Workers & Pages GitHub App when asked, and give it access to this repository only.

| Setting | Value |
|---|---|
| Production branch | `main` |
| Root directory | blank (repository root) |
| Build command | blank |
| Deploy command | `pnpm --filter web exec vp run deploy` |
| Non-production branch builds | **Off** |

- **Keep non-production branch builds off.** Otherwise every branch's code builds with production's token, database URL and secrets.
- Builds installs dependencies with pnpm from `pnpm-lock.yaml`, at the version in `package.json`'s `packageManager`. Node defaults to 24; set the `NODE_VERSION` build variable to change it.

Then add **build** variables and secrets (Settings → Build → Variables and secrets). They exist during the build only, never at runtime:

| Kind | Name | Value |
|---|---|---|
| Secret | `CLOUDFLARE_API_TOKEN` | The token from [Create the API Token](#create-the-api-token) |
| Variable | `CLOUDFLARE_ACCOUNT_ID` | Your account ID (Workers & Pages → Account details). Void needs it when the token can reach more than one account |
| Secret | `DATABASE_URL` | The production Postgres URL. Used for migrations only |
| Variable | `CLOUDFLARE_WORKERS_SUBDOMAIN` | Your `workers.dev` subdomain, e.g. `my-team`. Void uses it to reach the new version for the readiness check when the version has no preview URL |
| Secret, optional | `CF_ACCESS_CLIENT_ID`, `CF_ACCESS_CLIENT_SECRET` | A Cloudflare Access service token, when Access protects the Worker |

Set your own `CLOUDFLARE_API_TOKEN` even though Workers Builds runs inside your account: `void deploy` needs the permissions listed above.

Limits: a build times out after 20 minutes; 3,000 build minutes a month on Free, 6,000 on Paid.

## Protect Main

Deploys start on the push and don't wait for the GitHub checks. In GitHub: Settings → Branches (or Rules) → add a rule for `main`:

- Require a pull request before merging.
- Require status checks to pass: `Format, lint and types`, `Unit tests`, `Build`, `E2E`.
- Block direct pushes, or limit them to people you trust.

A direct push to an unprotected `main` deploys without the checks.

## What a Deploy Does

On a push to `main`, Workers Builds installs dependencies and runs `vp run deploy` (`tooling/scripts/src/deploy.mjs`, which passes any extra arguments to `void deploy --platform cloudflare`):

1. The kit checks that `DATABASE_URL` is PostgreSQL 17 or newer, and stops before anything migrates if it isn't.
2. Void checks the required Worker secrets and schema drift, migrates the database with `DATABASE_URL`, uploads a version, checks `/__void/ready` on it, then sends it traffic. It restores the previous version if readiness fails.

The same task deploys from your machine.

## Adding a Resource

Adding KV, R2, a queue or email to the app changes the lock: the deploy writes the new resource IDs to `void.lock.json`. Deploy that change from your machine (`pnpm --filter web exec vp run deploy`) and commit the lock before pushing. A build would provision the resource and deploy, but its updated lock is lost with the build.

If you did push first, deploy from your machine afterwards and check the Cloudflare dashboard for a second resource of the same kind before you commit the lock.

## Rollback

```bash
pnpm --filter web exec void project status            # versions
pnpm --filter web exec void project rollback [version]
```

Without a version, rollback shows a menu. It activates that Worker Version at 100% and restores its triggers when both versions recorded them.

**Rollback never reverts migrations.** The older code runs against the newer schema, so write migrations expand-then-contract:

1. **Expand:** add the new column or table; keep the old one. Deploy code that works with both.
2. **Contract:** drop the old one in a later deploy, once no live or rollback-target version reads it.

A deploy that fails readiness has already migrated. Fix forward with a new deploy, or with a new migration.

## DATABASE_URL Rules

- **Deploy shell only.** `void deploy` reads `DATABASE_URL` from its environment to create the Hyperdrive config and run migrations. Locally, prefix the deploy command; in Workers Builds it is a build secret. `vp run deploy` stops with `deploy: set DATABASE_URL in the deploy shell` when the variable is missing. Always set it explicitly, so the deploy can never pick up your local database.
- **Hyperdrive at runtime.** The deployed Worker connects through the `HYPERDRIVE` binding, which pools connections near your database.
- **Turn on Analytics Engine.** Audit events are stored in a Cloudflare Analytics Engine dataset that `void.config.ts` binds. On an account that never used it, the first deploy stops with code 10089: open [Analytics Engine in the Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/analytics-engine), select **Enable**, and deploy again. Without the binding audit events only reach the logs ([Audit Log](../audit/overview)). Every deploy also binds the admin's audit reader (`AUDIT_SQL`). It only works deployed; locally there is no reader and no Cloudflare login ([Read the Audit Log](../audit/reading-the-log)).
- **Check the live site.** `SITE_URL=https://your-site.com pnpm kit:doctor --prod` reads `/robots.txt` and `/api/health` ([Operations](../operations/health)). The health check is only meaningful with query caching off.
- **Query caching off.** Hyperdrive caches `SELECT` results for up to 60 seconds by default, and `void deploy --platform cloudflare` creates the config with it on (only Void's hosted platform turns it off). Cached reads would let a revoked session, or a member removed from an organization, keep access for up to a minute. Turn it off once after the first deploy (command above) and check it in the dashboard (Hyperdrive → your config → Caching).
- **Never a Worker secret.** Void prefers a `DATABASE_URL` secret over Hyperdrive, so a Worker with one bypasses the pool. Check with `void secret list`, and remove it with `pnpm --filter web exec void secret delete DATABASE_URL`.
- **`void db` commands read `apps/web/.env` only**, not the shell. Don't point `.env` at production to run migrations; let the deploy run them.

## Common Pitfalls

- **Adding a resource and pushing.** See [Adding a Resource](#adding-a-resource): deploy locally and commit the lock first.
- **Runtime secrets as build variables.** Build variables never reach the Worker. Set `SITE_URL` and the rest with `void secret put`.
- **Non-production branch builds on.** Branch code would build against production. Keep them off.
- **Connecting a second Worker to this repository** for staging. It deploys with production's resource IDs; see [Staging and Previews](./overview#staging-and-previews).
- **A gradual rollout left open in Cloudflare.** Void won't flatten it. Finish or cancel it in the dashboard, then retry the build.

---

**Next:** [Troubleshooting →](./troubleshooting)
