Atomic Deployments — Flip a Switch, Not a Site

Most deploy scripts have the same quiet flaw: they edit the live site in place. You copy new files over old ones while the server is still handing pages to visitors. For the few seconds that copy runs, the site is neither fully the old version nor fully the new one — it’s a mix, and a mix can be broken. An atomic deployment removes that window entirely. The switch from old to new happens in a single filesystem operation, so a visitor either gets the whole old site or the whole new site, never something in between.

The problem with copying in place

Picture the common shape: build the site, then sync the output straight into the directory the web server reads from.

# The naive deploy: overwrite the live directory in place
rsync -avz --delete ./build/ user@server:/var/www/site/

While that rsync runs, the live directory is a moving target:

The root cause is the same in every row: the live site and the deploy target are the same directory. Atomic deployment breaks that coupling.

The core idea: a symlink is the switch

Instead of one live folder, keep many timestamped release folders and a single symlink — call it current — that points at the active one. The web server’s document root points at current, so visitors always follow the symlink to whichever release is live.

/var/www/site/
├── releases/
│   ├── 20260716-140200/     ← previous release (kept for rollback)
│   ├── 20260716-151030/     ← previous release
│   └── 20260716-153312/     ← new release, just uploaded
└── current -> releases/20260716-153312   ← the only thing that "switches"

Deploying is now two independent halves:

1. Upload the new build into a brand-new releases/<timestamp>/ folder. This can take as long as it needs — the live site is a different folder, completely untouched.
2. Switch by re-pointing current at the new folder.

That second step is the whole trick. Re-pointing a symlink is a single, atomic filesystem operation. There is no moment where current points at “half the new release.” It points at the old one, and then — one syscall later — the new one.

# The atomic switch: force + no-dereference re-points an existing symlink in one operation
ln -sfn releases/20260716-153312 current

The deploy flow, step by step

Everything before step 4 is invisible to visitors. Step 4 is the deploy, and it’s instantaneous. Everything after is housekeeping. A minimal script:

#!/usr/bin/env bash
set -euo pipefail

BASE="/var/www/site"
RELEASE="$(date +%Y%m%d-%H%M%S)"

# 1–2. Build, then upload into a NEW release dir (note: no --delete needed).
build_site
rsync -avz ./build/ "user@server:${BASE}/releases/${RELEASE}/"

# 4–5. Switch atomically, then keep only the newest 5 releases.
ssh user@server bash -s <<EOF
  set -euo pipefail
  ln -sfn "${BASE}/releases/${RELEASE}" "${BASE}/current"
  cd "${BASE}/releases" && ls -1dt */ | tail -n +6 | xargs -r rm -rf
EOF

Notice the --delete flag is gone. Each release is its own clean folder built from scratch, so there are no stale files to purge — another class of bug removed for free.

Rollback becomes one command

This is the payoff that’s hard to overstate. Because previous releases are still sitting on disk, undoing a bad deploy is just pointing the symlink back:

ln -sfn releases/20260716-151030 current

No rebuild, no re-upload, no downtime — a second, at most. Compare that to the in-place approach, where “rollback” means rebuilding an old commit and re-running the whole risky sync. When something breaks at 2am, “flip the symlink back” is the difference between a shrug and an incident.

What it costs

Atomic deployment isn’t free, but for a static site the price is small:

The one-line version

Upload the new site next to the old one, then flip a symlink. The switch is instant, nothing breaks mid-deploy, and rollback is a single command.

This pattern is the backbone of tools like Capistrano and Deployer, but you don’t need any of them to get the benefit. A timestamped folder and a symlink is the entire idea — the rest is convenience.