Deployer builds each Magento release in its own directory, then flips a single symlink to make it live, so a deploy is an atomic switch measured in milliseconds, not a window of downtime. The art is in what persists across releases, when maintenance mode is unavoidable, and how a rollback actually works.
Deployer is an SSH-based PHP deployment tool with a built-in Magento 2 recipe, and it is one of the most common ways teams ship Adobe Commerce without taking the store offline on every release. This guide covers the atomic release model, the shared paths that must survive a deploy, how to keep the slow build steps out of the downtime window, and the rollback reality. For the full engineering picture, see our Magento development services.
The atomic release model
The whole idea rests on a directory layout:
releases/holds one directory per deploy. Each new deploy builds into a fresh release folder.shared/holds data that must persist across releases: media, logs, and the environment config.currentis a symlink that points at the live release.
A deploy builds the new release completely, then switches the current symlink to point at it. That symlink swap is the cutover, and it is atomic: it takes milliseconds, and at no point is the site serving a half-built release. If anything in the build fails, current never moves, so visitors keep hitting the previous good release the whole time.
This is the structural difference from deploying into the live directory in place, where a composer install or an asset rebuild leaves the running site in an inconsistent state mid-deploy. Deployer’s own Magento 2 recipe documentation lists zero-downtime deployment and rollbacks as core features, and the Deployer source is worth reading to see the exact task order.
Shared paths: what must survive a deploy
If each deploy is a fresh directory, anything that must persist has to live in shared/ and be symlinked into the release. Get this list wrong and you lose uploaded media or break configuration on the first deploy. For Magento the essentials are:
| Path | Type | Why it is shared |
|---|---|---|
pub/media |
Directory | Uploaded product and CMS images, must not be lost |
var |
Directory | Logs, and caches you want to persist |
app/etc/env.php |
File | Environment config: DB, cache, session |
app/etc/config.php |
File | Module and scope config, often committed but sometimes shared |
The rule of thumb: code and generated artifacts belong in the release, and state belongs in shared/. Deployer lets you add extra shared paths with its additional-shared task rather than overriding the whole list, which is the safe way to extend it. Anything a customer uploaded, or any config that differs per environment, has to be shared, or it vanishes when the symlink moves to a new release that does not contain it.
Keep the slow steps out of the downtime window
A Magento deploy has several heavy steps, and the zero-downtime win comes from running the slow ones before the cutover, not during it. The heavy steps:
composer installfor dependencies.setup:di:compileto compile dependency injection.setup:static-content:deployto build frontend assets.
All three can and should run inside the new release directory while the old release is still serving traffic. None of them need the site offline. Magento’s own deployment improvements were aimed squarely at this: compilation, static asset generation, and the schema upgrade are what add downtime, so the goal is to move everything except the unavoidable database step out of the live window. Because this happens on a Hyva store too, the Tailwind build is part of the static-content step, which our guide to the Magento and Hyva release pipeline covers in the CI context. Dependency hygiene matters here as well, and our guide to Magento 2 Composer and dependency management explains why a reproducible build is the foundation of a safe deploy.
When maintenance mode is unavoidable
Zero downtime does not always mean zero maintenance mode. The one step that can require it is setup:upgrade, which applies database schema and data changes. If a release changes the schema, there is a moment where the new code expects the new schema. Deployer’s recipe handles this by enabling maintenance mode only when the release requires it, running the upgrade, then disabling it, and it exposes a zero-downtime option so deploys that do not touch the schema can skip maintenance mode entirely.
So the honest framing: deploys with no schema change are truly zero-downtime, a pure symlink swap. Deploys with a schema change have a short maintenance window scoped to just the setup:upgrade, not the whole build. Keeping schema migrations small and backward-compatible is how you keep that window short, and how you make rollbacks safe.
After the cutover, the cache is typically flushed, which means the new release starts cold. On a busy store, pair the deploy with a cache warm-up so the first visitors do not all hit a cold cache at once; our guide to full page cache warming on Magento and Hyva covers exactly that post-deploy step.
Rollbacks: fast for code, careful for data
The release model makes code rollback trivial: point the current symlink back at the previous release directory, and the old code is live again in milliseconds. Deployer keeps a configurable number of past releases for exactly this.
The complication is the database. A symlink rollback reverts the code, but it does not revert a schema change the deploy already applied. If the previous release’s code cannot run against the new schema, a code-only rollback is not enough and you may need to restore the database. This is why backward-compatible migrations matter so much: a migration that only adds, never removes or renames, lets the previous code keep running, which keeps rollback to a simple symlink flip. Magento’s setup:rollback can revert the filesystem, database, and media, but only against a backup you made beforehand, so a rollback plan is really a backup plan.
| Change type | Rollback method | Speed |
|---|---|---|
| Code only | Symlink back to previous release | Milliseconds |
| Backward-compatible schema | Symlink back, old code runs on new schema | Milliseconds |
| Breaking schema | Restore database from backup | Minutes to longer |
A sensible deploy checklist
Before you trust a Deployer setup on a production store, confirm these are true:
- Shared paths are complete. Deploy to a fresh server or a staging clone and confirm media, logs, and config survive a second deploy. A missing shared path only shows up on the deploy after the one that created the data.
- The build runs before the cutover. Composer, DI compile, and static content all complete in the new release directory while the old one serves traffic. If any of them run after the symlink swap, you have reintroduced downtime.
- Maintenance mode is conditional. It engages only for schema-changing releases, and only around
setup:upgrade, not the whole deploy. - Rollback is tested, not assumed. Actually roll back a release on staging and confirm the previous code runs. A rollback you have never exercised is a hope, not a plan.
- Backups exist before schema changes. A breaking migration without a database backup is a deploy with no undo.
MGT-Commerce’s Magento 2 zero-downtime deploy guide walks through the techniques in more depth, and the same principles apply whether you drive them with Deployer, a hosted tool, or your own scripts. The tool matters less than the discipline: build off the live path, swap atomically, and keep migrations reversible.
How deploys differ on other platforms
The atomic-symlink model is specific to self-hosted PHP applications. Managed platforms deploy very differently:
- Teams on Shopify development deploy themes and app code through Shopify’s own pipeline; there is no server to symlink.
- BigCommerce development and Shopware development each have their own deploy models, with Shopware self-hosted builds resembling Magento’s more than a SaaS platform does.
On self-hosted Magento and Adobe Commerce, you own the deploy, which means you own both the power of a true zero-downtime release and the responsibility to get shared paths and migrations right. The team at Bemeir builds and runs these pipelines on production stores, and our technology partners include the hosting and CI tooling the deploy runs on. For the frontend side of every release, see our Hyva development services.
FAQ
What makes a Deployer Magento deploy zero-downtime?
Deployer builds each release in its own directory while the current release keeps serving traffic, then switches a single current symlink to the new release. That symlink swap is atomic and takes milliseconds, so there is no window where the site serves a half-built release. Deploys without a schema change need no maintenance mode at all.
What paths should be shared in a Magento Deployer setup?
At minimum pub/media for uploaded images, var for logs, and the app/etc environment config such as env.php. The principle is that code and generated artifacts live in the release, while state and per-environment config live in the shared directory and are symlinked in. Add extra shared paths with Deployer’s additional-shared task rather than overriding the list.
Does zero-downtime deployment mean no maintenance mode ever?
No. Deploys that do not change the database schema are a pure symlink swap with no maintenance mode. Deploys that run setup:upgrade with a schema change need a short maintenance window scoped to that step. Keeping migrations small and backward-compatible keeps that window short.
How do I roll back a Magento deploy?
For a code-only or backward-compatible change, point the current symlink back at the previous release directory, which is instant. For a breaking schema change, a symlink rollback is not enough because the schema already changed, so you restore the database from a backup. Backward-compatible migrations are what keep rollback to a simple symlink flip.
Where do the slow build steps run?
composer install, setup:di:compile, and setup:static-content:deploy all run inside the new release directory before the cutover, while the old release still serves traffic. Only the database upgrade happens in the brief maintenance window, which is what keeps the live downtime minimal.
Ship without taking the store down
A good deploy is one nobody notices. Deployer’s atomic release model makes that the default for Magento, as long as shared paths, build order, and migrations are handled with care. Bemeir is the USA’s first Hyva Gold Partner and an Adobe Commerce shop that ships to production stores without downtime. Learn more about how we work and how we build deploy pipelines teams can trust.
