The collector reads its configuration from environment variables (with Docker Compose, from .env). It refuses to
start when a required variable is missing or invalid, and the error names the variable without printing its value.
Empty values count as unset.
| Variable |
What it is |
DATABASE_URL |
PostgreSQL 16 or newer, for example postgres://user:password@host:5432/shardlens. Add ?sslmode=require for a managed database. Docker Compose builds it from POSTGRES_PASSWORD. |
SHARDLENS_PUBLIC_URL |
The URL people and bots use, for example https://stats.example.com. Used for sign-in redirects and links in alerts. |
SHARDLENS_APP_ID |
Your Discord application ID. The collector serves one application. |
SHARDLENS_SESSION_SECRET |
At least 32 characters. Signs the short-lived cookies of Discord sign-in (dashboard sessions themselves are random IDs stored hashed). openssl rand -base64 32 |
SHARDLENS_SETTINGS_KEY |
32 random bytes, base64. Encrypts stored secrets such as alert webhook URLs. openssl rand -base64 32 |
| Variable |
What it is |
SHARDLENS_INGEST_KEY |
An ingest key (slk_ingest_ and 43 characters) for your bot. Registered when the collector starts. |
SHARDLENS_READ_KEY |
A read key (slk_read_ and 43 characters) for read-only dashboard access, scripts and a dashboard of your own. |
SHARDLENS_ACTIVITY_KEY |
Optional. An activity key (slk_activity_ and 43 characters): reads everything a read key does, and who ran what while the collector is in audit mode. For the server side of your own dashboard only. |
Set both on a first install (npx shardlens init does). Each is registered when the collector starts;
a new value revokes the key the variable held before, so replacing one in .env and restarting is how a leaked key is
replaced, with or without the dashboard. A replaced key can’t be brought back: generate a new one. Several collector instances on one database need the same values, or each revokes the others’ keys as it starts. Keys made in Settings can’t take one of these variable names as their label. More keys can be
created and revoked in the dashboard (Settings → API keys), but Settings needs Discord sign-in, and Discord sign-in only knows your owner and
team once the bot has reported them, so a collector with neither key and no SHARDLENS_EXTRA_ADMINS can’t be opened.
The collector logs a warning at start-up when the bot or you would have no way in. Generate keys with
npx shardlens keys.
| Variable |
What it is |
DISCORD_CLIENT_ID |
OAuth2 client ID, for “Sign in with Discord”. Set it together with DISCORD_CLIENT_SECRET. |
DISCORD_CLIENT_SECRET |
OAuth2 client secret. |
DISCORD_PUBLIC_KEY |
The application’s public key (64 hex characters), to receive webhook events. |
SHARDLENS_EXTRA_ADMINS |
Comma-separated Discord user IDs allowed full dashboard access besides the application owner and team. |
| Variable |
What it is |
SHARDLENS_AUDIT_KEY |
32 random bytes, base64. Encrypts audit-mode identities. Without it, audit mode can’t be turned on. |
SHARDLENS_MODE |
Optional. privacy or audit: decides hashed or identified users here instead of in Settings → User identity, which then shows the choice but can’t change it. The way to choose audit mode when the dashboard is off. audit needs SHARDLENS_AUDIT_KEY. Give every collector instance the same value: each one sets it as it starts. |
| Variable |
Default |
What it is |
PORT |
8080 |
Port to listen on. Docker Compose, Railway and Render set it for you. |
HOST |
0.0.0.0 |
Address to listen on. Docker Compose sets it. |
SHARDLENS_TRUST_PROXY |
false |
Behind a reverse proxy or load balancer, the number of proxies in front (1 for one), so client addresses and HTTPS are seen correctly. Docker Compose uses 1 (Caddy) unless .env sets another number. true trusts the whole X-Forwarded-For header, which is only safe behind a proxy that replaces it rather than adding to it. |
SHARDLENS_DEMO |
false |
true lets anyone view the dashboard without signing in, read-only. For a public demo with seeded data only; never with real data. Settings, keys, alerts, audit data and ingest stay locked. |
SHARDLENS_DASHBOARD |
on |
off stops serving the dashboard pages: the collector is an API only, for a dashboard of your own or none. Ingest, queries, jobs, reports and alerts carry on; their Discord messages no longer link to a dashboard. |
SHARDLENS_DASHBOARD_DIR |
(bundled) |
Serve the dashboard from another folder. Mainly for development; restart the collector after rebuilding the dashboard, because it lists the files when it starts. |
LOG_LEVEL |
info |
fatal, error, warn, info, debug, trace or silent. Per-request logs, which contain URLs, are written at debug and trace only. |
| Variable |
What it is |
CLICKHOUSE_URL |
Optional. http://user:password@host:8123/database of a ClickHouse server to use as an analytics store. The database is created if missing. docker-compose.clickhouse.yml sets it. Never logged. |
| Variable |
Default |
What it is |
SHARDLENS_SINK_URL |
off |
Optional. A mongodb://, mongodb+srv://, mysql://, mariadb://, postgres:// or sqlite: URL to copy every event into. Never logged. |
SHARDLENS_SINK_TABLE |
shardlens_events |
Table or collection the copies go to. Letters, digits and underscores, up to 48 characters. |
SHARDLENS_SINK_RETENTION_DAYS |
35 |
Days copies are kept, 1 to 3,650. |
SHARDLENS_SINK_EVENTS |
every type |
Comma-separated event types to copy, for example interaction,message_command,custom. |
These are read by docker-compose.yml, not by the collector itself.
| Variable |
What it is |
SHARDLENS_DOMAIN |
The domain Caddy gets a certificate for. |
POSTGRES_PASSWORD |
Password for the bundled PostgreSQL. Letters, digits, - and _ only: it goes into DATABASE_URL. |
SHARDLENS_IMAGE |
Collector image to run. Empty or unset, the published image for the current major version. |
CLICKHOUSE_PASSWORD |
Password for the bundled ClickHouse in docker-compose.clickhouse.yml. Letters and digits only. |