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:
/readystarts failing, so the load balancer stops sending work before the socket closes.- New connections are refused.
- Every open stream gets a
reconnectevent with its own random delay, so thousands of SDKs return as a ramp, not a stampede. - In-flight requests finish, for up to
SHUTDOWN_GRACE_MS(10 seconds). - Sockets and Postgres close. A second
SIGTERMexits at once.
Give your orchestrator a longer grace period than that: on Kubernetes, terminationGracePeriodSeconds: 30.
| Probe | Path | Checks |
|---|---|---|
| Liveness | /live | Nothing external, so a database blip doesn't restart every node. |
| Readiness | /ready | Postgres 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_connectionsandcompile_locksare unlogged and rebuild themselves. - Rehearse it, quarterly, against a scratch instance.
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
| Resource | Default ceiling | Setting |
|---|---|---|
| Server streams per node | 10,000, then SDKs poll | MAX_STREAM_CONNECTIONS |
| Client streams per node | 50,000 | MAX_CLIENT_CONNECTIONS |
| Members read per segment per compile | 2,000,000 | SEGMENT_MEMBER_CEILING |
| Buffered analytics rows | 100,000, oldest dropped | EVENT_BUFFER_MAX |
| Postgres connections per node | 10 | DB_MAX_CONNECTIONS |
Measured on a developer laptop, Node 22, loopback, so read these as relative, not as fleet planning:
| Scenario | p50 | p99 |
|---|---|---|
| Compile 1,000 flags (0.4 MB snapshot) | 5.5ms | 9.2ms |
| Compile 10,000 flags (3.9 MB snapshot) | 59.8ms | 89.1ms |
| Fan-out, 2,000 client connections × 20 flags | 47.6ms | 56.9ms |
| Open 1,000 SSE streams | 4.1ms | 6.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.