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.
Install
Section titled “Install”-
Point a domain at your server
Create an
A(andAAAA) record such asstats.example.com. Ports 80 and 443 must be reachable for the certificate. -
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
initrefuses to overwrite any of these files unless you pass--force, which replaces the others and updates an existing.envin place, keeping its secrets. You can also copydeploy/from the repository and fill in.env.exampleyourself; every variable is described in the environment reference. -
Start it
Terminal window cd shardlens && docker compose up -ddocker compose logs -f collectorThe collector applies its database migrations, then starts listening. Open
https://stats.example.com. -
Check it
Terminal window docker compose ps # collector "healthy" after up to a minutecurl https://stats.example.com/readyz # {"ok":true} once the database is migratedThen 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.
Discord sign-in
Section titled “Discord sign-in”The dashboard accepts two kinds of sign-in:
- Read key: anyone with
SHARDLENS_READ_KEYcan 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:
- In the Developer Portal, open your application → OAuth2.
- Add the redirect
https://stats.example.com/auth/discord/callback. - Copy the client ID and secret into
.envasDISCORD_CLIENT_IDandDISCORD_CLIENT_SECRET. docker compose up -dto restart the collector.
Hardening that is already done
Section titled “Hardening that is already done”- 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.
Updating
Section titled “Updating”docker compose pull && docker compose up -d. Read Upgrading first: it says what to back up and
what changes between versions.
Backups
Section titled “Backups”Back up the database with pg_dump. See Backups.