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, 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).
- 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):
# Chat model: Divine (preferred) or Anthropic directly
INFERENCE_API=https://divine.silenlocatelli.ch
INFERENCE_API_KEY=<divine key>
INFERENCE_MODEL=gpt-5-nano
# Web login (the admin account comes from these two values)
ADMIN_USERNAME=admin
ADMIN_PASSWORD=<long random 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
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:
docker tag totenschloss:latest ghcr.io/<you>/totenschloss:latest
docker push ghcr.io/<you>/totenschloss:latest
4a. Deploy with once
- Install once on the host:
curl https://get.once.com | sh, then runonce. - Choose to add an app and enter the image path, for example
ghcr.io/<you>/totenschloss:latest. - Enter the hostname, for example
totenschloss.example.com, and create a DNSArecord for it to the host IP. - once fetches the image, starts the app, and shows the dashboard. Check that
https://totenschloss.example.com/upreturnsok.
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
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:
- Choose how long the invite should last (1, 7 or 30 days) and create it.
- Copy the
/signup?invite=…link and send it to one person. - 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 /upreturnsok. - Data:
/storageholds the DuckDB extension cache, spill files, andauth.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_playertable must filterstart_timeormatch_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.