Zero-Downtime Deployment: Blue-Green, Rolling and Atomic Switchover

Situations that can cause 502s during a release, blue-green and gradual release options, database compatibility and a rollback plan.
Technical summary
Technology
Nginx, PHP-FPM, OPcache, MySQL/MariaDB, Kubernetes, HAProxy
Topic
Zero-downtime release strategies and rollback
Level
Intermediate–advanced
Prerequisites
  • Experience managing Linux servers and web servers
  • Basic CI/CD concepts
  • Knowledge of database schema changes
In this article7 sections

“We get a few seconds of 502s on every release” is an accepted routine in most teams. Yet those few seconds are made up of defined, fixable gaps: process restarts, files half-copied into the live directory and a schema that doesn’t match the code. In a web application, the way to close these gaps is to choose the right switchover strategy and plan database changes separately from code. Below we explain how we set up blue-green, rolling, canary and atomic release switchover for PHP/WordPress, Node.js and container-based applications in the field, along with schema changes and rollback.

Where does downtime at release come from?

When you look at the log after a release, you won’t find a single cause; several small gaps stack up. Get to know them one by one before choosing a strategy:

  • Process restart: restart stops and starts the process; requests in between are rejected or cut off. A graceful switch with reload (Nginx starting new workers and closing the old ones once they finish their work, PHP-FPM being reloaded with SIGUSR2) largely closes this gap. The mistake we see most often in the field is a restart line written into the deploy script out of habit.
  • Half-copied files: Writing over the live directory with rsync or FTP runs a mix of old and new files for a few seconds. If a new class file has arrived but the file that calls it hasn’t, you get a fatal error.
  • Old code in the cache: PHP OPcache can keep using old bytecode when the file path doesn’t change. Conversely, there’s a brief CPU spike while the cache is cleared.
  • Schema mismatch: The new code expects the new column, but the migration hasn’t run yet (or the reverse). On large tables, a locking ALTER TABLE can freeze the release for minutes.
  • Asset mismatch: A browser or CDN holding the old HTML in its cache requests an app.3f2a1.js file that no longer exists on the server and gets a 404.
  • Session and cache format: If the new version writes session data or cache keys in a different structure, users are logged out during the window when the two versions run together.

Each of these six items needs its own measure. No single tool solves them all.

Comparing strategies

The four approaches differ in resource needs and rollback speed. Three questions decide: how many application servers do you have, is there a load balancer in front, and can the application handle two versions running at the same time?

Strategy How it works Extra resources Rollback
Atomic symlink The new release is prepared in a separate directory, and the current link is switched in a single step None (a single server is enough) Seconds; the link is switched back to the old directory
Blue-green Two identical environments; traffic moves to the new environment all at once at the load balancer Twice production Very fast; traffic returns to the old environment
Rolling Servers or containers are updated one after another Low (one node’s capacity) Medium; rolling again in reverse
Canary The new release is first given a small share of traffic, and metrics are monitored Low to medium Fast; the canary weight is set to zero

On a single-server PHP site, an atomic symlink is usually enough and is the cheapest solution. If there are several application servers and a load balancer, rolling is the natural choice; but rolling and canary mean the old and new versions receive traffic at the same time for a while. In these two strategies, backward compatibility isn’t a preference. It’s a requirement. Blue-green minimizes the window in which the two versions overlap; in return you double the environment, and the question of the two environments sharing the same database comes to the table. Evaluate the options on the load balancer side together with a load-balanced, highly available web architecture.

The method tools such as Capistrano and Deployer have used for years is simple: each release is unpacked into its own directory under releases/; persistent data (uploads, .env, the log directory) sits under shared/ and is linked into each release; and the web server’s document root always points to the current link.

/var/www/app/
├── releases/
│   ├── 20261108-1412/
│   └── 20261110-0930/
├── shared/
│   ├── .env
│   └── storage/
└── current -> releases/20261110-0930

The real work is making the link change genuinely atomic. The behavior of the commonly used ln -sfn command depends on the implementation: older GNU coreutils versions and some other ln implementations delete the old link first and then create the new one; for a very brief moment there’s no link. Current GNU coreutils creates a temporary link and moves it over. Don’t rely on the version on the server; write the switch explicitly: create a temporary link and move it over with mv -T, which uses the rename system call:

REL=/var/www/app/releases/20261110-0930
cd /var/www/app
ln -s "$REL" current_tmp
mv -T current_tmp current          # rename(2): changes in a single step
sudo systemctl reload php8.2-fpm   # SIGUSR2; check the process_control_timeout setting

How long PHP-FPM waits for running workers to finish their work during a reload depends on the process_control_timeout setting in php-fpm.conf. The default value is 0; in that case long-running requests can be cut off at the moment of reload. Set the value to cover the longest expected request time (e.g. 10s); only then is the reload really graceful.

The second place to look in the console is Nginx’s FastCGI settings. The script path should be passed via the resolved real path, not via the symlink. Otherwise OPcache and PHP’s realpath cache keep using the old release directory for a while, and the complaint “we released but the old code is running” comes in.

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    fastcgi_param DOCUMENT_ROOT   $realpath_root;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}

$realpath_root resolves symlinks and gives the real releases/… path; each release is keyed in OPcache by a separate path, so nothing gets mixed up at switchover. Dependency installation (composer install --no-dev, npm ci), asset building and cache warming must be finished in the new directory before the link is switched. Running composer install in the live directory recreates the half-copied file problem above. We described how these steps are ordered in a CI pipeline in the article on setting up a CI/CD pipeline with GitHub Actions.

Database changes: expand/contract

Making the code switchover atomic is easy. The database isn’t. The solution is to split the schema change into parts spread across several releases, each of them backward compatible, instead of a single-step break. This pattern is known as “expand/contract” or “parallel change”. Example: splitting a customer.full_name column into first_name and last_name.

  1. Expand: The new columns are added so that they accept null values. The old code doesn’t see these columns and keeps working.
  2. Dual write: The new release writes to both the old and new columns, and still reads from the old column.
  3. Backfill: Existing records are moved into the new columns in small batches (e.g. 1,000 rows at a time). A single giant UPDATE can lock the table and replication.
  4. Move reads: The next release reads from the new columns and keeps writing to the old column; rollback is still safe.
  5. Contract: After verifying that no running release needs the old column any more, the old column is removed in a separate release.

It looks slow. But at every step, old and new code can work with the same schema; rolling and canary become possible, and rollback doesn’t require reverting the schema. In MySQL/MariaDB, online DDL options for large tables such as ALTER TABLE … ALGORITHM=INPLACE, LOCK=NONE return an error without starting the operation if the requested change isn’t supported; so they also work as a safe pre-check. Supported operations vary by version and engine type; rely on the documentation for your own version.

On systems without a migration tool, such as WordPress, pay extra attention to cases where a plugin or core update performs a database upgrade: these upgrades usually can’t be undone. Try such a change first in a test environment with equivalent data, and take a database backup immediately before release.

Health checks and traffic management

In a rolling or blue-green switchover, the load balancer must be able to answer the question “is this node ready?” correctly. Define a separate readiness endpoint: an address such as /healthz checks that the application can connect to the database and cache and that the configuration is loaded, and returns 200; otherwise it returns 503. Using the home page as a health check is both expensive and misleading because of responses coming from the cache. With the database down, the home page can keep returning 200 from the cache.

In open-source Nginx, upstream health checking is passive: with max_fails and fail_timeout, a server is taken out for a while when real requests fail. Active health checks (periodic test requests) are found in the commercial version of Nginx or in load balancers such as HAProxy. The order we follow for a rolling deployment with open-source Nginx is: mark the node to be updated as down in the configuration, drain the traffic with nginx -s reload, do the update, verify the health check by hand and bring the node back.

upstream app {
    server 10.0.10.11:8080 max_fails=3 fail_timeout=10s;
    server 10.0.10.12:8080 max_fails=3 fail_timeout=10s down;  # being updated
    keepalive 32;
}

In Kubernetes, the same logic is managed by the readiness probe and the Deployment’s maxUnavailable/maxSurge settings. But if the application isn’t written to stop accepting new requests and finish those in hand when it receives SIGTERM, the orchestrator alone can’t prevent downtime. For the single-server equivalent of a containerized deployment, see the production deployment with Docker Compose article.

Assets, sessions and caching

Add a content hash to the names of compiled JS/CSS files and leave the assets of at least the previous release on the server; clients holding old HTML in their cache don’t get 404s. Keep sessions not on the file system but in a shared store such as Redis or the database; if the session structure changes, the new code should also be able to read the old format. Adding a version prefix to application cache keys stops the new release from reading entries written in the old format. If you use a CDN, purge only the changed HTML paths after a release instead of emptying the whole cache; a full purge puts a sudden load on the origin.

Rollback plan

Rollback is no use if you start thinking about it on release day. Before every release, these questions should have been answered:

  • Is a rollback command or pipeline step defined, and has it been tried at least once in the last three months?
  • Does this release include an irreversible database change? If so, has a backup been taken, and will rollback be done from that backup?
  • Which metric will trigger the rollback decision: 5xx rate, response time, a drop in orders or form submissions?
  • Who will make the decision, and how long will you wait?
  • Were background jobs waiting in the queue created in the new format; can the old release process them?

An untested rollback isn’t a plan. When expand/contract is applied, a code rollback is almost always safe, because the schema supports both releases. In the symlink method, rollback means switching the link to the previous release directory with the same mv -T method and reloading PHP-FPM. In blue-green, traffic returns to the old environment; data written by the new environment in the meantime isn’t lost, because the two environments usually share the same database. That’s why the schema compatibility rule applies in blue-green too.

If you want to design the release pipeline and rollback procedure together, we build these steps into the pipeline as part of CI/CD and web DevOps automation. For reference, use Kubernetes’ Deployment documentation and Nginx’s upstream module pages.

Frequently asked questions

Is zero-downtime deployment possible on a single-server WordPress site?

On the code side, yes: unpack releases into separate directories, switch the current link atomically with mv -T and reload PHP-FPM. But if a core or plugin update performs a database upgrade, that step can cause a brief lock. Try it in a test environment first, and take a backup before release.

What’s the basic difference between blue-green and canary?

In blue-green, traffic moves to the new environment in one go, and the old environment waits on standby. In canary, the new version is first given a small share of traffic; the share is increased gradually while error rate and response time are monitored. Canary takes risk in a more controlled way with fewer resources, but requires the two versions to be able to run together for a long time.

Not always. Older GNU coreutils versions and some other ln implementations delete the existing link first and then create the new one; for a very brief moment there’s no link, and a request arriving at that moment gets an error. Current GNU coreutils uses a temporary link and a rename, but don’t leave this to the version: create a temporary link and move it over with mv -T. That’s a single rename system call and is atomic.

At what stage should I drop a database column?

In a separate release, after verifying that no running version, queue job or report still reads or writes the old column. This contract step can’t be undone; take a backup before it.

Support

Contact us for support or a discovery session on this topic.

Contact form
[email protected]

Eretek Web

We build and maintain corporate websites, WordPress and CMS platforms, intranet and SharePoint portals, document management, and form and approval workflows, and keep them secure and up to date.

Knowledge Center

Other articles