Star
Run it

Deployment

In production you supply Postgres, run migrations as a deploy step, and set three things. The development conveniences (starting Postgres, migrating on boot, picking ports) turn themselves off.

The minimum

import { FeaturekitServer } from "featurekit-server";
      
      const server = new FeaturekitServer({
        nodeEnv: "production",
        host: "0.0.0.0",
        port: 3000,
        databaseUrl: process.env.DATABASE_URL,
        secureModeSecret: process.env.SECURE_MODE_SECRET,        // once you have client keys
        corsAllowedOrigins: ["https://app.acme.com"],            // the browsers that call the client tier
      });
      
      await server.start();
      process.on("SIGTERM", () => server.stop());

Production fails loudly, and lists every missing setting at once, rather than starting against a laptop default. Everything else is in configuration.

Migrations

Run them once, as a deploy step, never inside booting nodes. Ten nodes migrating at once take the same locks at the same moment, during the deploy, while traffic shifts.

import { migrate, migrationStatus } from "featurekit-server/migrate";
      
      await migrate();                                   // reads DATABASE_URL and DATABASE_SCHEMA
      const { applied, partitionRunwayDays } = await migrationStatus();
  • It takes a Postgres advisory lock, so two runs at once are safe: the second waits and finds nothing to do.
  • Migrations only add. Columns are never dropped in the release that stops using them, so old code runs on the new schema for the length of a rollout, and rolling code back is always safe.
  • The order for a release: migrate → deploy new nodes → drain old ones.

Docker

The repository ships a multi-stage Dockerfile: Node 22 Alpine, production dependencies only, runs as node, not root, with node as PID 1 so SIGTERM reaches the graceful shutdown.

docker build -t featurekit .
      docker run --rm -e DATABASE_URL=postgres://… featurekit node scripts/migrate.mjs   # the deploy step
      docker run -p 3000:3000 -e DATABASE_URL=postgres://… -e SECURE_MODE_SECRET=… featurekit

Or embed FeaturekitServer in a service you already deploy; it's the same code.

Rolling deploys

On SIGTERM, shutdown happens in an order that keeps clients calm:

  1. /ready starts failing, so the load balancer stops sending work before the socket closes.
  2. New connections are refused.
  3. Every open stream gets a reconnect event with its own random delay, so thousands of SDKs return as a ramp, not a stampede.
  4. In-flight requests finish, for up to SHUTDOWN_GRACE_MS (10 seconds).
  5. Sockets and Postgres close. A second SIGTERM exits at once.

Give your orchestrator a longer grace period than that: on Kubernetes, terminationGracePeriodSeconds: 30.

ProbePathChecks
Liveness/liveNothing external, so a database blip doesn't restart every node.
Readiness/readyPostgres reachable, the right schema, migrated, and analytics partitions ahead.

Behind a pooler

Nodes hear about each other's changes through Postgres LISTEN, which transaction-mode pgbouncer can't carry. Set DATABASE_LISTEN_URL to a direct Postgres address; every other query keeps going through DATABASE_URL. Set the role's search_path too: ALTER ROLE featurekit SET search_path = featurekit;

Backup and recovery

Postgres is the only thing to back up. Point-in-time recovery is what matters: the realistic disaster is a bad bulk change, and "restore to 14:02" is its fix.

  • Targets: RPO 5 minutes with continuous WAL archiving, RTO 1 hour.
  • The cache tables don't need backing up. snapshot_cache, snapshot_patches, client_connections and compile_locks are unlogged and rebuild themselves.
  • Rehearse it, quarterly, against a scratch instance.
After a point-in-time restore

The restore moves snapshot versions backwards, and SDKs ignore anything older than what they hold, so the fleet stays frozen on its last snapshot. Bump every version past what was served, then trigger a recompile with any change:

UPDATE environments SET snapshot_version = snapshot_version + 10000;

Capacity

ResourceDefault ceilingSetting
Server streams per node10,000, then SDKs pollMAX_STREAM_CONNECTIONS
Client streams per node50,000MAX_CLIENT_CONNECTIONS
Members read per segment per compile2,000,000SEGMENT_MEMBER_CEILING
Buffered analytics rows100,000, oldest droppedEVENT_BUFFER_MAX
Postgres connections per node10DB_MAX_CONNECTIONS

Measured on a developer laptop, Node 22, loopback, so read these as relative, not as fleet planning:

Scenariop50p99
Compile 1,000 flags (0.4 MB snapshot)5.5ms9.2ms
Compile 10,000 flags (3.9 MB snapshot)59.8ms89.1ms
Fan-out, 2,000 client connections × 20 flags47.6ms56.9ms
Open 1,000 SSE streams4.1ms6.5ms

Each SSE connection costs about 5.4 KB, so 10,000 server streams is about 54 MB. Not yet measured: multi-hour soak, real network and TLS, 100,000+ connections. Don't size a fleet from this table alone.