Files
jobboard/docs/release.md
T
WolfandClaude Opus 5.5 9d666d0937 Bring in pipeline, auth, deploy and docs from the boilerplate
roledesk is built on the boilerplate from here on: pipeline 2.0 (queue and
scheduler), auth (one password, sessions, passkeys), the deploy kit and its
docs, plus the coupling and packaging tests. Downstream copies, unedited.

Refreshed from boilerplate/d56949f7d0f6c0bfe5745478e09007bfad67ae87

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-23 12:29:16 +02:00

3.7 KiB

Building and publishing a release

Build on Windows, run on the server. Nothing in this half connects to the server: it tests a commit, promotes it, builds an image and pushes it to the registry. server.md is the other half.

The scripts are already in place in deploy/, with deploy/server/ beside them — db.ps1 expects that — and the Dockerfile at deploy/Dockerfile, which is where 2-build-image.ps1 looks for it inside the archived commit. The package is app; there is nothing to rename.

Once

Copy deploy/release.env.example to deploy/release.env and fill it in. .gitignore already covers deploy/release.env and deploy/backups/.

Log Docker in with a token that has package-write access, before the first push:

docker login git.rittershofer.org -u wolf

Enter the token at Docker's password prompt, not in source files or chat. Git credentials and Docker registry credentials are separate: a successful Git push does not log Docker in.

Every release

.\deploy\1-test-and-promote.ps1  # test local main, fast-forward local production
.\deploy\2-build-image.ps1       # build production's image locally
.\deploy\3-push-image.ps1        # push the built image to the registry

The number is the order. Each script stops on failure, can be run on its own, and works out the repository root for itself, so the working directory does not matter. To run all three, use .\deploy\0-release.ps1 — numbered zero so it sorts above the steps it runs.

Step 1 never builds; step 2 never pushes; step 3 never rebuilds or deploys. That separation is the point of the numbering: a failed push is 3 again, not the whole thing again.

What each step is actually doing

1 — test and promote. Resolves main to a commit, checks that commit out into a throwaway worktree, and runs the project's checks there. The worktree is what makes this honest: the tests run against exactly the tree that is about to become production, with none of the working copy's uncommitted edits in the way. Worktrees have no .venv of their own, so the interpreter comes from the main checkout and the code from the worktree.

Promotion is a fast-forward only. If production has commits main does not, that is a release made from somewhere else, and the script stops rather than discarding it.

Git publication is optional: run git push origin production yourself, or pass -PushBranch. production identifies the tested candidate; the server's running image identifies the deployed release.

2 — build. git archive of the production commit, unpacked to a temporary directory, built from there. Writing the archive out rather than piping it is deliberate — a PowerShell pipeline carries text, so it would re-encode the tar stream and hand Docker a corrupted context. The build publishes two tags locally: the short commit sha and latest.

Docker builds an image. No container starts or restarts on this machine.

3 — push. Re-tags latest onto this candidate, then pushes both. It never rebuilds, so a push that failed on connectivity is just this step again.

Uncommitted work is never included

Every step reads from git, not from the working copy. An edit you have not committed is not in the tests, not in the image, and not in the release. That is worth knowing in both directions: it cannot bite you by accident, and it will not pick up the fix you forgot to commit.

Version pinning and rollback

latest moves on every publication, so it cannot identify a previous release. Commit tags can: keep them in the registry, and set APP_TAG=<sha> in the server's .env to pin or roll back. See server.md for what else a rollback has to check.