Deployment Setup

Initial Admin
Workflow Overview

VK deploys as an Astro server app on Cloudflare Workers. Keep committed runtime config in Workers bindings and wrangler.jsonc vars. Keep local secret values in .dev.vars, and set deployed secret values with Wrangler secrets. See Configuration Guide for the separation of concerns between src/config, wrangler.jsonc, .dev.vars, and Wrangler secrets.

Preflight

Run the same verification command locally and in CI:

npm run verify

This runs type checking, linting, tests, and the production build.

Build directly when investigating adapter or bundling issues:

npm run build

Runtime Variables

Use wrangler.jsonc as the committed source of truth for non-secret app-level Worker variables:

{
  "vars": {
    "EMAIL_PROVIDER": "console",
    "BETTER_AUTH_URL": "https://example.com",
    "EMAIL_FROM": "VK <noreply@example.com>",
    "MAILGUN_DOMAIN": "mg.example.com",
  },
}

Typical non-secret runtime values are EMAIL_PROVIDER, EMAIL_FROM, EMAIL_REPLY_TO, BETTER_AUTH_URL, and MAILGUN_DOMAIN. App identity and route policy live in src/config. If you use named Wrangler environments, define the vars block inside each environment because Wrangler does not inherit vars from the top level.

Local Secrets

Copy the local example and fill in values:

cp .dev.vars.example .dev.vars

Use .dev.vars for local-only secrets such as BETTER_AUTH_SECRET, email API keys, and local callback URLs. You can also use it for local-only overrides of non-secret values from wrangler.jsonc. Do not commit .dev.vars.

Deployed Secrets

Set deployed secrets with Wrangler. Better Auth always needs a stable secret:

npx wrangler secret put BETTER_AUTH_SECRET

Set provider-specific email secrets only when the selected provider needs them:

npx wrangler secret put RESEND_API_KEY
npx wrangler secret put MAILGUN_API_KEY

Wrangler prompts for each value. Do not pass secret values as command arguments, print them in shell history, or commit them to wrangler.jsonc.

If you deploy with a named Wrangler environment, pass the environment name when setting the secret:

npx wrangler secret put BETTER_AUTH_SECRET --env production

List configured secret names when auditing an environment:

npx wrangler secret list
npx wrangler secret list --env production

Deployment Checklist

  1. Create the D1 database with wrangler d1 create vk.
  2. Update the D1 database_id in wrangler.jsonc.
  3. Configure non-secret app values in wrangler.jsonc.
  4. Configure BETTER_AUTH_SECRET and any provider credentials with wrangler secret put.
  5. Run npm run db:migrate:remote.
  6. Optionally create a verified user with the admin role with npm run init:admin -- --remote.
  7. Run npm run verify.
  8. Deploy with the project Cloudflare workflow.