Skip to content
Tutorials Center
My learning

Topics

Lesson 71 of 95 ยท Projects

Project: A Deployment Script Skeleton

Build a deployment script skeleton in Bash: environment config, timestamped releases, atomic symlink switch, loopback health check, rollback and dry-run mode.

"Deploying" sounds grand, but at its core it is a small, careful sequence: put the new version somewhere next to the old one, check that it works, switch over in one step, and keep the old version around in case you need to go back. Many real deployment tools, from shell scripts to Capistrano and Deployer, work exactly like this. In this project you write the skeleton in Bash and run it for real in the sandbox, with a health check against a server on the loopback interface.

You will meet symbolic links in a very practical role, configuration handling, background processes, a TCP client written in pure Bash (networking basics), traps for cleanup, a lock directory, and the dry-run and exit-code habits from Designing Maintainable Scripts. Like the other projects it is built in steps, and the time is injectable so every example prints the same release names.

This is a teaching skeleton. It deploys into a directory inside the sandbox. A real deployment adds things we cannot do here: copying to remote servers over SSH, restarting a service manager, database migrations, secrets management and notifications. The structure, though, is the one you would keep.

TEXT
  deploy-root/
  โ”œโ”€โ”€ releases/
  โ”‚   โ”œโ”€โ”€ 20260105T020000Z/      <- every deploy builds a NEW directory
  โ”‚   โ”œโ”€โ”€ 20260105T030000Z/
  โ”‚   โ””โ”€โ”€ 20260105T050000Z/
  โ”œโ”€โ”€ shared/
  โ”‚   โ””โ”€โ”€ app.env                <- settings that must survive deploys
  โ”œโ”€โ”€ current -> releases/20260105T050000Z     <- what the web server uses
  โ””โ”€โ”€ .lock/                     <- exists only while a deploy is running

The web server (or any other program) always uses the path deploy-root/current. Going live is nothing more than repointing that one symlink to a different release directory, and going back is pointing it at the previous one. Nothing is copied or modified in place while the site is running, so a half-finished deploy can never be seen by users.

The sequence of deploy is: take the lock, build the release into a new directory, start the release on a loopback port and check its health, and only if it answers correctly switch the symlink and delete releases beyond the limit. If the check fails the new directory is removed and current never moved.

Symbolic links are the heart of the design, and there are two traps. First, ln -sf releases/r2 current when current is already a symlink to a directory does not replace it: ln follows the link and creates a new link inside the old release. The option -n (--no-dereference) tells ln to treat the existing link as a file. Second, ln -sfn internally removes the old link and then creates the new one, and for a moment current does not exist. The fix is to create the new link under another name and move it over the old one with mv -T, which uses the rename system call, atomic on one filesystem: at every instant current points at either the old or the new release.

Bash Step 1: ln -sf pitfall, then an atomic switch with mv -T

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The last example shows why -T (treat the destination as a normal file, never as a directory to move into) is essential: without it mv puts other.new inside releases/r1. mv -T is a GNU option; on macOS or BSD the same effect needs mv -h or a different approach, so the skeleton is Linux-oriented.

Notice also that the links are relative (releases/r1, not /full/path/releases/r1), so the whole deploy-root directory can be moved or mounted elsewhere without breaking.

Step 2: environment configuration

The same code is deployed to several environments (staging, production), and the differences live in configuration files. The tempting way to read one is source config/production.env, but that executes the file: anyone who can edit it can run arbitrary commands as the deploying user. A deployment script is exactly where that matters. The skeleton instead reads the file as data: split each line at the first =, accept only a small list of known keys, and validate each value.

Bash Step 2: parse a config file as data, not as code

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The loop uses IFS='=' read -r key value. Because value is the last variable, it receives the rest of the line, so a value may itself contain =. Blank lines and # comments are skipped. printf -v "$key" '%s' "$value" assigns to a variable whose name is in $key; it is safe here only because the case has already restricted $key to known names. (See Parameter Expansion and The Order of Expansions for why variable-name tricks need that guard.)

Step 3: a health check on the loopback interface

How do you know the new release works before real users see it? You start it on a loopback port nobody else can reach (127.0.0.1) and ask it. The skeleton looks for the answer 200 OK on a path such as /health, retries a few times, and stops the candidate afterwards.

The sandbox has no application server, so python3 -m http.server stands in for "your real app" and serves each release's public directory. (It is a labelled stand-in: the lesson is about the check, not the server.) The HTTP client is pure Bash: exec 3<>/dev/tcp/HOST/PORT opens a TCP connection as file descriptor 3, printf sends a request into it and read takes the first line of the answer. Port 0 asks the operating system for any free port, which avoids clashes, and the server prints the number it was given; the script parses it from its log.

Bash Step 3: start a candidate, ask it, stop it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

http_status fails cleanly when nothing listens (bash reports "Connection refused" and the function returns 1), which the real script turns into the code 000 and retries. The retry loop matters in practice, because a real server needs a moment to boot: the first probe may fail even for a perfectly healthy release.

A health check proves that the release starts and answers. It does not prove it is bug-free, which is why serious pipelines add smoke tests, canary releases (a small share of traffic first) and monitoring after the switch. Keep the check cheap and honest: a /health page that always returns 200 regardless of what is broken is worse than none.

Step 4: the complete deployment script

Now everything together. The script has four commands: deploy SRC, rollback, status and prune. Global options come first: -e ENV picks the config file, -r ROOT the target directory and -n turns on dry-run mode, in which every state-changing step is only printed. The same run helper as in the backup project makes that possible with almost no extra code.

The demo that follows the script uses a fixed clock (DEPLOY_NOW) and plays a story: a dry run, two good deploys, a broken release that the health check refuses, a third deploy that triggers pruning, a dry-run rollback and a real one, a stale lock, a second environment and two configuration mistakes. The "application" is a template page; the build replaces {{ENV}} and {{VERSION}}, and a typo in a placeholder ({{VERSIOM}}) is the deliberate bug that makes the broken release fail its check.

Bash Step 4: deploy.sh with releases, health check, rollback and dry-run

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

How the pieces fit

Atomic and reversible. The only step that changes what users see is switch_to, a single rename. Everything before it happens in a new directory that nobody is using, and everything after it (pruning) only deletes releases that are not live. This is what makes rollback trivial: the old release is still on disk, untouched, so going back is the same one-step switch.

The health check guards the switch. In the broken-release run you can read the three failed probes (404), the removal of the new directory and the message current is still 20260105T030000Z. The deploy command also returned status 1, so a CI job calling it fails visibly. Compare this with the naive deploy that overwrites files in place: it would have taken the site down first and discovered the problem afterwards.

Names sort by time. Release IDs are UTC timestamps with the year first, as in the backup project, so ls order is time order. release_ids is therefore all that rollback and prune need: the "previous" release is the one just before current in the list, and pruning deletes from the front. prune skips the live release explicitly: after a rollback current may be an old release, and deleting it by age would take the site down.

Shared state lives outside releases. shared/app.env stands for anything that must survive a deploy: uploaded files, secrets, a database file. Each release gets a relative symlink to it (../../shared/app.env). Never store such data inside a release directory, because pruning would delete it.

The lock. mkdir either creates the directory or fails, atomically, so mkdir deploy-root/.lock is a lock that two scripts cannot both obtain. The EXIT trap in cleanup removes it when the script ends, whether it succeeded, failed or was interrupted, and stops the candidate server too. A hard kill (SIGKILL) runs no traps, which is why the error message tells you how to remove a stale lock by hand. The flock command is the alternative that cleans up automatically (see Advanced Patterns).

Configuration as data, with safe defaults. The defaults sit at the top of the script, the file overrides them, unknown keys are errors, and a typo in a config key fails the deploy instead of being silently ignored.

Extending it for real work

  • Remote deployment: run the same steps through ssh host 'bash -s' < script or with rsync for the upload, and keep the current symlink swap on the server. See SSH, scp and Working Remotely. Read-only here: no network.
  • Restart or reload: after switch_to, tell the service manager to reload (systemctl reload app), see Packages, Services and systemd. A post-switch health check, with automatic rollback if it fails, closes the loop.
  • Build step: npm ci && npm run build, composer install --no-dev, or docker build, run inside the new release directory before the check.
  • Database migrations are the hard part: they cannot be rolled back by moving a symlink. Make migrations backward compatible (add first, remove later) so the old release still works against the new schema.
  • Retention by age instead of count, a --keep N option, deployment notifications, a deploy.log with timestamps.
  • Tests: drive the script with the framework from A Mini Test Framework: deploy twice, assert the link, break a release, assert nothing changed.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the script create current.new and then run mv -T current.new current, instead of just ln -sfn?

    ln -sfn removes the old link and then creates the new one; between those two steps current is missing. rename(2), used by mv -T, replaces it atomically.
  2. 2. What is wrong with reading a config file using source config/production.env?

    source runs every line as Bash. A line such as KEEP_RELEASES=$(command) would execute the command. Parsing KEY=VALUE as data with a whitelist avoids that.
  3. 3. A new release fails its health check. What does deploy do?

    The switch only happens after a successful check. On failure the half-built release is deleted, the live one keeps serving traffic and the non-zero exit status lets a CI job notice.
  4. 4. Why does prune skip the release that current points to, even if it is old?

    Pruning removes the oldest names first. After a rollback the live release may be among the oldest, so the script must explicitly protect whatever current points to.
  5. 5. How does the script check a candidate release using only Bash as the HTTP client?

    Bash's special /dev/tcp/HOST/PORT path opens a TCP connection. Writing a raw HTTP request to the descriptor and reading the first line gives the status code.

Summary

  • Deploy by building each version into its own timestamped release directory and switching one current symlink; rollback is the same switch in the other direction.
  • Replace the link atomically: ln -sfn new current.new && mv -T current.new current. Plain ln -sf on a directory link creates a stray link inside the old target.
  • Read configuration as data with a whitelist; never source a file you do not fully control.
  • Start the candidate on a loopback port and probe a health URL with retries before going live. Bash alone can speak HTTP through /dev/tcp.
  • Protect the live release from pruning, keep shared state outside releases, and use a mkdir lock with an EXIT trap.
  • Offer -n dry-run through one run helper, log every step, and exit non-zero on any failure.

Next: Linux and Bash Cheat Sheet