Configuration
Every environment variable the hub reads, with its default.
All configuration is environment variables in .env. .env.example in the hub repository lists them
with their defaults. One deployment serves one guild; another clan runs its own hub with its own values.
Hub
| Variable | Default | Purpose |
|---|---|---|
APP_URL | (required) | The public origin, such as https://hub.example.com. It must include the scheme and have no path; the hub refuses to start otherwise. Players paste this URL into the plugin, which appends /api/osrs-data/pair and /api/osrs-data/events. |
HUB_NAME | osrs-data-hub | The connection name players see in the plugin (up to 64 characters). |
MIN_PLUGIN_VERSION | 1.5 | Older HA Exporter versions are refused at pairing, and the wizard names the outdated version. |
Database
| Variable | Default | Purpose |
|---|---|---|
DATABASE_URL | postgres://hub:change-me@db:5432/hub | Connection string of PostgreSQL 18 with TimescaleDB. |
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB | hub, change-me, hub | Used by the bundled db container. Keep them in sync with DATABASE_URL. |
DB_MEMORY | 2GB | Compose only: the memory the database tunes itself for at first start. |
Sign-in and roles
| Variable | Default | Purpose |
|---|---|---|
AUTH_SECRET | (required) | Session secret. Generate one with openssl rand -base64 32. |
DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET | (required) | The Discord OAuth application. |
DISCORD_BOT_TOKEN | (required) | Used only to re-check guild membership every 6 hours. |
DISCORD_GUILD_ID | (required) | The guild whose members may sign in. |
DISCORD_GUILD_NAME | Shown in "not a member of …" messages. | |
DISCORD_REQUIRED_ROLE_IDS | Optional, comma-separated. Members need at least one of these roles. | |
DISCORD_ADMIN_ROLE_IDS | Optional, comma-separated. Members with any of these roles are admins. | |
ADMIN_DISCORD_USER_IDS | Comma-separated Discord user ids who are always admin. Set at least one. |
Retention and limits
| Variable | Default | Purpose |
|---|---|---|
OFFBOARD_GRACE_DAYS | 30 | How long a member who left the guild is kept before their data is deleted. |
PAIRING_CODE_TTL_SECONDS | 300 | How long a pairing code stays valid. |
XP_RAW_RETENTION_DAYS | 365 | 5-minute XP samples (at least 14). Hourly and daily XP are kept forever. |
LOCATION_RETENTION_DAYS | 30 | The location trail. |
RAW_PAYLOAD_RETENTION_HOURS | 72 | Raw plugin payloads, for debugging ingest. |
AUDIT_LOG_RETENTION_DAYS | 730 | The admin audit log. |
INGEST_MAX_BODY_KB | 256 | The largest plugin payload the hub accepts. |
Events, sessions, equipment and wealth history are kept forever. The worker applies retention at startup, so a change takes effect on the next restart.
Proxy, metrics and logs
| Variable | Default | Purpose |
|---|---|---|
TRUST_PROXY_HOPS | 1 | The number of proxies in front of the hub that append to X-Forwarded-For. See Reverse proxy. |
METRICS_TOKEN | Enables /metrics on the web app and the worker (send it as a bearer token). Empty means /metrics answers 404. Generate one with openssl rand -hex 32. | |
WORKER_METRICS_PORT | 9464 | The worker's own metrics port. 0 disables it. |
WORKER_METRICS_BIND | 127.0.0.1 | Compose only: the host address the worker's port is published on. Use a private address, never a public one. |
WEB_PORT | 3000 | Compose only: the host port of the web app. |
BACKUP_DIR | ./backups | Compose only: where the optional backup service writes dumps. |
LOG_LEVEL | info | JSON logs on stdout. They never contain tokens, request bodies or coordinates. |