# Deploying a host app

URL: https://kywi-docs-production.up.railway.app/operating/deploying-a-host-app
Type: docPage

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.

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 service environment, in full

The auth secret's exact refusal, and what rotating it costs, is [AUTH_SECRET and production fail-fast](/operating/authsecret-and-production-fail-fast/). The consent mirror is [Consent policy: the startup throw and the env mirror](/operating/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.json

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](/operating/running-migrations-against-a-live-database/) and [Why drizzle-kit push is banned before deploy](/operating/why-drizzle-kit-push-is-banned-before-deploy/).

## The scheduler and webhook retries run in every process

## Before 0.25.0, neither worker starts on its own

On earlier versions the runtime starts neither worker: scheduled publishes, expiries and due changesets wait for a cron call to the admin trigger below, and a failed webhook delivery is re-sent only if the host app starts the retry worker itself.

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.

export default defineKywiConfig({ // … scheduler: { enabled: false }, // or intervalSeconds: 300 webhooks: { retryIntervalSeconds: 0 }, // 0 stops the retry worker })

## kywi.config.ts — turn either worker off

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.

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}}

## every minute, from cron

## Only the retry worker re-sends a failed delivery

The retry route, and the admin's Retry now button that calls it, only marks a failed delivery due; the in-process worker is what sends it, so setting `webhooks.retryIntervalSeconds: 0` on every process means a failed delivery is never re-sent. A first delivery that fails — an HTTP error response, a network error or a timeout — is stored `failed` with a next-retry time, and the worker backs off from there ([Webhooks](/integrating/webhooks/)).

## 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](/operating/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.
