Commit `bbf4eec5cd`

bbf4eec5cd941f040ab46d6a0cbae560a1900821

parent: e1dc1624c4

Unsigned

cmc <hello@cleberg.net> · 2026-08-22 04:20 UTC

Add a dry-run deploy, and document which invocation writes to the server

The deploy is rsync --delete-before, so a build that silently produced fewer
pages would quietly remove the rest from the server. DRY_RUN=true connects and
compares but transfers nothing, listing every file that would be sent or
deleted. --itemize-changes because --dry-run alone prints almost nothing, and
run() grew an echo flag because it swallows stdout on success, which would have
hidden the entire output.

The README described three variables without saying that one combination of
them overwrites production, and suggested deploying by scp or SFTP, which is
not what the script does. It now carries the full matrix. The clone URL still
pointed at sr.ht.

No default behaviour changes: without DRY_RUN the rsync arguments are byte for
byte what they were.

Layout: unified · split

README.md +33 −13

	@@ -56,7 +56,7 @@ To obtain a working copy of this repository, execute the following
56	commands within a shell environment or Emacs shell interface:	56	commands within a shell environment or Emacs shell interface:
57		57
58	``` shell	58	``` shell
59	git clone https://git.sr.ht/~ccleberg/cleberg.net	59	git clone https://github.com/ccleberg/cleberg.net
60	cd cleberg.net	60	cd cleberg.net
61	emacs -nw	61	emacs -nw
62	```	62	```
	@@ -69,32 +69,52 @@ For users employing Doom Emacs, open any repository Org file using
69	The `build.py` script wraps the build: it runs orgo, and then either	69	The `build.py` script wraps the build: it runs orgo, and then either
70	deploys the result or serves it locally.	70	deploys the result or serves it locally.
71		71
72	Two environment variables control what it does, and both default to	72	Environment variables control what it does, and all default to off:
73	off:
74		73
75	- `BUILD=true` performs the build.	74	- `BUILD=true` performs the build.
76	- `DEPLOY=true` deploys in production, or starts a development server	75	- `DEPLOY=true` deploys in production, or starts a development server
77	on port 8000 otherwise.	76	on port 8000 otherwise.
78		77	- `ENV=prod` selects production: image URLs are rewritten to be
79	A third, `ENV`, selects the mode. Setting `ENV=prod` rewrites image	78	root-relative (see Deployment below) and the `ruff` pass is skipped.
80	URLs to be root-relative (see Deployment below) and skips the `ruff`	79	Anything else builds for development.
81	pass; anything else builds for development.	80	- `DRY_RUN=true` turns a production deploy into a report. Production
		81	only; ignored everywhere else.
		82
		83	Exactly one combination writes to the server:
		84
		85	\| `ENV` \| `BUILD` \| `DEPLOY` \| `DRY_RUN` \| What happens \| Output \| Server \|
		86	\|--------\|---------\|----------\|-----------\|---------------------------------------\|--------------\|-------------------\|
		87	\| unset \| `true` \| — \| — \| Development build, `ruff` first \| `.build-dev/`\| Untouched \|
		88	\| unset \| `true` \| `true` \| — \| Development build, then serve on :8000\| `.build-dev/`\| Untouched \|
		89	\| `prod` \| `true` \| — \| — \| Production build and image rewrite \| `.build/` \| Untouched \|
		90	\| `prod` \| — \| `true` \| `true` \| Reports what a deploy would change \| — \| Read only \|
		91	\| `prod` \| `true` \| `true` \| — \| Production build, then deploy \| `.build/` \| Overwritten \|
82		92
83	``` shell	93	``` shell
84	# Production build:
85	ENV=prod BUILD=true uv run build.py
86
87	# Development build:	94	# Development build:
88	BUILD=true uv run build.py	95	BUILD=true uv run build.py
89		96
90	# Development build, then serve it on localhost:8000:	97	# Development build, then serve it on localhost:8000:
91	BUILD=true DEPLOY=true uv run build.py	98	BUILD=true DEPLOY=true uv run build.py
		99
		100	# Production build, no deploy:
		101	ENV=prod BUILD=true uv run build.py
		102
		103	# What would a deploy change? Connects, compares, transfers nothing:
		104	ENV=prod DEPLOY=true DRY_RUN=true uv run build.py
		105
		106	# Production build and deploy. This is the one that writes to the server:
		107	ENV=prod BUILD=true DEPLOY=true uv run build.py
92	```	108	```
93		109
94	Generated site files reside in `.build/` for production and	110	Generated site files reside in `.build/` for production and
95	`.build-dev/` for development, ready for deployment. You can deploy the	111	`.build-dev/` for development.
96	resulting static site files via standard file transfer protocols such as	112
97	`scp` or SFTP.	113	The deploy is `rsync --delete-before`, so files the build no longer
		114	produces are removed from the server. That is what makes the dry run
		115	worth having: a build that silently produced fewer pages would quietly
		116	delete the rest. Lines beginning `*deleting` in the dry-run output are
		117	what the real deploy would remove.
98		118
99	Builds are incremental: orgo keeps an `.orgo-cache.json` inside the	119	Builds are incremental: orgo keeps an `.orgo-cache.json` inside the
100	output directory and re-renders only what changed, so the directory is	120	output directory and re-renders only what changed, so the directory is

build.py +37 −18

 from pathlib import Path
-def run(cmd, error):
+def run(cmd, error, echo=False):
-    """Run cmd quietly, exiting with its stderr if it fails."""
+    """Run cmd quietly, exiting with its stderr if it fails.
+    echo prints stdout on success. Only the dry run needs it: its output is the
+    whole reason to run it, and the default of swallowing stdout would hide it.
+    """
     result = subprocess.run(cmd, capture_output=True, text=True, check=False)
     if result.returncode != 0:
         print(error, file=sys.stderr)
         print(result.stderr, file=sys.stderr)
         sys.exit(1)
+    if echo:
+        print(result.stdout, end="")
 def run_ruff():
         sys.exit(1)
-def deploy_to_server(build_dir, server):
+def deploy_to_server(build_dir, server, dry_run=False):
+    """Push the built site to the server, or show what pushing it would do.
+    The deploy deletes remote files the build no longer produces, so "what would
+    this remove" is a question worth being able to ask before answering it
+    irreversibly. DRY_RUN=true asks it: rsync connects and compares, then reports
+    instead of transferring.
+    """
     remote_path = f"{server}:/var/www/cleberg.net/"
-    print(f"Deploying {build_dir}/ → {remote_path}")
+    print(f"{'Would deploy' if dry_run else 'Deploying'} {build_dir}/ → {remote_path}")
-    run(
+    cmd = [
+        "rsync",
+        "-r",
+        "--delete-before",
         # The build cache lives in the output directory because it describes it, but it
         # is not part of the site. Excluding it also stops --delete removing it locally.
-        [
+        "--exclude",
-            "rsync",
+        ".orgo-cache.json",
-            "-r",
+    ]
-            "--delete-before",
+    if dry_run:
-            "--exclude",
+        # --itemize-changes because --dry-run alone prints almost nothing: the
-            ".orgo-cache.json",
+        # point is to name every file that would be sent or deleted.
-            f"{build_dir}/",
+        cmd += ["--dry-run", "--itemize-changes"]
-            remote_path,
+    cmd += [f"{build_dir}/", remote_path]
-        ],
+    run(cmd, "Error during rsync deployment:", echo=dry_run)
-        "Error during rsync deployment:",
-    )
 def start_dev_server(build_dir):
     if os.environ.get("DEPLOY", "").casefold() == "true":
         if prod:
-            print("Deploying to production...")
+            dry_run = os.environ.get("DRY_RUN", "").casefold() == "true"
-            deploy_to_server(build_dir, "homelab")
+            print(
+                "Dry run — the server will not be modified"
+                if dry_run
+                else "Deploying to production..."
+            )
+            deploy_to_server(build_dir, "homelab", dry_run)
         else:
             start_dev_server(build_dir)

Commit bbf4eec5cd

Commit `bbf4eec5cd`