Skip to content

MARKDOWN SOURCE

Raw
# 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=<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

```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/<you>/totenschloss:latest
docker push ghcr.io/<you>/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/<you>/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.

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

  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/<you>/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

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.

VariableDefaultRequiredPurpose
PORT8080 locally, 80 in the imagenoHTTP port the server listens on.
STORAGE_PATHstorage locally, /storage in the imagenoDirectory for DuckDB's cache, spill files and auth.json.
LAKE_CATALOGhttps://data.deadlock-api.com/v1/catalog.ducklakenoDuckLake catalog URL. Must be https://, with no spaces or quotes.
INFERENCE_API_KEYunsetfor chat via DivineBearer key for Divine. Setting it selects Divine.
INFERENCE_APIhttp://localhost:9090with INFERENCE_API_KEYDivine base URL, for example https://divine.silenlocatelli.ch. Set this in production.
INFERENCE_MODELclaude-sonnet-5-5noModel name sent to Divine. The deployed Divine accepts gpt-5-nano and claude-haiku-5-5.
ANTHROPIC_API_KEYunsetfor chat without DivineAnthropic key, sent as x-api-key. Used only when INFERENCE_API_KEY is unset.
ANTHROPIC_MODELclaude-sonnet-5-5noModel for the direct Anthropic path.
ANTHROPIC_BASE_URLhttps://api.anthropic.comnoBase URL for the direct Anthropic path.
ADMIN_USERNAMEadminnoAdmin account name.
ADMIN_PASSWORDunsetto enable loginAdmin password, 8-256 characters. Unset leaves the site open with no login.
SESSION_TTL_HOURS168noHow long a browser session stays valid after signing in.
INVITE_TTL_HOURS168noDefault lifetime for new invites.
COOKIE_SECUREfalserecommended with HTTPSMark 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.