Deploy & operate

Create the Cloudflare resources, migrate, set secrets, deploy and create the first admin.

On this page

This page walks through a first deploy of a kitcms app to Cloudflare Workers and the things to check afterwards.

A kitcms app deploys with wrangler deploy, like any SvelteKit app on the Cloudflare adapter. It needs the Workers Paid plan and wrangler login.

1. Create the D1 database and R2 bucket

pnpm create kitcms@latest --create-resources can do this for you. Otherwise create them with wrangler:

pnpm exec wrangler d1 create my-site
pnpm exec wrangler r2 bucket create my-site

wrangler d1 create prints a database_id. Put it in wrangler.jsonc, together with the names:

wrangler.jsonc
{
	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "my-site",
			"database_id": "00000000-0000-0000-0000-000000000000",
			"migrations_dir": "migrations"
		}
	],
	"r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-site" }]
}
  • Keep the binding names DB and BUCKET, or set bindings in kitcms.config.ts to your names.
  • Keep migrations_dir as migrations. That is where kitcms migrate:create writes. pnpm exec kitcms info warns if it differs.

You can commit database_id: it is an identifier, not a secret. Do not commit an account_id. Wrangler reads your account from wrangler login or the CLOUDFLARE_ACCOUNT_ID variable.

2. Apply the migrations

Migrations are plain SQL files. Apply them to the production database:

pnpm exec kitcms migrate --remote

--remote runs wrangler d1 migrations apply against your real database. Without it, kitcms targets the local D1. The scaffolded package.json has a db:migrate script (kitcms migrate), so pnpm db:migrate --remote works too. Check what has been applied with kitcms migrate:status --remote.

3. Set secrets

pnpm exec wrangler secret put BETTER_AUTH_SECRET

Wrangler asks for the value. Use a random string of at least 32 characters, for example the output of openssl rand -base64 32. It signs sessions, and the Worker throws on sign-in without it. Keep it secret, and keep it the same across deploys: changing it signs everyone out.

Locally, the secret lives in .dev.vars, which the scaffolder creates and .gitignore excludes.

Optionally set BETTER_AUTH_URL to your public origin, for example https://example.com. See Auth and users.

4. Build and deploy

pnpm run deploy

The deploy script runs pnpm build, then wrangler deploy (wrangler.jsonc points main at the build output). Wrangler prints the workers.dev URL.

5. Seed content (optional)

If you have a seed file, such as the website template's src/kitcms.seed.ts, run it against the production database:

pnpm exec kitcms seed --remote

The seed is idempotent: it creates only what is missing and never overwrites edits. To reach the real database and bucket, the D1 entry in wrangler.jsonc needs "remote": true. Add it temporarily, then remove it, or the seed refuses to run:

{ "binding": "DB", "database_name": "my-site", "database_id": "...", "migrations_dir": "migrations", "remote": true }

The seed runs with overrideAccess, so it can create documents in locked collections. See Orderable and locked.

6. Create the first admin

Create your admin account right after the first deploy. Until a user exists, /admin/create-first-user is open to anyone.

Open /admin on your deployed URL and fill in the form. Once one user exists, that page redirects to sign-in and creates nothing. See Auth and users.

Do this before you attach a custom domain or share the URL.

After the first deploy

Topic Page
Serve the site on your own domain Custom domains
Cache anonymous reads at the edge Edge cache
Faster reads far from your database Read replication and Smart Placement
Move to a newer kitcms Upgrading
Provision a site from a script (hosting platforms) System setup
Pause a site's writes Read-only mode

Deploying changes

For each release of your app:

  1. If the schema changed: pnpm db:generate <name>, review the SQL and commit it.
  2. pnpm exec kitcms migrate --remote
  3. pnpm run deploy

Migrate first. The old code keeps working against the added columns for the short time before the new code goes live. For breaking schema changes such as a renamed field, plan a two-step change: add the new field and deploy, copy the data, then drop the old one.

Edit this page on GitHub