A Note on What This Is

Details of the businesses involved are withheld: this work was delivered under employment, and the systems and clients are not ZaidanLab's to claim. What follows describes a real pattern of engineering work, with names, data and internal details left out.

The Problem Pattern

Many commerce platforms deploy in place: pull the code, enable maintenance mode, run the build, then bring the site back. On a large catalog the build can take long enough that customers see a maintenance page during trading hours. The goal is to ship without any visible interruption.

Build First, Then Swap

The reliable approach is to build the new release in a separate directory while the current release keeps serving traffic, then switch to it atomically by repointing a symlink. If the build fails, nothing changes for visitors. Rollback is the same swap in reverse, which makes releases much less stressful.

What Has to Be Shared Between Releases

Anything that must survive a release (media uploads, generated reports, runtime configuration, session or cache storage) lives outside the release directory and is linked in. Getting that list wrong is the most common cause of a deploy that looks successful and then loses data or serves stale files.

Build Traps

Asset compilation can fail for reasons unrelated to the change being shipped, for example a deleted source file that leaves dangling links in the built output. Treat the build as a gate: if it fails, the release never goes live. Also decide explicitly what happens to the frontend stylesheet build, which should be produced on the server at deploy time rather than committed as a generated file.

Multiple Nodes and Shared Storage

With more than one application node on shared storage, a swap must look atomic to every node. Check how each node resolves the release path, and be careful with permissions, because files created by a command-line user and files created by the web server user can block each other.

Why This Matters

A release process that cannot be interrupted by a failure is what lets a team ship small changes often. That is a reliability feature for the business, not only a convenience for developers.