Magento zero downtime deployment: how to run the Magento 2 deploy process without maintenance mode

Out of the box, a Magento 2 deploy is a maintenance page. The standard sequence puts the store into maintenance mode, pulls code, runs composer install, compiles dependency injection, deploys static content, runs setup:upgrade and flushes cache. On a real catalogue that is anywhere from two minutes to the better part of an hour, and on a multi server setup it is worse. For a store doing meaningful revenue, that window is the whole problem.

The good news is that most of that sequence does not need the store to be down at all. It only looks that way because the default process does the work in the live directory.

Why does Magento 2 need maintenance mode?

Magento needs maintenance mode because the default deploy modifies the running installation in place. While composer install is swapping vendor files and setup:static-content:deploy is regenerating pub/static, requests hitting the store can load a half updated codebase. Maintenance mode is protection against serving that inconsistent state, not a requirement of the framework itself.

Once you stop deploying in place, most of the reason for the maintenance page disappears. That is exactly what Adobe's pipeline deployment model, introduced in Magento 2.2, is built around.

The build phase and the deploy phase

Pipeline deployment splits the work into two phases with very different risk profiles.

The build phase produces a complete, ready to run copy of the application without touching the live site or the database. It runs in a new release directory (or on a separate build machine entirely):

• composer install --no-dev --optimize-autoloader
• bin/magento setup:di:compile
• bin/magento setup:static-content:deploy -f <locales>

None of that reads or writes the production database, and none of it is visible to customers. It is also the slow part, which is the useful bit: the expensive minutes are spent while the old release is still happily serving traffic.

The deploy phase is what actually changes the live system:

• bin/magento setup:upgrade --keep-generated applies schema and data changes
• bin/magento app:config:import imports configuration from app/etc/config.php
• the symlink switch, then cache flush and a PHP FPM reload

The --keep-generated flag matters. Without it, setup:upgrade will discard the generated code and static content you just built, and you are back to compiling on a live server.

The release directory and symlink model

The structure is the same one used by zero downtime deployment tools generally, and it is worth setting up even if you script it yourself:

/var/www/store/
  releases/
    20260731093000/
    20260730141500/
  shared/
    app/etc/env.php
    pub/media/
    var/log/
  current -> releases/20260731093000

Your web server document root points at current/pub. A deploy builds into a new folder under releases/, symlinks the shared paths into it, and only at the end repoints current. Because repointing a symlink is a single filesystem operation, there is no moment where some requests get old code and others get new code.

Three things must be shared rather than rebuilt: app/etc/env.php (the environment specific config), pub/media (customer and catalogue uploads, which must never be tied to a release), and var/log so history survives. Everything else should be produced by the build.

How do you know if a deploy can be zero downtime?

Run bin/magento setup:db:status before you deploy. It compares the schema declared by your modules against the live database and returns exit code 0 when everything is up to date, 1 when module versions and the database disagree, and 2 when setup:upgrade is required. Exit code 0 means this release can go out with no maintenance window at all.

That single check is the honest dividing line, and it is worth wiring into the pipeline as a gate rather than running by hand:

Schema changes are the real constraint

Magento 2.3 and later use declarative schema, so db_schema.xml describes the target state and setup:upgrade works out the difference. That makes schema changes easier to write and does nothing to make them safe to deploy, because the problem is not the migration mechanism. The problem is that for a few seconds, code from the old release and code from the new release are both talking to the same database.

The way out is the expand and contract pattern: add the new column in one release while old code ignores it, write to both old and new in the next, backfill, then remove the old column in a later release once nothing reads it. It takes three or four deploys instead of one, which is the price of never taking the store down. The mechanics generalise across frameworks and are worked through in detail in our guide to zero downtime database migrations.

Do not forget opcache

This is the step that catches people out on their first symlink based Magento deploy. PHP's opcode cache keys entries by resolved file path. After you repoint current, PHP FPM can keep serving the compiled bytecode from the previous release, so the switch appears to do nothing, or worse, mixes old and new classes.

Reload PHP FPM (systemctl reload php8.3-fpm or equivalent) as the step immediately after the symlink flip. A reload is graceful: in flight requests finish on the old workers while new ones start against the new release. Do not use a hard restart, which drops connections and undoes the point of the exercise.

Blue green for multi server Magento

The symlink approach works well on a single application server. Once you are running several behind a load balancer, the release has to land on all of them and the switch has to be coordinated, otherwise nodes serve different versions for as long as the rollout takes.

Two options. Roll the release out node by node, draining each from the load balancer first, which is simple but means mixed versions during the rollout and therefore demands backward compatible database changes. Or run two full environments and cut the load balancer across in one move, which avoids mixed versions and costs you a second set of servers. The tradeoffs are compared in blue green versus rolling deployment.

Verify more than the HTTP status

A health check that only asks for a 200 on the homepage will happily approve a release where the cart page renders and the add to cart button silently does nothing. For a store, check something transactional: add a product to a cart, hit the checkout step, confirm the price is right. Those are also the pages worth auditing for copy and layout problems separately from deploys, since a checkout can be technically healthy and still leak revenue.

What a full Magento deploy pipeline looks like

1. Run bin/magento setup:db:status and record the exit code.
2. Create a new release directory and clone the target commit into it.
3. Symlink shared paths: app/etc/env.php, pub/media, var/log.
4. Build: composer install --no-dev --optimize-autoloader, then setup:di:compile, then setup:static-content:deploy for your locales.
5. If step 1 returned 0, skip ahead. If not, decide: backward compatible patch, or an announced maintenance window.
6. Run bin/magento setup:upgrade --keep-generated.
7. Run bin/magento app:config:import if configuration changed.
8. Health check the new release directly, including one transactional path.
9. Repoint current to the new release.
10. Reload PHP FPM, flush cache, and warm the pages that matter.
11. Keep the previous release on disk. That is your rollback.

Steps 2 through 11 are the same shape for every PHP application, which is why deployment management software exists rather than every team maintaining its own version of this script. DeployManage provisions the server, runs this release model with health gated switching, and keeps previous releases ready so a rollback is a symlink repoint rather than an emergency rebuild.

Rolling back a Magento release

Code rollback is easy in this model: point current at the previous release directory and reload PHP FPM. Dependencies and static content are already built there, so it takes seconds.

The database is the part that does not roll back. If the release you are reverting applied a schema change, the older code has to be able to run against the newer schema, which is precisely what expand and contract buys you. Teams that skip that discipline discover during an incident that their rollback path does not actually exist.