# Deploying Totenschloss Totenschloss is one container: the Zig server with DuckDB linked in, and the embedded web app. It listens on port 80, serves `GET /up` for health checks, and keeps its state in `/storage`. Deploy it with [once](https://github.com/basecamp/once), or run the image with Docker directly. ## 1. Prerequisites - A Linux host with Docker, and a DNS name for the app (for example `totenschloss.example.com`). - An Anthropic key, or a Divine deployment with its key (see [Environment](#environment)). - A long password for the admin account. ## 2. Configure Create `.env` next to the Dockerfile (never commit it; it is git-ignored and excluded from the image): ```sh # Chat model: Divine (preferred) or Anthropic directly INFERENCE_API=https://divine.silenlocatelli.ch INFERENCE_API_KEY= INFERENCE_MODEL=gpt-5-nano # Web login (the admin account comes from these two values) ADMIN_USERNAME=admin ADMIN_PASSWORD= COOKIE_SECURE=true ``` `ADMIN_PASSWORD` turns on login. Without it the site stays open to anyone, which is useful for a local trial but not for a public deployment. The admin account is not stored on disk: it is checked against the environment on every sign-in, so rotating the password means updating `.env` and restarting the container. `ADMIN_USERNAME` defaults to `admin`. `COOKIE_SECURE=true` marks the session cookie `Secure`; set it whenever the site is served over HTTPS (the request's `X-Forwarded-Proto: https` header also enables it automatically). ## 3. Build the image ```sh docker build -t totenschloss:latest . ``` The build compiles for baseline x86-64 and links DuckDB and libstdc++ into the binary, so the image carries no `libduckdb.so` and the binary also runs on hosts older than the build machine. To run it on any host that can pull images, push it to a registry: ```sh docker tag totenschloss:latest ghcr.io//totenschloss:latest docker push ghcr.io//totenschloss:latest ``` ## 4a. Deploy with once 1. Install once on the host: `curl https://get.once.com | sh`, then run `once`. 2. Choose to add an app and enter the image path, for example `ghcr.io//totenschloss:latest`. 3. Enter the hostname, for example `totenschloss.example.com`, and create a DNS `A` record for it to the host IP. 4. once fetches the image, starts the app, and shows the dashboard. Check that `https://totenschloss.example.com/up` returns `ok`. Open question: once's documented setup covers the image path and hostname, but not how to pass custom variables such as `INFERENCE_API_KEY` or `ADMIN_PASSWORD`. Check the dashboard settings (`s`). If there is no field for them, the values have to be supplied another way before the chat or login will work. ## 4b. Deploy with Docker directly ```sh docker run -d --name totenschloss --restart unless-stopped \ -p 8080:80 --env-file .env \ -v totenschloss-data:/storage \ totenschloss:latest curl http://localhost:8080/up # ok ``` Put a TLS-terminating proxy in front of it for HTTPS. ## 5. Accounts and invites Sign in at `/` with `ADMIN_USERNAME` and `ADMIN_PASSWORD`. Admins get an **Invites** button: 1. Choose how long the invite should last (1, 7 or 30 days) and create it. 2. Copy the `/signup?invite=…` link and send it to one person. 3. That person opens the link, picks a username and a password (at least 8 characters), and is signed in. Invites are single-use, stored as hashes, and can be revoked before they are used. Users and invites live in `/storage/auth.json` (mode `0600`); passwords are PBKDF2-HMAC-SHA256 hashes with a random salt per user. Sessions are kept in memory, so restarting the container signs everyone out; the accounts themselves survive. ## 6. Operations - **Health**: `GET /up` returns `ok`. - **Data**: `/storage` holds the DuckDB extension cache, spill files, and `auth.json`. Back it up if you care about the accounts; deleting it removes all users and invites (the env admin still works). - **Update**: build and push a new image, then restart (`docker restart totenschloss`) or update it in once. - **Logs**: `docker logs -f totenschloss`. - **Limits**: 4 chats at once (extra requests get HTTP 429), 30 s per query, 45 s per answer, 1 GB memory per query session. Scans of the huge `lake.match_player` table must filter `start_time` or `match_id`; unbounded scans are refused before data files are downloaded. Each chat opens a fresh session against the lake, so the first answer after a restart may take longer while the extensions load. ## Environment All variables are read once at startup. Empty values count as unset. | Variable | Default | Required | Purpose | | --- | --- | --- | --- | | `PORT` | `8080` locally, `80` in the image | no | HTTP port the server listens on. | | `STORAGE_PATH` | `storage` locally, `/storage` in the image | no | Directory for DuckDB's cache, spill files and `auth.json`. | | `LAKE_CATALOG` | `https://data.deadlock-api.com/v1/catalog.ducklake` | no | DuckLake catalog URL. Must be `https://`, with no spaces or quotes. | | `INFERENCE_API_KEY` | unset | for chat via Divine | Bearer key for Divine. Setting it selects Divine. | | `INFERENCE_API` | `http://localhost:9090` | with `INFERENCE_API_KEY` | Divine base URL, for example `https://divine.silenlocatelli.ch`. Set this in production. | | `INFERENCE_MODEL` | `claude-sonnet-5-5` | no | Model name sent to Divine. The deployed Divine accepts `gpt-5-nano` and `claude-haiku-5-5`. | | `ANTHROPIC_API_KEY` | unset | for chat without Divine | Anthropic key, sent as `x-api-key`. Used only when `INFERENCE_API_KEY` is unset. | | `ANTHROPIC_MODEL` | `claude-sonnet-5-5` | no | Model for the direct Anthropic path. | | `ANTHROPIC_BASE_URL` | `https://api.anthropic.com` | no | Base URL for the direct Anthropic path. | | `ADMIN_USERNAME` | `admin` | no | Admin account name. | | `ADMIN_PASSWORD` | unset | to enable login | Admin password, 8-256 characters. Unset leaves the site open with no login. | | `SESSION_TTL_HOURS` | `168` | no | How long a browser session stays valid after signing in. | | `INVITE_TTL_HOURS` | `168` | no | Default lifetime for new invites. | | `COOKIE_SECURE` | `false` | recommended with HTTPS | Mark the session cookie `Secure`. Also automatic when the request arrives with `X-Forwarded-Proto: https`. | Without `INFERENCE_API_KEY` or `ANTHROPIC_API_KEY`, chat is disabled. `/sql` and `/tables` still work. Fixed values (not configurable yet): 30 s query timeout, 1 GB memory per session, 4 concurrent chats.