Schero D.

Running Strapi 5 plugins on several instances

Schero D. ·

Two Railway replicas with four pm2 workers each are eight Strapi processes that share one database and no memory. A plugin that counts, locks or schedules in memory does all of that eight times. These are the patterns the plugins on this site use instead, with the numbers their tests measured.

Keep shared state in the database

Every value that two processes must agree on lives in the Strapi database: rate-limit counters, quotas, revocations, leases and outbox rows. Magic Link, Magic Mail, Magic Session Manager and Magic MessageGate therefore need no sticky sessions, and Redis is optional. Requests can land on any process.

Write conditionally instead of reading first

A read followed by a write loses updates when two processes run it at once. The plugins write in one statement and let the database decide. Magic Mail reserves quota with one UPDATE ... WHERE count < limit per send and counts opens with SET count = count + 1. Magic Link accepts a login link or code with a conditional update, so it is accepted exactly once across all processes.

Lock only where a read-modify-write cannot be avoided

Magic Link writes its plugin-store keys (JWT blocklist, IP bans, settings) under a cluster-wide lock: pg_advisory_xact_lock on PostgreSQL, GET_LOCK on MySQL and the write lock on SQLite. Hot paths stay lock-free. Up to version 6.1 every login appended to one shared session list under that lock. Version 6.2 stores one row per JWT instead. With 4 processes on PostgreSQL 16 and 100 simultaneous logins while the old lock was held for 5 seconds, 6.1 needed 5.5 s and 6.2 needed 0.38 s.

Run background jobs under a lease

Each process keeps its timers, but every run of a cleanup, quota refresh or migration takes a lease in the database first. One process does the work per interval; if it dies, another takes over on its next tick. Magic Mail and Magic Link both work this way.

Claim outbox rows so each message is sent once

Magic MessageGate claims outbox messages with FOR UPDATE SKIP LOCKED on PostgreSQL and MySQL 8, and with a conditional update on SQLite. In its test, 8 processes on one PostgreSQL database behind a round-robin balancer sent 500 messages with 0 duplicates. A send whose outcome is unknown becomes uncertain and waits for an admin instead of being retried into a duplicate.

Accept short, documented windows for caches

Some reads are cached per process and the delay is written down. In Magic Link a revocation reaches the other processes within 2 seconds and changed rate-limit settings within 5 seconds. Magic Mail re-checks its settings row about once a second.

Give every process the same secrets

A process with a different JWT_SECRET rejects tokens the others issued, and a different encryption key cannot read stored credentials. Magic Mail logs short fingerprints of its secrets at startup, so two instances that print different values have different secrets.

Pass the real client IP through the proxy

Behind Railway's edge or any load balancer, set proxy: { koa: true, maxIpsCount: 1 } in config/server.js. Without it every unauthenticated caller shares the proxy's address and therefore one rate-limit quota.

Start one replica on schema changes

Strapi creates and alters tables when it starts, and that step is not coordinated between processes. On an empty database or after an update that adds columns, all but one process can stop with already exists errors and restart. Deploy such an update with one replica and scale up afterwards.

Socket.IO needs an adapter

WebSocket connections are held by one process. plugin-io makes several processes act as one Socket.IO server with the Postgres adapter (LISTEN/NOTIFY) or the Redis adapter, and clients connect WebSocket-only because Railway and pm2 have no sticky sessions. Each process opens its own connection pool: 8 processes with Strapi's default pool of 10 need 96 PostgreSQL connections, so set pool.max to about 6 to stay under a limit of 100.

Sources