Deployment

NotifKit ships as a library, not an image. You containerise your service — the one that constructs NotifkitServer — and give it a Postgres and a Redis. This page is that Dockerfile, a compose file to run it against, and the two mistakes that bite on the second replica.

What you are building

The smallest correct production deployment is three containers. NotifKit will not start in production without the middle two — it throws at boot rather than silently degrading:

The service

Read both URLs from the environment and pass them in. Nothing else about server.ts changes between development and production except nodeEnv:

import { NotifkitServer } from "notifkit";
import { ResendTransport } from "@notifkit/provider-resend";

const server = new NotifkitServer({
  services: ["all"],
  port: Number(process.env.PORT ?? 3000),
  nodeEnv: "production",

  // Required in production — startup throws without them.
  databaseUrl: process.env.DATABASE_URL,
  redisUrl: process.env.REDIS_URL,

  // Transports must be registered on every deployment that runs `delivery`.
  providers: [new ResendTransport({ apiKey: process.env.RESEND_KEY!, from: "hi@acme.com" })],
});

await server.start();

Dockerfile

Multi-stage: build with dev dependencies, ship without them. NotifKit targets Node 22 and is ESM-only, so the base image is not negotiable below 22.

# ── build ───────────────────────────────────────────────────────
FROM node:22-alpine AS build
WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# ── runtime ─────────────────────────────────────────────────────
FROM node:22-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production

# Production deps only. This still pulls in notifkit's `drizzle/`
# folder, which is where the migrations live — do not prune it.
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --from=build /app/dist ./dist

# Do not run as root.
USER node

EXPOSE 3000

# Exec form, so node is PID 1 and receives SIGTERM directly.
# NotifkitServer installs its own SIGTERM/SIGINT handlers and drains
# in-flight work before exiting.
CMD ["node", "dist/server.js"]

node_modules
dist
.git
.env
*.log
tests
coverage

Compose: everything in one process

Right for staging and for production up to the point where one service's load starts interfering with another's. services: ["all"] runs the API and all seven workers in the single container:

services:
  notifkit:
    build: .
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      PORT: "3000"
      # Required. The default is 127.0.0.1, which would accept connections from
      # inside this container only — the published port above would refuse them.
      HOST: 0.0.0.0
      LOG_LEVEL: info
      DATABASE_URL: postgres://notifkit:notifkit@postgres:5432/notifkit
      REDIS_URL: redis://redis:6379
      ADMIN_API_KEY: ${ADMIN_API_KEY:?set ADMIN_API_KEY}
      RESEND_KEY: ${RESEND_KEY}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    # Node 22 has global fetch, so no curl needed in the image.
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://localhost:3000/ready').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 40s
    # Above the 30s the delivery worker may need to drain.
    stop_grace_period: 45s
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: notifkit
      POSTGRES_PASSWORD: notifkit
      POSTGRES_DB: notifkit
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U notifkit"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    # Persistence on: in-flight messages and pending lists live here.
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  pgdata:
  redisdata:

docker compose up --build -d
docker compose logs -f notifkit

# Once it reports healthy, bootstrap a project exactly as in the quickstart:
curl -s -X POST http://localhost:3000/v1/projects \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"production"}'

Splitting the API from the workers

The services array is the only thing that differs between deployments. Point them at the same Postgres and Redis and they form one system — the API scales on request rate, the workers on stream depth. Both images are identical; only the command differs.

// One image, two roles, chosen at boot.
const ROLE = process.env.NOTIFKIT_ROLE ?? "all";

const services =
  ROLE === "api"     ? ["api"] as const
  : ROLE === "worker" ? ["enricher", "engine", "delivery", "scheduler",
                         "workflow", "events", "ai"] as const
  : ["all"] as const;

const server = new NotifkitServer({
  services: [...services],
  nodeEnv: "production",
  databaseUrl: process.env.DATABASE_URL,
  redisUrl: process.env.REDIS_URL,
  providers: [/* … */],

  // Only the api role owns migrations. See below.
  autoMigrate: ROLE !== "worker",
});

services:
  api:
    build: .
    environment:
      NOTIFKIT_ROLE: api
      NODE_ENV: production
      HOST: 0.0.0.0
      DATABASE_URL: postgres://notifkit:notifkit@postgres:5432/notifkit
      REDIS_URL: redis://redis:6379
      ADMIN_API_KEY: ${ADMIN_API_KEY:?set ADMIN_API_KEY}
    ports:
      - "3000:3000"
    depends_on:
      postgres: { condition: service_healthy }
      redis:    { condition: service_healthy }
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://localhost:3000/ready').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 15s
      start_period: 40s
    stop_grace_period: 45s

  worker:
    build: .
    environment:
      NOTIFKIT_ROLE: worker
      NODE_ENV: production
      DATABASE_URL: postgres://notifkit:notifkit@postgres:5432/notifkit
      REDIS_URL: redis://redis:6379
    depends_on:
      # Wait for the api to have migrated before consuming.
      api:
        condition: service_healthy
    deploy:
      replicas: 3
    # No HTTP server in this role — see the note below.
    stop_grace_period: 45s

Migrations and the second replica

autoMigrate defaults to true, and migrations run during server.start() before any service comes up. With one container that is exactly what you want. With three replicas booting at once, they race for the same schema lock.

Pick one owner and turn it off everywhere else:

For the multi-replica case, run migrations as a one-shot container that exits, and gate the rollout on it:

  migrate:
    build: .
    command: ["node", "dist/migrate.js"]
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://notifkit:notifkit@postgres:5432/notifkit
      REDIS_URL: redis://redis:6379
    depends_on:
      postgres: { condition: service_healthy }
    restart: "no"

// Starts nothing. Migrates, then exits — the whole point.
import { NotifkitServer } from "notifkit";

const server = new NotifkitServer({
  services: [],
  nodeEnv: "production",
  databaseUrl: process.env.DATABASE_URL,
  redisUrl: process.env.REDIS_URL,
  autoMigrate: true,
});

await server.start();
await server.stop();

Deploying on a PaaS

Railway, Render, Fly and Heroku all work, and they differ from the Compose setup above in three ways that matter: the platform supplies Postgres and Redis, it chooses the port, and it reaches your container over a network interface rather than loopback. Railway is the worked example below; the same three points carry to the others under different names.

What you actually deploy

Not this repository. NotifKit is a library — its package.json has no start script and its entry point is dist/index.mjs, so there is nothing here to boot. What you deploy is a small repository of your own holding the server.ts from above, a package.json that depends on notifkit and defines a start script, and nothing else:

{
  "type": "module",
  "engines": { "node": ">=22" },
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js"
  },
  "dependencies": {
    "notifkit": "^0.1.0",
    "@notifkit/provider-resend": "^0.1.0"
  }
}

A Dockerfile is optional here — Railway builds with Nixpacks when there is none, and the engines field above is what pins it to Node 22. If you add the Dockerfile from earlier, Railway uses that instead, and the note about keeping node_modules/notifkit/drizzle in the image applies exactly as it does under Compose.

The two dependencies

Add a Postgres and a Redis to the project, then reference them rather than pasting connection strings — Railway's ${{ Service.VAR }} syntax keeps them correct when a database is recreated:

Config as code

A railway.json at the repository root pins the parts that are easy to lose in a dashboard:

{
  "$schema": "https://railway.com/railway.schema.json",
  "deploy": {
    "startCommand": "npm start",
    "healthcheckPath": "/ready",
    "healthcheckTimeout": 300,
    "restartPolicyType": "ALWAYS",
    "drainingSeconds": 45
  }
}

drainingSeconds is the window between SIGTERM and SIGKILL — the same job stop_grace_period does under Compose, so keep it above the 30 seconds the delivery worker may need to drain.

/ready rather than /health: it reports on the dependencies, so a container that booted before Postgres was accepting connections fails the check and is replaced instead of serving errors. Both routes are unauthenticated and are served only where services includes api.

Migrations, without the race

The one-owner rule is the same here, and Railway gives you a cleaner way to honour it than a compose depends_on. Set autoMigrate: false on every service and hand migrations to preDeployCommand, which runs to completion before any new container starts taking traffic:

{
  "deploy": {
    "preDeployCommand": "node dist/migrate.js",
    "startCommand": "npm start"
  }
}

That is the same migrate.ts from the section above — the one that starts no services, migrates, and exits. Put it on the API service only; a worker service should never own schema.

Splitting into two services

The NOTIFKIT_ROLE pattern maps onto Railway directly: deploy the same repository twice in one project, set NOTIFKIT_ROLE=api on one and NOTIFKIT_ROLE=worker on the other, and point both at the same database references. Only the API service gets a public domain, a healthcheckPath, and HOST — a worker has no HTTP listener, so a healthcheck against it can only fail.

Environment

Before you call it done

• NODE_ENV=production, with DATABASE_URL and REDIS_URL set explicitly.
• Exec-form CMD, so SIGTERM reaches node.
• stop_grace_period above 30 seconds on every container that runs delivery.
• Exactly one deployment with autoMigrate enabled.
• Redis started with --appendonly yes, on a real volume.
• Transports registered on every deployment that runs delivery.
• USER node — the image does not run as root.
• Port 3000 not published to the public internet.

Operations picks up from here: what to alert on, how to read the metrics endpoint, and how to drain the dead-letter queue.