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>
76 lines
5.2 KiB
Markdown
76 lines
5.2 KiB
Markdown
# Server setup and operation
|
|
|
|
What happens once an image has been published. The release half is [release.md](release.md); the box itself and the seven steps for putting a new service on it are [hosting.md](hosting.md).
|
|
|
|
Deployment is server-local. No Git checkout, build tooling or SSH from the development machine is needed for it — `db.ps1` is the one exception and it moves a database, not a release.
|
|
|
|
## Install the files
|
|
|
|
`APP_DATA` decides where the data directory goes. Left out, it is `./data` beside the compose file. Set to an absolute path, it can sit under the one root every container on the box writes to — which is what makes a backup a single target rather than a hunt.
|
|
|
|
```bash
|
|
sudo mkdir -p /srv/data/app/home /srv/data/app/backups
|
|
sudo chown -R 1000:1000 /srv/data/app
|
|
```
|
|
|
|
`home/` is there because `HOME=/data/home` in the Dockerfile: a CLI the app shells out to needs somewhere writable, and the image is not it.
|
|
|
|
Then:
|
|
|
|
- the `app:` block from [../deploy/server/compose.yaml](../deploy/server/compose.yaml) into the compose file that runs the proxy
|
|
- the variables from [../deploy/server/env.example](../deploy/server/env.example) appended to the `.env` beside it, `chmod 600`
|
|
- [../deploy/server/deploy.sh](../deploy/server/deploy.sh) and [../deploy/server/backup.sh](../deploy/server/backup.sh) next to that compose file
|
|
- the app's own `config.yaml` into `$APP_DATA/config.yaml`
|
|
- [../deploy/server/swag/app.subdomain.conf](../deploy/server/swag/app.subdomain.conf) into SWAG's `proxy-confs/`, renamed
|
|
|
|
Edit `.env` for the actual data path and UID/GID. Keep `APP_TAG=latest` for ordinary deployments or choose a published commit tag to pin.
|
|
|
|
## Deploy
|
|
|
|
```bash
|
|
bash /srv/swag/deploy.sh
|
|
```
|
|
|
|
It runs `docker compose pull app` first, and only on success runs `docker compose up -d --no-deps --pull never --wait --wait-timeout 240 app`, using that image and waiting for its `HEALTHCHECK`. Other services in the file are left alone. A failed pull stops before startup; an unhealthy startup exits nonzero. Inspect `docker compose ps` and `docker compose logs app` on failure.
|
|
|
|
**After changing credentials in `.env`, use `up -d`, not `restart`.** A restart does not update environment variables — the same container starts again with the environment it was created with. This is the single most common way an updated token appears not to have worked.
|
|
|
|
## The database
|
|
|
|
Never overwrite a live SQLite database with a plain file copy. It is in WAL mode, so the `.db` on disk is always missing whatever is still in the `-wal` beside it, and copying the three files while the app is running is a race you lose quietly: a database that opens fine and is short a day's writes.
|
|
|
|
**Backups.** `bash /srv/swag/backup.sh` takes a `VACUUM INTO` snapshot through the running container, gzips it into `$APP_DATA/backups`, and deletes everything past `KEEP` (14 by default). Schedule it with cron:
|
|
|
|
```
|
|
0 4 * * * bash /srv/swag/backup.sh >> /srv/swag/backup.log 2>&1
|
|
```
|
|
|
|
Keep an off-server copy, and test restoring it. A backup nobody has restored is a hypothesis.
|
|
|
|
**Moving a database onto the server.** `.\deploy\db.ps1 push` takes a snapshot of this machine's database, uploads it with the importer, and runs the import. The server validates the incoming file — `integrity_check` plus the tables it must have — and snapshots the live database into `/data/backups` before replacing it, atomically.
|
|
|
|
It does not stop the app and does not start it: **stop it yourself first** and start it afterwards. The import is refused while the app is up. Get the image the database needs into the registry and onto the server first, because older code refuses to open a newer schema.
|
|
|
|
If the app has accounts, importing replaces them too, so do the account setup against the final database rather than before the import.
|
|
|
|
**Taking one off.** `.\deploy\db.ps1 pull` runs the server's own `backup.sh` and downloads the newest snapshot into `backups\`. Work on a copy of it, never on a file you intend to push back: after a push the two copies diverge from the first write on either, and there is no merge for that.
|
|
|
|
## Roll back
|
|
|
|
Record the current image tag or digest before an update. Then set that commit tag in `.env` and run `deploy.sh` again. `latest` moves on publication, so it cannot name a previous release — this only works if commit-tagged images stay in the registry.
|
|
|
|
Check schema compatibility before rolling code back. If a release migrated the database incompatibly, restore a matching backup while the app is stopped. No automated rollback overwrites the database, and that is deliberate.
|
|
|
|
## Before relying on it
|
|
|
|
Verify, in this order, and write down what you saw rather than closing it from local reasoning:
|
|
|
|
1. HTTPS from outside, on the real hostname.
|
|
2. Login, and a passkey if the app has them — passkeys need `rp_id`/`origin` to match the hostname exactly.
|
|
3. The app's heaviest real operation, once, end to end.
|
|
4. Persistence: `docker compose up -d --force-recreate app`, then check the data is still there.
|
|
5. A restore of an off-server backup copy.
|
|
6. Memory under that heaviest operation, before choosing `APP_MEM`.
|
|
|
|
The health endpoint checks the web app and its store. It does not check model credentials, and a green container says nothing about whether the API key works.
|