Self-Hosting Guide

The self-hosted community edition is free software under the GNU Affero General Public License v3. It includes end-to-end encryption, sign-in (OIDC, passkeys, browser sign-in key), repositories, the catalog, publishing, sync and federation. It does not include content moderation, upload screening, signed evidence (franking), security advisories or the audit anchor — those ship in the business and managed editions. Uploads and repositories on a community node are not screened; the operator is responsible for what the node hosts.

One runbook per platform, all with the same twelve steps (prerequisites, install, configure, first start, key ceremony, sign-in, verify, connect a client, upgrade, backup, uninstall, troubleshooting). They live in the repository under docs/runbooks/selfhost/.

The web server never holds the encryption root or the session-signing root key. Those live in separate processes with their own users and sockets; the root broker has no network at all. This is what a community node runs.

The web server reads about a hundred variables; the complete list with tiers (required, recommended, advanced, business-only, managed-only) is generated from the source into docs/generated/env.md and .env.example, and a contract test keeps them in sync. These are the ones a community node cannot boot or sign in without.

SSL is required for OIDC redirects and secure WebSocket sync. Choose your method.

# Install Caddy
sudo apt install caddy
 
# Caddyfile (auto-provisions TLS)
thumper.example.com {
    reverse_proxy localhost:3000
}

# nginx config snippet
server {
    listen 443 ssl;
    server_name thumper.example.com;
    ssl_certificate /etc/ssl/certs/thumper.pem;
    ssl_certificate_key /etc/ssl/private/thumper.key;
 
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 
    # WebSocket support for CRDT sync
    location /ws {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Thumper-Run uses Rauthy as its OIDC identity provider. Any OIDC provider that issues the expected claims should work; Rauthy is the one we test.

Initial Setup

# Provision the OIDC client for Thumper-Run
python3 scripts/rauthy-provision-client.py \
  --rauthy-url http://localhost:8080 \
  --client-name "Thumper Run" \
  --redirect-uri https://thumper.example.com/auth/callback

The script prints the client id for RAUTHY_CLIENT_ID and writes the client secret; keep the secret in a file referenced by the compose secrets block.

Logs

View logs from all services.

# All services
docker compose -f docker/docker-compose.mode5.yml logs -f
 
# Web server only
docker compose -f docker/docker-compose.mode5.yml logs -f web
 
# Set log level via RUST_LOG
RUST_LOG=debug docker compose -f docker/docker-compose.mode5.yml up web

Health Check

The web server exposes a health endpoint.

curl -fsS https://node.example.org/readyz
curl -fsS https://node.example.org/version | jq .
# {"edition": "self-hosted-community", "api_version": 1, "source_url": "...", ...}
curl -fsS https://node.example.org/api/v1/client-config | jq .node

A migration is a hard dependency: the migrator from the new release must finish before the new web starts. Migrations are forward-only; rollback means the previous web binaries against the current schema.

git fetch --tags && git checkout <new tag>
docker compose -f docker/docker-compose.mode5.yml pull
# 1. migrate first — must exit 0
docker compose -f docker/docker-compose.mode5.yml up migrate
# 2. then the web and sidecars
docker compose -f docker/docker-compose.mode5.yml up -d web
# 3. verify
curl -fsS https://node.example.org/version && curl -fsS https://node.example.org/readyz

Full procedure, including the single-binary installer and Kubernetes: docs/runbooks/selfhost/UPGRADE_AND_ROLLBACK.md.