ssi atomic

Atomic Deployment Command

Deploy a site atomically using symlink updates for zero-downtime deployments.

ssi atomic <source> <link>

Arguments

<source> - Source directory containing your site files and ssi-config.toml
<link> - Path to the deployment symlink

Options

--config <file> — Use a specific configuration file instead of ssi-config.toml
--allow-external-paths — Allow external paths (symlinks outside source directory, absolute paths in config)
--no-preserve-timestamps — Do not preserve file timestamps (applies to both copied files and processed template output)
--initial — Bootstrap atomic deployment (use for first deployment when symlink doesn’t exist)
--suffix <type> — Suffix type (default: blue-green):
- blue-green — alternates between .blue and .green; triggers cleanup of the outgoing deployment directory; ignores --suffix-length (default)
- git — git commit hash as suffix; falls back to random if no git repository is found
- random — random alphanumeric string
- timestamp — timestamp in YYYYMMDDHHMMSSNNNNNNNNN format; ignores --suffix-length
--suffix-length <value> — Suffix length (ignored for timestamp and blue-green):
- short — 10 characters (works with both git and random)
- long — 40 characters (full git hash or maximum random length)
- numeric value (1–40) — exact character count for both git and random (default: 12)

How it Works

Atomic deployment enables zero-downtime updates by:

Detecting current deployment color (.blue or .green)
Removing old deployment with opposite color (if it exists)
Creating new deployment directory with opposite color
Processing your site into the new directory
Atomically updating symlink to point to the new deployment

Result: Always maintains current + previous deployment for instant rollback

Symlink Atomicity

On Linux, ssi replaces the live symlink using a temporary symlink and the rename(2) system call. The process is:

A temporary symlink — with a random suffix, e.g., production.tmp.x7k3m2ab — is created pointing to the new deployment directory.
rename(2) atomically replaces the live symlink with the temporary one in a single kernel operation.

Because rename(2) is atomic, the live symlink is never in a broken state — there is no window during which a web server could dereference the link and find nothing. The temporary symlink is always created in the same directory as the live link; this guarantees that the rename stays on one filesystem, which is required for rename(2) atomicity.

Blue-Green Default

By default, atomic deployments use blue-green strategy:

Alternates between .blue and .green directories
Automatically cleans up old deployments before building new ones
Always keeps two versions (current + previous) for rollback

Alternative suffix modes (opt-in):

--suffix=git: Uses git commit hash (e.g., 12 chars)
--suffix=random: Uses random alphanumeric string
--suffix=timestamp: Uses timestamp format

First-Time Deployment (Bootstrap)

For initial deployment when the symlink doesn’t exist yet, use --initial:

# Bootstrap atomic deployment (creates .blue by default)
                ssi atomic --initial site/ ~/public_html/mysite
                # Creates: ~/public_html/mysite.blue and symlink
                
                # Subsequent deployments work normally
                ssi atomic site/ ~/public_html/mysite
                # Creates: ~/public_html/mysite.green (alternates with .blue)
                
                # Bootstrap with custom suffix
                ssi atomic --initial --suffix=git site/ ~/public_html/mysite
                # Creates: ~/public_html/mysite.{githash} and symlink

Requirements for --initial:

Symlink must NOT exist (error if it does)
Parent directory must exist — SSI will not create it. If <link> is ~/public_html/mysite, then ~/public_html/ must exist before you run ssi atomic. Create it first:
```
mkdir -p ~/public_html
                ssi atomic --initial site/ ~/public_html/mysite
                
```
Preserve processor is automatically skipped (nothing to preserve yet)

Self-Healing Deployments

When the symlink exists but its target directory has been deleted — for example, by rm -rf or disk cleanup — ssi atomic automatically recovers with a warning and proceeds with the next deployment. No manual intervention is needed.

⚠️ Symlink target /var/www/production.blue not found — proceeding with self-healing recovery from /var/www/production

This makes ssi atomic safe to run unattended from cron or CI, even in environments where deployment directories may be cleaned up between runs.

Distinguish from --initial:

Situation	Use
No symlink at all — first ever deployment	`ssi atomic --initial`
Symlink exists, target directory deleted	`ssi atomic` (self-heals automatically)

If a symlink is present and you pass --initial, SSI will fail — --initial is only for the case where no symlink exists yet.

Examples

# Blue-green deployment (default) - alternates between .blue and .green
                ssi atomic site/ /var/www/production
                # First deploy:  → production.blue (after --initial bootstrap)
                # Second deploy: → production.green (.blue kept for rollback)
                # Third deploy:  → production.blue (.green kept for rollback)
                
                # Explicit git suffix (opt-in to git-based naming)
                # Note: Requires .git directory in source_dir
                ssi atomic site/ /var/www/production --suffix=git
                # → production.abc123456789ab (git commit hash)
                
                # Git suffix with short hash
                ssi atomic site/ /var/www/production --suffix=git --suffix-length=short
                # → production.abc1234567 (10 chars)
                
                # Random suffix with custom length
                ssi atomic site/ /var/www/production --suffix=random --suffix-length=8
                # → production.xyz98765 (8 chars)
                
                # Timestamp suffix
                ssi atomic site/ /var/www/production --suffix=timestamp
                # → production.20240819105333123456789
                
                # Preview atomic deployment without making changes
                ssi --dry-run atomic site/ /var/www/production
                
                # Dry-run shows what directory would be created and symlink updated
                ssi -n atomic site/ /var/www/production

For complete argument details: ssi atomic --help