Skip to content

Deploying a host app

Four environment variables, a start command that survives SIGTERM, and a migrate before the push — NODE_ENV only arms one of the three boot checks.

The environment the boot requires

Three variables decide whether the process starts at all, and only one of them cares what NODE_ENV is set to. DATABASE_URL throws from the runtime's first statement when neither it nor db.url in the config provides a URL — in development or production alike, since nothing gates that check. KYWI_REQUIRE_CONSENT fails only when it disagrees with the config, which is the one an operator sets by accident — that check is also unconditional. AUTH_SECRET is the exception: it is asserted at module scope — in core's middleware and again in the generated kywi.config.ts — but only once NODE_ENV=production, so a production build or start breaks before any request arrives, and kywi migrate refuses for the same reason. Left at anything but production, the same missing or default secret is accepted with a console warning instead of refused. The fourth variable, NODE_ENV, arms only that one check — it has no effect on DATABASE_URL or KYWI_REQUIRE_CONSENT, which fail the boot regardless of environment.

the service environment, in fullbash
DATABASE_URL=postgresql://…            # internal/private host is fine
AUTH_SECRET=…                          # openssl rand -base64 32
NODE_ENV=production
# KYWI_REQUIRE_CONSENT — set it ONLY to mirror the config; unset means true

The auth secret's exact refusal, and what rotating it costs, is AUTH_SECRET and production fail-fast. The consent mirror is Consent policy: the startup throw and the env mirror. Leaving both the theme flag and the variable unset is a valid, agreeing configuration — this documentation's own deployment does exactly that.

A start command that survives SIGTERM

Set the start command explicitly to the Next binary: left to infer one, the platform runs pnpm start, and pnpm treats a child ended by SIGTERM as a failed script and exits 1, so every ordinary container rollover files a crash report for a replacement that is perfectly healthy.

railway.jsonjson
{
  "$schema": "https://railway.com/railway.schema.json",
  "deploy": {
    "startCommand": "node_modules/.bin/next start"
  }
}

Verify it by reading a retired deployment's log rather than the new one: it must end at Stopping Container, with no ELIFECYCLE Command failed. after it. Node then takes the signal directly and Next exits 0.

Migrate before you push, never during the deploy

Run the migration from an operator machine against the production database first, then push the commit that deploys the code. A migration wired as a pre-deploy hook can prompt, and a prompt in a non-TTY hangs forever — which blocks every later deploy until the hung one is canceled. See Running migrations against a live database and Why drizzle-kit push is banned before deploy.

The scheduler and webhook retries run in every process

Every app built on createKywiNextRuntime starts two in-process workers once its runtime initializes, each on a 60-second interval: the scheduler sweep (scheduled publishes, expiries, due changesets, expired featured flags and page-expiry notices) and the webhook retry worker. Nothing in your host app has to call them, but the runtime initializes lazily — in a scaffolded app, on the first request the process serves — and the first sweep runs one interval after that, so a replica that never receives a request never sweeps. Rows that have been waiting move on the first sweep after an upgrade from an older version — approved pages whose publish date has passed go live, published pages past their expiry archive, failed deliveries with a retry time are re-sent — so run the read-only checks in the release notes before you deploy. Both workers are safe across replicas: sweeps are conditional updates and a changeset publish or a retry claims its row first, so two processes on one database never apply the same change twice. The scheduler runs on Postgres only.

kywi.config.ts — turn either worker offts
export default defineKywiConfig({
  // …
  scheduler: { enabled: false },          // or intervalSeconds: 300
  webhooks: { retryIntervalSeconds: 0 },  // 0 stops the retry worker
})

Turn the in-process scheduler off on extra replicas, or when you would rather drive it from cron: the admin trigger runs the same sweep, is siteAdmin-gated and takes no site parameter, because the sweep is deployment-wide. notified counts the page-expiry emails it sent; they need a configured email provider — with none, or the console logger, they stay pending and go out once one is configured — and the trigger sends them with the handler’s own provider, so a cron call and an in-process sweep behave alike.

every minute, from cronbash
curl -sS -X POST https://your-host/api/v1/scheduler/run \
  -H "Authorization: Bearer kywi_…"
# {"data":{"published":0,"expired":0,"changesets":1,"featuredReset":0,"notified":0}}

What SITE_DOMAIN and an uploads volume are not

SITE_DOMAIN is read by nothing in the app — it is vestigial, and setting it does not affect host resolution, which comes from the config (Multi-site: the domain field and host-based resolution). And an uploads volume is per service: a second service pointed at the same database and the same commit does not share media with the first, because the local storage provider writes to its own container filesystem. Either mount a volume on every service that accepts uploads, or move media to object storage.