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>
This commit is contained in:
WolfandClaude Opus 5.5 committed 2026-09-23 12:29:16 +02:00
1 parent 1f436104f3
commit 9d666d0937
76 files changed
+15235

No files matched your search

+51
View File
@@ -0,0 +1,51 @@
# 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](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:
```bash
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
```powershell
.\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](server.md#roll-back) for what else a rollback has to check.