Skip to content

Collector environment

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.