Strapi high availability and scaling

Putting two Strapi instances behind a load balancer exposes state that a single node hides. Three failure modes appear first: uploads written to one node's local disk that other nodes cannot read, content served from a cache that only one node has warmed, and instances running different builds during a rolling deploy. Each one passes a quick test on a single server and then fails intermittently once traffic is split, which is why teams often find them after go-live rather than before.

Uploads on local disk. By default, Strapi's upload provider stores media on the local filesystem of the instance that handled the request. A file uploaded through node A is recorded in the database, but node B has no copy, so the editor sees a broken image on some page loads and a working one on others, depending on which node answers. API consumers see the same thing as a missing or 404 asset URL. The fix belongs in the architecture: an external upload provider that every node writes to and reads from. Confirm with your Strapi 5 minor version which upload provider options are supported and how the default provider is configured.

Caches warmed on one node. Any in-process cache, such as response caching in a custom controller, a memoized service or a CDN rule that varies by host header, lives on one node. A content update may invalidate the cache on the node that handled the edit and leave the others serving the old entry. Editors then report that a published change is visible in the admin preview but not on the site for some visitors. To reproduce this in staging, publish a change, then send repeated requests through the load balancer and compare responses, checking whether the stale version appears on some requests only.

Mixed builds during rolling deploys. A rolling deploy briefly runs the old and new build side by side. If the new build changed a content type, a component or a API response shape, consumers may receive two formats within minutes. Schema changes also need care because Strapi applies schema updates on startup, so the first node to boot can alter the database that the other node still expects. In staging, run a deploy while a scripted client polls the API and record every distinct response shape and build identifier returned.

The safe order for a schema change across several Strapi nodes is to version the change first, migrate the database once, and only then let new instances take traffic. Content type definitions live in the project code as schema files, so every node that serves requests should be built from the same commit. Keep those files in version control and treat any change to a content type as a code change that goes through the same review and release path as the rest of the application. If a node is running a build with a different schema than its peers, editors and API consumers can see inconsistent fields, and the problem is hard to trace later.

Run database migrations once, from a single controlled job, before any new instance receives traffic. When every node attempts to migrate on boot, they compete for the same tables and locks, and one failure can leave the database half changed while some nodes already run the new code. A dedicated deployment step that runs the migration, checks that it succeeded, and only then starts or releases the new application instances gives you one place to watch, one log to read and one clear go or no-go decision. Your team should confirm with Strapi's documentation for your exact version how migrations are triggered and whether any of them run automatically on first start.

During the rollout window, old and new builds will run side by side, so both must read and write the same database safely. Plan for this before writing the change. Prefer additive changes first, such as adding an optional field, and defer removals or renames to a later release once no node depends on the old shape. Test your front ends against both response shapes, since a schema change can also alter what the API returns. If your project is moving between major Strapi versions, the compatibility options described in the v4 to v5 migration guidance, including the response format header, are relevant here, and you should confirm their current behavior in the version you run.

Decide early how editors are prevented from changing the schema on production nodes. In Strapi, the Content-Type Builder is part of the admin panel, so a production admin who can edit content types can alter the schema outside your release process. Options include disabling schema editing in production configuration, restricting the admin role that can reach the builder, or routing all schema work through a staging environment and version control. Confirm with your team which control your Strapi version supports and test that an editor cannot change a content type on a production node.

A failed migration cannot be rolled back by reversing the code. Strapi's documentation says downgrading is not supported, so the recovery path is a restore from a backup that has been tested. Before every schema release, confirm that a current database backup exists, that someone has restored it into a non-production environment, and that the restore time fits your tolerance for downtime. Document who approves a restore, which steps the runbook contains and how the application is returned to the previous build. Ask your implementation partner or your Strapi version's documentation for the exact restore procedure before the first production change, because the steps depend on the version and database you run.

A Strapi cluster is only safe to run once someone has watched it survive the failures it was built for. Write the test plan before anyone touches production, and agree the pass criteria with the people who own the content and the uptime commitments. Start with the basic behaviors. Create an entry through one instance and read it through another, which shows that both nodes share one database and hold no local state. Upload a media file through one node and confirm it loads from every node, which only holds when media is stored in an external upload provider rather than on local disk. Run a rolling deploy while a steady stream of read requests continues, and confirm that traffic keeps receiving answers throughout. Finally, stop one instance, confirm the load balancer removes it from rotation through its health checks, then confirm it returns to rotation after restart.

The database failover rehearsal needs the most care, because the result depends on your database platform and on how Strapi's connection handling behaves under that platform. Strapi 5 supports PostgreSQL 14 or later, MySQL 8.0 or later and MariaDB 10.3 or later, but the failover mechanism differs between a managed service, a self-managed replica pair and a cluster proxy. Confirm with your database vendor or operations team how failover is triggered, how long clients should expect to be disconnected, and whether the endpoint name changes. During the rehearsal, record which requests fail, whether the application's connection pool recovers without a restart, and whether requests succeed again on their own. The load balancer shapes the result too. Its health check path, check interval, unhealthy threshold and sticky session settings all determine what users see during the window, so document them before the test.

Schema changes need their own test on staging, because the database is shared by every node and a faulty change can break all of them at once. Copy a recent production backup into a staging environment that matches production's database engine and Strapi version, then apply the planned content type change through the same deploy path you will use in production. Strapi 5 runs data migration scripts on first start, so check which instance performs the migration when several start together, and confirm the result on each node. Then run a restore drill: take a backup, restore it into a clean environment, boot Strapi against it and compare record counts and sampled entries with the source. Strapi does not support downgrading once data has moved to Strapi 5, so the backup taken before the change is your only rollback path. Keep that backup and the restore steps in the runbook.