Deployment

Vercel auto-detects Next.js. The shipped vercel.json files set workspace-aware install and build commands.

{
  "buildCommand": "cd ../.. && pnpm build --filter=@syntaxkit/web",
  "installCommand": "pnpm install",
  "framework": "nextjs"
}

{
  "buildCommand": "cd ../.. && pnpm build --filter=@syntaxkit/docs",
  "installCommand": "pnpm install",
  "framework": "nextjs"
}

Two Fly apps, one per Next.js app, both built from apps/Dockerfile. The web app's release hook runs migrations.

fly launch --copy-config --no-deploy

[deploy]
  release_command = '/bin/sh /release/scripts/deploy/migrate-database.sh'

fly launch --copy-config --no-deploy -c apps/docs/fly.toml

fly secrets set \
  DATABASE_URL="postgresql://..." \
  BETTER_AUTH_SECRET="$(openssl rand -base64 32)" \
  UPSTASH_REDIS_REST_URL="https://..." \
  UPSTASH_REDIS_REST_TOKEN="..." \
  EMAIL_DELIVERY_MODE="resend" \
  RESEND_API_KEY="re_..." \
  EMAIL_FROM="App <noreply@example.com>" \
  --app your-app-web

fly deploy                          # web (./fly.toml)
fly deploy -c apps/docs/fly.toml    # docs

Render reads render.yaml at the repo root and provisions both services. Migrations run as preDeployCommand on every release.

Root docker-compose.yml defines three services: one-shot migrator (tools profile), web, and docs. You bring Postgres.

cp .env.docker.example .env
docker compose build
docker compose run --rm migrator
docker compose up -d

migrator is on the tools profile, so up does not run it. Invoke it before each release. Healthchecks use /api/health for web and / for docs (same readiness idea as Fly and Render). Web has a 30-second stop_grace_period so Next.js after() callbacks can finish before SIGTERM.

Pre-built images on GHCR. .github/workflows/docker.yml publishes on every push to main and every semver tag:

• ghcr.io/<owner>/<repo>/web:latest (also :<sha>, :<branch>, :<version>)
• ghcr.io/<owner>/<repo>/docs:latest

Use these on Kubernetes, Coolify, Dokku, Nomad, or any Docker host. Set runtime env, then migrate with the migrator stage (docker build --target migrator ...) or scripts/deploy/migrate-database.sh in a job that has Prisma and packages/database.

NEXT_PUBLIC_* values are baked at image build time from CI variables. Empty Actions variables produce an image with empty public URLs. Changing a public var means republishing the image.

The kit ships no netlify.toml. Netlify, Railway, Heroku, Coolify, and similar hosts follow the Vercel shape:

• Build with pnpm build --filter=@syntaxkit/web (or --filter=@syntaxkit/docs) after pnpm install.
• Apply the same build-time vs runtime env split.
• Run migrations from CI before deploy. scripts/deploy/migrate-database.sh works on any Linux host with Node and the packages/database workspace.

Each host has its own config surface (netlify.toml, dashboard settings, and so on). Use that host's Next.js guide for the exact syntax.

Generate with openssl rand -base64 32 and set the same value on every replica. Without a shared key, a server-action payload signed on replica A fails to decrypt on replica B. Render's blueprint generates this for you.

Set TRUST_PROXY_HEADERS=true and TRUSTED_PROXY_IP_HEADERS to the header your proxy sets (often x-forwarded-for). Better Auth uses these for real client IPs in rate limits and audit logs.

Fly's web fly.toml already sets TRUST_PROXY_HEADERS=true. Set TRUSTED_PROXY_IP_HEADERS via secrets if you need IP-based limits. Render's blueprint sets both. On Docker Compose, set them only when a trusted proxy in front overwrites those headers. Do not enable them on a directly exposed app; clients can spoof the headers.

Only when Better Auth must use a different origin from NEXT_PUBLIC_APP_URL. Most deploys leave it unset so Better Auth derives the base URL from the public app URL.