Files
WolfandClaude Opus 5.5 515d2250fc Deploy from a WSL checkout, from boilerplate 1679e88
When the checkout lives under \\wsl.localhost, step 1 runs its tests in the
distro through deploy/test-commit.sh and db.ps1 push makes its snapshot
there, because the .venv is a Linux one. pipeline/context.py narrows by
sys.platform so mypy passes on Linux. See boilerplate docs/wsl.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 19:43:50 +02:00
..

Deploy

Everything needed to put this app on the rittershofer.org box behind SWAG: build an image on Windows, publish it to Gitea, run it as one more service in the compose file that already runs the proxy, back up its database, and give it a password that survives being on the open internet.

Extracted from newsdesk, which is the worked example — every decision here has been run in production at least once, and the comments say why rather than what.

It is already in place. Nothing has to be copied and nothing has to be renamed: the package is app, the environment variables are APP_, and the files below are where the scripts expect them. <app> in the docs is your service's name — the hostname, the data directory, the image tag, the compose service — and it is the one thing you choose.

Where each file is

Here
deploy/*.ps1 the release scripts, run on Windows
deploy/Dockerfile read out of the archived commit by step 2 copies app, pipeline and auth
deploy/Dockerfile.dockerignore Docker finds it by that name
deploy/server/* committed here, then installed on the server
deploy/server/compose.yaml to /srv/swag/docker-compose.yml, as one services: block
deploy/server/env.example to /srv/swag/.env, as appended variables, chmod 600
deploy/server/deploy.sh, deploy/server/backup.sh to /srv/swag/, next to the compose file
deploy/server/swag/app.subdomain.conf to SWAG's proxy-confs/, renamed to <app>.subdomain.conf

db.ps1 expects server/ beside it, which is why deploy/server/ is committed here as well as installed on the server.

Keep the .ps1 files to ASCII. Windows PowerShell 5.1 reads a script without a byte-order mark as Windows-1252, so an em dash becomes three characters ending in a closing quote: the string ends in the middle of itself and the script fails to parse before it runs a line. Write --. newsdesk hit this on a comment nobody thought was code, and tests/test_packaging.py here holds every script in this folder to it.

.gitignore already covers deploy/release.env and deploy/backups/.

The docs

They are one directory up, in ../docs/, because they are about the hosting rather than about these scripts.

  • ../docs/hosting.md — what the box is, the seven steps to add a service, what the templates already decide for you, and the things that have already gone wrong on it. Start here for a service that is not on the box yet.
  • ../docs/release.md — the Windows side: release.env, the four numbered scripts, what each one refuses to do, and why the tests run in a throwaway worktree.
  • ../docs/server.md — installing, deploying, backups, moving a SQLite database in either direction, rolling back, and what to verify before relying on any of it.
  • ../docs/llm-backends.md — asking Claude from a deployed app: API key or subscription token, selected by which one is in the environment, with a self-contained reference implementation.
  • ../docs/password-protection.md — one password on a public hostname: the lockout, sessions, passkeys, and how much throttling is actually worth building. auth/ is the implementation of it.

A new service, in order

  1. DNS, then certificate, then registry login, then data directory — ../docs/hosting.md.
  2. Copy release.env.example to release.env and fill it in. That is the only file this step touches: everything else is already committed.
  3. .\deploy\0-release.ps1 to test, promote, build and publish.
  4. Install the server files, edit .env, bash deploy.sh — ../docs/server.md.
  5. Put the model credential in .env if the app needs one — ../docs/llm-backends.md.
  6. Get in, rotate the bootstrap password, register a passkey — ../docs/password-protection.md.
  7. Schedule backup.sh, then restore one of its backups somewhere else to prove it works.

Step 1 of 0-release.ps1 runs pytest in a throwaway worktree, with ruff and mypy commented out beside it: this repository's dev group is pytest and httpx, and a gate whose tool is not installed fails every release for a reason that has nothing to do with the code. Add the tools, then uncomment the gates.

What this is not

Not a framework and not a generator: nothing here is imported or extended, it is copied and edited. That is the point — three services with three edited copies beats three services sharing one abstraction that has to be right for all of them. What this repository changes is only where the copy comes from: boilerplate/deploy/ is the source of truth, and news and health hold copies of it.