9.2 KiB
Deploy
Everything needed to put roledesk on a server behind SWAG (../docs/Install Server.md is the box it was written for, a copy of the boilerplate's file): test it in WSL, build an image on Windows with wslc, 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.
This folder is a downstream copy of ../boilerplate/deploy (commit 09e144d), refreshed with git archive; a fix to a shared script lands upstream first. roledesk's own facts are put back after a refresh: the Dockerfile without a frontend stage and with desk, plugins, llm and seed, the extras passkeys, embeddings and llm, our image name in release.env.example, server/config.example.yaml for roledesk's keys, TABLES and REQUIRED_TABLES naming roles, and bin/pull.sh and bin/worker.sh. tests/test_deploy.py pins them.
The package is app, and the files below are where the scripts expect them: the APP_ variables, the compose service app and the hostname app.example.com in the templates are placeholders for the server, and <app> in the docs is the service's name: the hostname, the data directory, the image tag, the compose service. The domain noun is role, so "job" only ever means queued work.
Where each file is
| Here | ||
|---|---|---|
deploy/1-test-and-promote.sh, test-commit.sh, _common.sh, db.sh |
the gate, the export and the database moves, run in the WSL distro | |
deploy/2-build-image.ps1, 3-push-image.ps1, _common.ps1 |
the image build and push, run on Windows with wslc |
the distro is a sealed sandbox and does not hold a container socket |
deploy/wsl-setup.cmd, wsl-setup.ps1 |
the profile commands, written once per checkout on Windows | |
bin/backend.sh, check.sh, and ours pull.sh, worker.sh |
the dev commands, run in the WSL distro: the backend, the gate on the working tree, a pull, the worker | |
.run/serve, pull, worker |
PyCharm run configurations, left as they are | serve --reload = bin/backend.sh --reload = <folder>-backend --reload; pull = bin/pull.sh = <folder>-pull; worker = bin/worker.sh = <folder>-worker |
deploy/Dockerfile |
read out of the tree step 1 exports, by step 2 | no frontend stage; copies app, pipeline, auth, llm, desk, plugins and seed |
deploy/Dockerfile.dockerignore |
copied to .dockerignore at the root of the exported tree |
wslc streams the Dockerfile, so only a root ignore file applies |
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/config.example.yaml |
to $APP_DATA/config.yaml, with the hostname filled in |
deploy.sh refuses a config without database and auth.enabled |
deploy/server/deploy.sh, deploy/server/backup.sh |
to /srv/swag/, next to the compose file |
|
deploy/server/import.sh, deploy/server/import_database.py |
uploaded and run by db.sh push |
|
deploy/server/swag/app.subdomain.conf |
to SWAG's proxy-confs/, renamed to <app>.subdomain.conf |
db.sh expects server/ beside it, which is why deploy/server/ is committed here as well as installed on the server.
Keep every .ps1 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 .ps1 in this folder to it, the release scripts included.
wsl-setup.sh and wsl-setup.ps1 are the two halves of setting up a checkout that lives in WSL. wsl-setup.sh runs in the distro (../docs/Install WSL.md, Git). wsl-setup.ps1, or a double-click on deploy\wsl-setup.cmd, writes the commands below into the PowerShell profile, with <folder> the checkout folder's name (jobboard here) or -Name. PowerShell 7, the execution policy, wslc, the hand-paste fallback and what to check when a command fails are in ../docs/Install WSL.md, PS Profile commands.
| Command | Runs | Does |
|---|---|---|
<folder>-cd |
Set-Location |
PowerShell into the checkout's folder |
<folder>-sh |
wsl.exe |
a shell in the distro, in the checkout |
<folder>-backend [-v] [--reload] |
bin/backend.sh in WSL | uv run app serve on :8790 |
<folder>-pull [args] |
bin/pull.sh in WSL | uv run app job pull, one pull in the foreground (roledesk's) |
<folder>-worker [args] |
bin/worker.sh in WSL | uv run app worker, the queue drained with no web app (roledesk's) |
<folder>-check |
bin/check.sh in WSL | the gate on the working tree, without promoting |
<folder>-1test [--push-branch] [--no-tests] |
deploy/1-test-and-promote.sh in WSL | test local main, fast-forward production, export it |
<folder>-2build |
deploy\2-build-image.ps1 on Windows | build the exported tree with wslc |
<folder>-3push |
deploy\3-push-image.ps1 on Windows | push the built image with wslc |
<folder>-0release [--push-branch] [--no-tests] |
the three above | steps 1, 2 and 3 in order, stopping at the first failure |
<folder>-db pull|push |
deploy/db.sh in WSL | the database, to and from the server |
Each command is one line in the profile: wsl.exe -d <DISTRO> --cd <CHECKOUT> -- bash <script> @args for the ones that run in the distro, and for steps 2 and 3 the .ps1 with the execution policy lifted for that run. DISTRO and CHECKOUT are read from deploy/release.env when the setup runs, so rerun it after either changes. -backend, -pull and -worker stay in the foreground until Ctrl-C. The -0release to -3push names carry the number of the script's file name, so 0<Tab> after <folder>- finds them.
.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. Install Server.md and Install WSL.md are copies of the boilerplate's documentation/ files; the two proposals stay in the boilerplate checkout.
- ../docs/Install Server.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/Install Server.md, Publishing a release — the release side:
release.env, the numbered scripts and where each runs, what each one refuses to do, and why the tests run in a throwaway worktree. - ../docs/Install Server.md, Operating it — installing, deploying, backups, moving a SQLite database in either direction, rolling back, and what to verify before relying on any of it.
- Proposal LLM Backends.md (boilerplate checkout) — asking Claude from a deployed app: API key or subscription token, selected by which one is in the environment.
llm/is the implementation of it, see ../llm/README.md. - Proposal Password Protection.md (boilerplate checkout) — one password on a public hostname: the lockout, sessions, passkeys, and how much throttling is actually worth building.
auth/is the implementation of it, see ../auth/README.md.
A new service, in order
- DNS, then certificate, then registry login, then data directory — ../docs/Install Server.md.
- Copy
release.env.exampletorelease.envand fill it in. That is the only file this step touches: everything else is already committed. <folder>-0releasefrom Windows to test, promote, build and publish.wslcand its registry login are on Windows, ../docs/Install Server.md, Publishing a release.- Install the server files and
config.yaml, edit.env,bash deploy.sh— ../docs/Install Server.md, Operating it. - Put the model credential in
.envif the app needs one — ../llm/README.md. - Get in, rotate the bootstrap password, register a passkey — ../auth/README.md.
- Schedule
backup.sh, then restore one of its backups somewhere else to prove it works.
Step 1 runs pytest in a throwaway worktree through test-commit.sh, with ruff and mypy commented out beside it, as the release has always run. The dev group has both, so uncommenting them is the owner's call: the tree has to pass them first.
What this is not
Not a framework: nothing here is imported or extended, it is copied and edited. boilerplate/deploy/ is the source of truth, and news, health, jobboard and pocketmoney hold copies of it.