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

+175
View File
@@ -0,0 +1,175 @@
services:
mealie:
image: ghcr.io/mealie-recipes/mealie:latest
container_name: mealie
restart: unless-stopped
# `deploy: resources: limits:` is Swarm-only and was silently ignored,
# so this container has never actually had a memory limit. This one works.
mem_limit: 1000m
# Was 9925:9000 on every interface — the internet, if the firewall is ever
# wrong. SWAG reaches it by container name on the shared network; this is
# only the fallback for when you are on the box itself.
ports:
- "127.0.0.1:9925:9000"
# Was a Docker-managed volume under /var/lib/docker, root-owned and
# invisible. A plain directory next to this file, so a backup is `tar`.
volumes:
- /srv/data/mealie:/app/data
environment:
ALLOW_SIGNUP: "false"
PUID: 1000
PGID: 1000
TZ: Europe/Brussels
MAX_WORKERS: 1
WEB_CONCURRENCY: 1
BASE_URL: https://mealie.rittershofer.org
# From .env, chmod 600. Never in this file.
OPENAI_API_KEY: ${OPENAI_API_KEY:?set OPENAI_API_KEY in .env}
# A base, not an endpoint. The old /v1/models made it request
# /v1/models/chat/completions.
OPENAI_BASE_URL: https://api.openai.com/v1
logging:
driver: json-file
options:
max-size: "20m"
max-file: "5"
gitea:
image: gitea/gitea:latest
container_name: gitea
restart: unless-stopped
environment:
- USER_UID=1000
- USER_GID=1000
volumes:
- /srv/data/gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
logging:
driver: json-file
options:
max-size: "20m"
max-file: "5"
newsdesk:
image: ${NEWSDESK_IMAGE:?set NEWSDESK_IMAGE in .env}:${NEWSDESK_TAG:-latest}
container_name: newsdesk
restart: unless-stopped
user: "${PUID:-1000}:${PGID:-1000}"
volumes:
- /srv/data/newsdesk:/data
environment:
TZ: ${TZ:-Europe/Berlin}
CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN:-}
ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
NEWSDESK_PASSWORD: ${NEWSDESK_PASSWORD:-}
mem_limit: ${NEWSDESK_MEM:-0}
logging:
driver: json-file
options:
max-size: "20m"
max-file: "5"
bookly:
image: git.rittershofer.org/wolf/bookly:${BOOKLY_TAG:-latest}
container_name: bookly
restart: unless-stopped
user: "1000:1000"
volumes:
- /srv/data/bookly:/data
environment:
TZ: Europe/Brussels
# Required: without it the demo would be open to anyone who finds the hostname, so Compose refuses to start.
BOOKLY_PASSWORD: ${BOOKLY_PASSWORD:?set BOOKLY_PASSWORD in .env}
# subscription: the Claude CLI with CLAUDE_CODE_OAUTH_TOKEN (same variable newsdesk reads).
# api: ANTHROPIC_API_KEY, billed per token, lower latency.
BOOKLY_BACKEND: ${BOOKLY_BACKEND:-subscription}
CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN:-}
ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
# No `ports:`. SWAG reaches :8000 by container name; nothing else can.
mem_limit: 0
logging:
driver: json-file
options:
max-size: "20m"
max-file: "5"
health:
image: ${HEALTH_IMAGE:?set HEALTH_IMAGE in .env}:${HEALTH_TAG:-latest}
container_name: health
restart: unless-stopped
# Warehouse, journal, job table, speech models, tiles, backups: all of it
# under one host directory, so a backup is one target.
volumes:
- ${HEALTH_DATA:-./data/health}:/data
user: "${PUID:-1000}:${PGID:-1000}"
environment:
TZ: ${TZ:-Europe/Berlin}
HEALTH_TIMEZONE: ${TZ:-Europe/Berlin}
# Which model writes the evening entry. The subscription token now; add
# ANTHROPIC_API_KEY and `docker compose up -d health` (not `restart`)
# to move to the API. Shared with the other services in this file.
CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN:-}
ANTHROPIC_API_KEY: ${HEALTH_ANTHROPIC_API_KEY:-}
# Normally empty. Set it to pin the password -- the way back in when a
# login is lost -- then empty it and recreate to hand the password back
# to the Settings page.
HEALTH_PASSWORD: ${HEALTH_PASSWORD:-}
# The speech model. `small` (0.7 GB) if turbo (1.9 GB while it runs)
# does not fit beside everything else on the box.
HEALTH_WHISPER_MODEL: ${HEALTH_WHISPER_MODEL:-large-v3-turbo}
# No `ports:` and no `networks:`: SWAG reaches it by name on this file's
# network, and nothing else reaches it at all.
# `deploy: resources: limits:` is Swarm-only and ignored here. 0 is
# unlimited until a transcription has been watched on the box.
mem_limit: ${HEALTH_MEM:-0}
logging:
driver: json-file
options:
max-size: "20m"
max-file: "5"
swag:
image: lscr.io/linuxserver/swag:latest
container_name: swag
cap_add:
- NET_ADMIN
environment:
- PUID=1000
- PGID=1000
- TZ=Europe/Brussels
- URL=rittershofer.org
- VALIDATION=http
# Commas and nothing else — SWAG splits on the comma alone, so a space
# asks for a hostname with a leading space. `news` added for newsdesk;
# `collabora` dropped, since nothing serves it any more.
- SUBDOMAINS=www,mealie,git,news,play,body
- ONLY_SUBDOMAINS=false
volumes:
- /etc/config/swag:/config
ports:
- 443:443
- 80:80
logging:
driver: json-file
options:
max-size: "20m"
max-file: "5"
restart: unless-stopped
+112
View File
@@ -0,0 +1,112 @@
# Deploying a service to rittershofer.org
The ground every service on this box shares: what the box is, the seven steps to add a service to it, the templates those steps need, and the things that have already gone wrong. [release.md](release.md) is how an image gets built and published; [server.md](server.md) is what happens once it has been.
`<app>` below is your *service's* name: the hostname, the data directory, the image tag, the compose service. It is the one thing you choose. The Python package stays `app` and the environment variables stay `APP_`, here and in every project started from this repository — nothing inside the checkout is renamed, and the files these steps need are already in place under `deploy/`.
## What the box is
A single Hetzner server running Ubuntu 24.04 on x86_64, with a 37 GB root filesystem and no separate data disk. One Docker Compose project holds everything.
/srv/swag/docker-compose.yml every service, one file, project name `swag`
/srv/swag/.env every secret, chmod 600, never in the compose file
/srv/data/<app>/ every service's data, owned 1000:1000
/etc/config/swag/ SWAG's /config: nginx confs, certificates, logs
A snapshot of that whole compose file, every neighbour included, is [box-docker-compose.yml](box-docker-compose.yml): what a new service block lands beside, and where the SWAG subdomain list lives.
`swag` is nginx, certbot and fail2ban in one container. It terminates TLS for every hostname and proxies to the others **by container name** over the project's default network. That shared network is the only reason all these services live in one compose file — nothing else about them is related.
Images are published to the Gitea instance on the same box, at `git.rittershofer.org/wolf/<app>`. Everything runs as uid/gid 1000 and `TZ=Europe/Brussels`.
Which compose file that is comes off the running container rather than out of memory:
```bash
docker inspect swag --format '{{index .Config.Labels "com.docker.compose.project.config_files"}}'
```
Declaring the network `external` from a second Compose project would work too, and would hardcode the first project's name into the second — a rename away from a confusing failure.
## The seven steps
**1. DNS.** `<app>.rittershofer.org` must resolve to the server *before* anything else. Confirm with `getent hosts <app>.rittershofer.org`.
**2. Certificate.** Add `<app>` to `SUBDOMAINS` in the swag service's environment. That list separates on commas and nothing else — a space after one asks for a hostname with a leading space. SWAG runs certbot on every container start and requests **one certificate covering every name in the list**, so a name that does not answer on port 80 fails the whole request and leaves the existing names unrenewed. This is why step 1 comes first. Restart swag, then check `docker logs swag` for the issuance. If SWAG already holds a wildcard certificate covering the name, reuse it and skip this step entirely.
**3. Registry login.** On the build machine a Gitea token with package **write**; on the server, package **read**. Same command both ends, token at the password prompt:
```bash
docker login git.rittershofer.org -u wolf
```
Git credentials and Docker registry credentials are separate. A successful Git push does not log Docker in.
**4. Data directory.** Root's `mkdir` produces a root-owned directory, and the container runs as 1000, so the chown is not optional:
```bash
sudo mkdir -p /srv/data/<app> && sudo chown -R 1000:1000 /srv/data/<app>
```
**5. Service block** from [../deploy/server/compose.yaml](../deploy/server/compose.yaml) into `/srv/swag/docker-compose.yml`, and the variables from [../deploy/server/env.example](../deploy/server/env.example) appended to `/srv/swag/.env`.
**6. Proxy conf** — [../deploy/server/swag/app.subdomain.conf](../deploy/server/swag/app.subdomain.conf) renamed to `<app>.subdomain.conf` in `/etc/config/swag/nginx/proxy-confs/`. SWAG's `/config` is a host directory bind-mounted into the container; read the host side off the running container rather than assuming where it is:
```bash
docker inspect swag --format '{{range .Mounts}}{{if eq .Destination "/config"}}{{.Source}}{{end}}{{end}}'
```
<config>/nginx/proxy-confs/ the per-site confs, where yours goes
<config>/nginx/proxy.conf the shared defaults every site includes
<config>/nginx/ssl.conf certificate paths and TLS settings
<config>/nginx/resolver.conf Docker's internal DNS
<config>/etc/letsencrypt/live/ the certificates themselves
Then validate, and reload only if validation passes:
```bash
docker exec swag nginx -t && docker exec swag nginx -s reload
```
Confirm the other sites still respond afterwards.
**7. Deploy.** Name the service, so nothing else in the file is recreated:
```bash
cd /srv/swag && docker compose up -d <app>
```
## What the templates already decide for you
Both templates are in [../deploy/server/](../deploy/server), commented in place. The decisions worth knowing before you read them:
**No `ports:`.** SWAG reaches the container by name on the project network. That is what keeps the app's port off the internet even if the firewall is wrong.
**No `networks:` either.** Being in that compose file is what puts it on the right one.
**`user: "1000:1000"`.** Container uid is host uid — there is no translation layer. Without this the process runs as whatever the image declares, usually root, and everything it writes into `/srv/data` lands root-owned.
**`mem_limit:`, not `deploy: resources: limits:`.** The latter is Swarm-only and silently ignored by `docker compose up`. 0 is unlimited, which is the honest default until the box has been watched under real load.
**`logging:` with a size cap.** Without it, json-file logs grow until the disk does not.
**`listen 443 ssl` without `http2`.** `http2 on;` is set once at `http` scope in `nginx.conf`, and the `listen ... http2` parameter is deprecated in nginx 1.25 and later.
**`proxy_read_timeout 86400s`** only if the app holds a WebSocket open. SWAG's `proxy.conf` already sets the Upgrade headers; what it also sets is a read timeout of a couple of minutes, which closes an idle socket on the minute. Delete those two lines if there is no socket.
## Things that have already bitten
**Disk.** 37 GB, and it has been full. Three causes, all recurring: `:latest` orphans the previous image on every pull and nothing cleans them up (a weekly `docker image prune -f` cron handles it — no `-a`, so pinned images survive); journald defaults to 10% of the filesystem and is capped here at 200 MB; and VS Code Remote installs a fresh server per version under `~/.vscode-server` forever.
**`cp -a "$SRC/."` with an unset `SRC`** copies the root filesystem. Use `"${SRC:?}"` and echo the value before running anything destructive with it.
**SWAG never touches your live confs**, only the `.sample` files beside them. That is deliberate and it means they drift for years. Diff them occasionally:
```bash
cd /etc/config/swag/nginx && for f in *.conf site-confs/*.conf proxy-confs/*.subdomain.conf; do echo "=== $f"; diff "$f" "$f.sample"; done
```
Take the samples wholesale and re-apply your own edits. `nginx.conf` and the site/proxy confs must be updated **together** — older ones include `ssl.conf` at `http` scope, newer ones per server block, and mixing the two produces `no "ssl_certificate" is defined`.
**SQLite is never safe to copy live.** Stop the container, or snapshot with `VACUUM INTO` through the running one. A `cp` of a WAL-mode database is a coin toss. See [server.md](server.md#the-database).
**Secrets in `.env`, never in the compose file.** It is easy to paste a compose file into a chat window; it is harder to do that by accident with a file you had to `cat` deliberately.
+241
View File
@@ -0,0 +1,241 @@
# Asking Claude, from a deployed app
One question — *ask Claude this, get JSON back* — and two ways to answer it, chosen by which credential is present in the environment. The caller asks without knowing which one ran.
api One call to the Claude API. Wants ANTHROPIC_API_KEY. No local
install, no subprocess, per-token billing. The unattended path.
claude_code The Claude Agent SDK drives the `claude` CLI, on the
subscription it is signed in with, authenticated by
CLAUDE_CODE_OAUTH_TOKEN. Nothing billed per token.
This is the reusable part of the deployment: the compose file passes both variables through, the app prefers the key when there is one, and switching from the subscription to the API is a line in `.env` and `docker compose up -d` — no rebuild, no code change.
## The two credentials
**`CLAUDE_CODE_OAUTH_TOKEN`** comes from `claude setup-token`, run interactively on a machine you are already signed in on. It lasts a year. Generating it needs browser authorization, so no deployment script can automate it — you produce it on your laptop and paste it into the server's `.env` with an editor. Then `docker compose up -d app`, because a `restart` will not pick it up.
**`ANTHROPIC_API_KEY`** is per-token billing from the Console. Nothing to renew, nothing to sign in to, and it is what production should run on once the thing is real.
Set one. If both are set, `auto` takes the key. Neither, and every call fails with a notice naming the reason, which is the correct outcome — better a batch that fails saying "no credentials" than one that waits for a human who is not there.
The API key and the OAuth token are not interchangeable and do not substitute for each other. `ANTHROPIC_API_KEY` in the environment does not make the CLI work, and an OAuth token does not authenticate an API call.
**Neither belongs in the image or in the compose file.** They live in the `.env` beside it, `chmod 600`, injected as environment variables at container creation. A compose file gets pasted into chat windows; a file you had to `cat` deliberately does not.
## Why there is a `backend` setting and not just detection
Detection answers "what can run here". The setting answers "what should". They differ in two cases worth naming: forcing `api` on a machine that also has the CLI, so a benchmark measures the thing you meant; and `off`, which makes everything needing a model fail on purpose, with a notice that says which switch did it. An app that silently degrades to no-model is worse than one that stops.
## What the `claude_code` path deliberately does not get
No tools (`tools=[]`, `allowed_tools=[]`), no filesystem settings (`setting_sources=None`, so no CLAUDE.md, no skills, no MCP servers leak into a classification call), no session to resume. One text-in, JSON-out turn — the same shape as the API call it stands in for. The CLI is built for agent work, and left to its defaults it will bring all of that with it.
## Thinking has to be stated, not defaulted
The CLI thinks unprompted; the Messages API thinks only when asked. So "say nothing about thinking" means opposite things on the two sides, and the two backends stop being interchangeable. State it explicitly to both. It is not a small difference: on a batch of twenty-five short classifications, the CLI's default cost 128 s against 17 s for the same answers.
Some models support manual extended thinking only and reject `adaptive`. Check before spending a call, not after.
## Both take the same JSON schema
The Agent SDK accepts the Messages API's `json_schema` output format and hands the parsed object back on `ResultMessage.structured_output`. That is what makes this two backends rather than two implementations: neither path is the degraded one, and moving between them is a config line.
## Reference implementation
Self-contained — no imports from your project, both SDKs optional. It is the shape, not the whole thing: the real one in newsdesk also streams partial answers out for a progress bar, retries, and classifies API errors by status code so a 401 and a 429 tell you different things.
```python
"""Ask Claude a question, constrained to a JSON schema, get a dict back.
Two backends, one seam. `ANTHROPIC_API_KEY` selects the API; otherwise the
Claude Agent SDK drives the `claude` CLI on a subscription, authenticated by
`CLAUDE_CODE_OAUTH_TOKEN`. Both are optional dependencies:
uv pip install anthropic # the api backend
uv pip install claude-agent-sdk # the claude_code backend
"""
from __future__ import annotations
import asyncio
import importlib.util
import json
import os
from dataclasses import dataclass
from typing import Any
class AgentError(Exception):
"""The backend was there and the call still did not produce an answer."""
@dataclass(slots=True)
class AgentConfig:
#: "auto", "api", "claude_code", or "off" to make every call fail.
backend: str = "auto"
model: str = "claude-haiku-4-5-20251001"
timeout: float = 300.0
max_tokens: int = 8192
#: "off" or "adaptive". Stated to both backends, never defaulted.
thinking: str = "off"
@dataclass(slots=True)
class Reply:
data: dict[str, Any]
backend: str
model: str
usage: dict[str, Any]
def backend(settings: AgentConfig) -> str:
"""Which backend will answer, or "" for nobody."""
if settings.backend == "off":
return ""
if settings.backend in ("api", "claude_code"):
return settings.backend
if any(os.environ.get(name) for name in
("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_PROFILE")):
return "api"
# The SDK bundles its own `claude`, so having the package is enough. Not
# proof the call will work — the CLI may be signed out — but that surfaces
# as an AgentError on the call, which the caller handles anyway.
if importlib.util.find_spec("claude_agent_sdk") is not None:
return "claude_code"
return ""
def _thinking(setting: str) -> dict[str, str]:
return {"type": "adaptive"} if setting == "adaptive" else {"type": "disabled"}
def ask_json(settings: AgentConfig, *, system: str, question: dict[str, Any],
schema: dict[str, Any]) -> Reply:
"""Ask `question`, constrained to `schema`, and return the parsed answer.
`system` should be byte-identical across the calls in a run — it is what
the API path caches. `question` is the part that changes.
"""
name = backend(settings)
if not name:
raise AgentError("no model backend is available: set ANTHROPIC_API_KEY "
"or install claude-agent-sdk with CLAUDE_CODE_OAUTH_TOKEN")
if name == "api":
return _ask_api(settings, system, question, schema)
return _ask_claude_code(settings, system, question, schema)
def _ask_api(settings: AgentConfig, system: str, question: dict[str, Any],
schema: dict[str, Any]) -> Reply:
try:
import anthropic
except ImportError as exc:
raise AgentError("the anthropic SDK isn't installed") from exc
try:
client = anthropic.Anthropic(timeout=settings.timeout)
response = client.messages.create(
model=settings.model,
max_tokens=settings.max_tokens,
# The instructions are byte-identical across every call; only the
# payload below changes. Caching them is most of the saving.
system=[{"type": "text", "text": system,
"cache_control": {"type": "ephemeral"}}],
messages=[{"role": "user", "content": json.dumps(question)}],
thinking=_thinking(settings.thinking),
output_config={"format": {"type": "json_schema", "schema": schema}},
)
except anthropic.APIError as exc:
# Carry the status through in the text: 401 ("your key is wrong") and
# 429 ("slow down") want different reactions, and the message body
# alone does not always separate them.
status = getattr(exc, "status_code", "")
raise AgentError(f"the API call failed: {status} {exc}".strip()) from exc
text = next((b.text for b in response.content if b.type == "text"), "")
return Reply(data=json.loads(text), backend="api",
model=response.model or settings.model,
usage=response.usage.model_dump() if response.usage else {})
def _ask_claude_code(settings: AgentConfig, system: str, question: dict[str, Any],
schema: dict[str, Any]) -> Reply:
try:
from claude_agent_sdk import (
ClaudeAgentOptions, ClaudeSDKError, ResultMessage, query,
)
except ImportError as exc:
raise AgentError("the Claude Agent SDK isn't installed") from exc
options = ClaudeAgentOptions(
system_prompt=system,
model=settings.model or None,
# A classification call, not an agent: nothing to run, nothing to read,
# and no project settings — so no CLAUDE.md, no skills and no MCP
# servers get in front of the model on the way to an answer.
tools=[],
allowed_tools=[],
permission_mode="dontAsk",
setting_sources=None,
thinking=_thinking(settings.thinking),
output_format={"type": "json_schema", "schema": schema},
# The API takes max_tokens as a parameter; the CLI takes it only as an
# environment variable. Without this the setting is quietly API-only.
# The SDK merges this into the inherited environment rather than
# replacing it, so naming one variable does not cost the CLI its PATH.
env={"CLAUDE_CODE_MAX_OUTPUT_TOKENS": str(settings.max_tokens)},
)
async def ask() -> Reply:
answer: Reply | None = None
async for message in query(prompt=json.dumps(question), options=options):
if not isinstance(message, ResultMessage):
continue
if message.is_error:
raise AgentError("; ".join(message.errors or []) or message.result
or f"the agent ended as {message.subtype}")
data = message.structured_output
if not isinstance(data, dict):
# Ended without structured output — a limit, an interruption.
# `result` is the raw text if there is any, worth one attempt.
data = json.loads(message.result or "")
answer = Reply(data=data, backend="claude_code",
model=settings.model, usage=message.usage or {})
if answer is None:
raise AgentError("the agent returned no result")
return answer
try:
# asyncio.run, so this is a synchronous call like the other backend.
# From inside a running loop, await `ask()` directly instead.
return asyncio.run(asyncio.wait_for(ask(), settings.timeout))
except TimeoutError as exc:
raise AgentError(f"no answer within {settings.timeout:.0f}s") from exc
except ClaudeSDKError as exc:
# The SDK has its own exception hierarchy — a CLI that exited, a line
# it could not parse, an answer that overran max_tokens — and none of
# it is an AgentError. Left alone, those escape a caller that catches
# AgentError per item and take down a whole run. Every failure of this
# backend is an AgentError or none of them are.
raise AgentError(str(exc)) from exc
```
Using it:
```python
settings = AgentConfig()
schema = {
"type": "object",
"properties": {"tags": {"type": "array", "items": {"type": "string"}}},
"required": ["tags"],
}
reply = ask_json(settings, system="Tag this article. Answer with the schema.",
question={"title": title, "body": body}, schema=schema)
print(reply.data["tags"], reply.backend)
```
## The two failures that will actually happen
**A changed token in `.env` appears to do nothing.** `docker compose restart` does not update environment variables. `docker compose up -d app` recreates the container, which does.
**The token expired and nothing said so.** The setup token lasts a year, and the failure looks like a model call failing rather than a credential problem. Read the error text — this is why the SDK's own message is passed through intact rather than summarised into "model call failed".
+106
View File
@@ -0,0 +1,106 @@
# One password, on the open internet
The shape used by a single-user app that has to sit on a public hostname because that is where the browser is. No user management, no usernames, no registration: one password and the sessions it opens. Everything below is about making that enough.
This is the reasoning; `auth/` in this repository is the code, already written and already wired into `app/main.py`. `auth/README.md` is the ten-minute version of how to take the folder somewhere else.
## Locked by what it is bound to, not by a flag
The switch is the bind address. On `127.0.0.1` the door is already the machine's own login, and asking for a password again is theatre. On `0.0.0.0` it is reachable from elsewhere and locks itself.
Deriving it rather than configuring it removes the failure that looks fine: "deployed it, forgot to switch auth on". The production config then says `enabled: always` anyway — redundant with the bind address and worth saying out loud.
```yaml
auth:
enabled: always # auto | always | never
session_days: 30
# `auto` marks the cookie Secure when the request arrived over HTTPS. Behind
# a TLS-terminating proxy the app only ever sees plain HTTP and cannot work
# that out, so behind SWAG this must be `always`.
secure_cookie: always
```
## The password itself
Stored as an scrypt hash, never in the config file. The first locked start either takes `APP_PASSWORD` from the environment or generates one and prints it to the log once. After that it is the app's own Account screen that changes it.
`APP_PASSWORD` is the way back in when a login is lost, and it is authoritative while it is set — the Account screen refuses to change what the environment pins. Set it, get in, empty it, recreate the container, then change the password in the app.
Two consequences worth writing down: a generated password is printed to the container log, so the retained log holds it until it rotates — rotate the password once you are in. And a password the *user* chooses is the weak spot, not the lockout: a minimum length of 8 is a very different thing from the 16 random characters the app generates.
## The lockout
Five wrong answers are free — past a typo and a stale password manager entry, short of anything systematic. After that each attempt waits, starting at 30 s and doubling to a ceiling of 15 minutes. That is about a hundred guesses a day against a secret with far more than a hundred possibilities, which is what "guessing is pointless" means in practice.
Three details that matter more than the numbers:
**Read the lockout before checking the password, not after.** Otherwise a fast attacker extends their own lockout forever and never notices, and — more to the point — an honest person hammering the button digs a deeper hole with every press.
**A wrong answer still costs a full scrypt derivation.** The delay an attacker meets is the one the honest user meets, and it is what lets the free-attempt count be as generous as it is.
**Cap the doubling.** `30s * 2**failures` with an uncapped counter eventually overflows whatever holds it, and a bot that has sent ten thousand guesses turns every future login attempt into a 500 — a denial of service delivered by arithmetic.
## One counter, not one per address
The obvious improvement is to lock out the address that is guessing, so a stranger cannot keep the owner waiting at their own door. Behind a proxy it cannot be built honestly: the only address the app sees is the one the proxy puts in a header, the peer is a container on the same Docker network, and a header is set by whoever is talking. Keyed on that, an attacker gets a fresh, empty counter per request by editing one line of their own request, while the owner still gets locked out by their own typos. Strictly worse, and it would look like protection.
So the address is **logged, not decided from** — at the layer that knows who connected, the decision can be made properly. See the throttling section below.
The honest cost of one global counter: an attacker hammering the door keeps password login locked for the owner too. A passkey login that skips the lockout is what makes that survivable.
## Sessions
One kind of session whichever door opened it, so revoking and expiry have one implementation. A row per session with its user agent and last-seen time, a screen listing them, a button to revoke one and a button to close all the others. `purge()` on startup drops the expired ones — otherwise that table grows forever.
The cookie: `HttpOnly` so an XSS cannot read it, `Secure` per the config above, `SameSite=Lax`, `path=/`.
**No CSRF token, and that is a decision rather than an omission.** A CSRF token defends a cookie-authenticated app against another origin submitting a form on your behalf. `SameSite=Lax` already refuses to send the cookie on any cross-site request that is not a top-level navigation, and if no `GET` in the app changes anything, the attack the token would stop cannot be mounted. Adding one anyway means a second secret, a second thing to rotate, and a second way for a request to fail that the UI has to explain. Where that reasoning stops holding is a browser old enough to ignore `SameSite` entirely.
## Passkeys
Here already, behind the `passkeys` extra: `uv sync --all-extras`, and without it the routes answer 501 and the Account tab simply does not draw the section.
A passkey and a security key are one feature: a YubiKey registers through the same flow as a phone, because to WebAuthn they are the same thing.
A passkey is bound to an origin, and that binding is what makes it unphishable — the browser only hands the credential back to the origin that created it. So it needs HTTPS and a real hostname, with `localhost` the one exception, which is what lets it be tried before deploying. Behind a proxy, state both explicitly:
```yaml
auth:
rp_id: app.rittershofer.org
rp_name: app
origin: https://app.rittershofer.org
```
Left blank they are derived from the request, which behind a TLS-terminating proxy derives `http://` and rejects every ceremony as an origin mismatch. Changing `rp_id` later invalidates every key already registered against the old one.
**The password does not go away**, deliberately: it is the way back in if a key is lost, which is why revoking a passkey can never lock you out.
## Throttling a stranger who is guessing
The lockout already makes the secret safe. What is left is keeping the door usable for you, and keeping the traffic off the app. Two layers, in the order worth adding them:
**1. Rate limit in nginx.** Five lines in the proxy conf, included in [../deploy/server/swag/app.subdomain.conf](../deploy/server/swag/app.subdomain.conf). Per-address, no state to manage, no capabilities, and it cannot lock you out — it just makes requests wait. This is the part that earns its place.
**2. fail2ban, only if a real attack turns up.** SWAG ships it. It reads nginx's access log, where the address is the one that actually connected rather than a header, and bans in the firewall across every service on the box. A filter matching the login routes with a 401/403/429 status, and a jail pointing at `/config/log/nginx/access.log`, is about ten lines.
What fail2ban adds over the throttle is narrow and worth being honest about: your own password login stays usable during an attack, the ban covers the whole box rather than one site, and you get a list of who has been banned. It adds no protection of the password — that is already done. Against that it costs `NET_ADMIN` on the SWAG container, a regex that breaks silently if the log format changes, and an unban procedure for when it catches you.
Add it with a real log sample to test the regex against:
```bash
docker exec swag fail2ban-regex /config/log/nginx/access.log /config/fail2ban/filter.d/app.conf
```
If the domain is proxied through Cloudflare, nginx logs Cloudflare's addresses and a ban hits Cloudflare rather than the attacker. Check that before building anything on top of the log.
## What to log
One WARNING line per refusal, with the address first after `from`, so a filter is one regex:
```
WARNING auth.router: wrong password from 203.0.113.9
```
The log is the record. A second table of attempts in the database would only ever disagree with it. If the app is run at `log_level="warning"` there is no access log of its own, which makes this the whole record of who is knocking.
The forwarded address is the one piece of a stranger's own writing that ends up in that log, so strip it to the characters an address is made of before writing it. A line in this log is something a filter reads and a person believes, and neither should be forgeable by whoever is knocking.
+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.
+75
View File
@@ -0,0 +1,75 @@
# 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.