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:
1 parent
1f436104f3
commit
9d666d0937
76 files changed
+15235
No files matched your search
@@ -0,0 +1,52 @@
|
||||
# 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/](../docs), because they are about the hosting rather than about these scripts.
|
||||
|
||||
- **[../docs/hosting.md](../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](../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](../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](../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](../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](../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](../docs/server.md).
|
||||
5. Put the model credential in `.env` if the app needs one — [../docs/llm-backends.md](../docs/llm-backends.md).
|
||||
6. Get in, rotate the bootstrap password, register a passkey — [../docs/password-protection.md](../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.
|
||||
Reference in new issue
Block a user