Skip to content

Docker Compose

The standard deployment runs three containers on one server:

  • Caddy terminates HTTPS with an automatic certificate and forwards to the collector.
  • The collector receives events, runs the background jobs and serves the dashboard and API.
  • PostgreSQL 17 stores everything. It is never published to the host.

A small VPS (1 vCPU, 1 GB RAM) is enough for most bots.

  1. Point a domain at your server

    Create an A (and AAAA) record such as stats.example.com. Ports 80 and 443 must be reachable for the certificate.

  2. Generate the files

    Terminal window
    npx shardlens init --domain stats.example.com --app-id <your application ID>
    • Directoryshardlens/
      • docker-compose.yml
      • Caddyfile
      • .env secrets and keys, generated; never commit it
      • bot.env the bot’s two settings, to copy to where the bot runs

    init refuses to overwrite any of these files unless you pass --force, which replaces the others and updates an existing .env in place, keeping its secrets. You can also copy deploy/ from the repository and fill in .env.example yourself; every variable is described in the environment reference.

  3. Start it

    Terminal window
    cd shardlens && docker compose up -d
    docker compose logs -f collector

    The collector applies its database migrations, then starts listening. Open https://stats.example.com.

  4. Check it

    Terminal window
    docker compose ps # collector "healthy" after up to a minute
    curl https://stats.example.com/readyz # {"ok":true} once the database is migrated

    Then start your bot with the two settings from bot.env. The live tiles on the Overview count its first events within seconds; the chart and checklist follow within a minute or two, without reloading.

Behind another proxy or a CDN in front of Caddy (Cloudflare, say), set SHARDLENS_TRUST_PROXY=2 in .env, so rate limits see each visitor’s own address. Caddy alone counts as one, which is the default.

The dashboard accepts two kinds of sign-in:

  • Read key: anyone with SHARDLENS_READ_KEY can view the dashboard. Settings, keys, alerts and audit pages stay locked.
  • Sign in with Discord: the application’s owner and team members (and any IDs in SHARDLENS_EXTRA_ADMINS) get full access.

To turn on Discord sign-in:

  1. In the Developer Portal, open your application → OAuth2.
  2. Add the redirect https://stats.example.com/auth/discord/callback.
  3. Copy the client ID and secret into .env as DISCORD_CLIENT_ID and DISCORD_CLIENT_SECRET.
  4. docker compose up -d to restart the collector.
  • The collector container runs as a non-root user that can’t change the collector’s own files, with a read-only root filesystem, no Linux capabilities and no-new-privileges.
  • PostgreSQL has no published port; only the collector can reach it.
  • The dashboard is served with a strict Content Security Policy.
  • API keys are stored as SHA-256 hashes, and the settings that hold secrets (alert webhooks) are encrypted with SHARDLENS_SETTINGS_KEY.

docker compose pull && docker compose up -d. Read Upgrading first: it says what to back up and what changes between versions.

Back up the database with pg_dump. See Backups.