Configuration
Configure Prelude Collector through COLLECTOR_* environment variables, including database, NATS, metrics, and TLS settings.
Prelude Collector is configured entirely through environment
variables. Pass them on
the container (-e NAME=value), in the environment: block of a
Compose service, or through an .env file next to your
docker-compose.yml. Every variable has a sensible default, so a
minimal deployment only needs to set the database connection.
This page walks through the variables you are most likely to touch.
For the exhaustive list of every COLLECTOR_* variable, see the
Configuration reference.
A convenient way to keep settings together is an .env file. Compose
loads it automatically when it sits next to docker-compose.yml:
# .env
POSTGRES_PASSWORD=change-me-sE43kapqD8df5fds
COLLECTOR_APP_URL=https://collector.example.com
The collector reads its environment only at startup, so restart the service after each change.
General settings
| Variable | Default | Description |
|---|---|---|
COLLECTOR_DEBUG |
false |
Enable debug-level structured logging. Leave off in production - it is verbose. |
COLLECTOR_TIMEZONE |
UTC |
IANA timezone for log timestamps and scheduled tasks. |
COLLECTOR_STORAGE |
./storage |
Root directory gweb uses for the auto-generated TLS certificate (certs/) and the at-rest encryption key (keys/). Inside the container this is /app/storage. |
COLLECTOR_LOG_LEVEL |
INFO |
Minimum log level (DEBUG, INFO, WARN, ERROR). COLLECTOR_DEBUG=true forces DEBUG. |
Database
Prelude Collector is PostgreSQL-only.
environment:
COLLECTOR_DB_HOST: postgres
COLLECTOR_DB_PORT: "5432"
COLLECTOR_DB_USER: prelude
COLLECTOR_DB_PASSWORD: change-me-sE43kapqD8df5fds
COLLECTOR_DB_NAME: collector
COLLECTOR_DB_SSL: "false"
| Variable | Default | Description |
|---|---|---|
COLLECTOR_DB_HOST |
postgres |
PostgreSQL hostname. Use the compose service name (postgres) in containerized deployments, or your DB host otherwise. |
COLLECTOR_DB_PORT |
5432 |
PostgreSQL port. |
COLLECTOR_DB_USER |
prelude |
Database user. |
COLLECTOR_DB_PASSWORD |
change-me-sE43kapqD8df5fds |
Database password. Change this for any non-evaluation deployment. |
COLLECTOR_DB_NAME |
collector |
Database name. |
COLLECTOR_DB_SSL |
false |
Set true to require TLS on the connection to PostgreSQL. |
Server and listen port
environment:
COLLECTOR_PORT: "4030"
COLLECTOR_APP_URL: https://collector.example.com
| Variable | Default | Description |
|---|---|---|
COLLECTOR_PORT |
4030 |
Port for the API and UI. Sets the listen address to 0.0.0.0:PORT. |
COLLECTOR_APP_URL |
http://localhost:4030 |
Public base URL of the collector application. |
TLS and at-rest encryption
HTTPS is always on. To serve your own certificate, set both
COLLECTOR_TLS_CERT and COLLECTOR_TLS_KEY to the in-container paths
of the fullchain certificate and the private key:
environment:
COLLECTOR_TLS_CERT: /app/storage/certs/collector.crt
COLLECTOR_TLS_KEY: /app/storage/certs/collector.key
| Variable | Default | Description |
|---|---|---|
COLLECTOR_TLS_CERT |
- | Path (inside the container) to the TLS certificate (or fullchain) the collector serves. |
COLLECTOR_TLS_KEY |
- | Path (inside the container) to the matching TLS private key. |
If either variable is unset, gweb auto-generates a self-signed
certificate on first start at storage/certs/main.{crt,key} and
serves HTTPS with it. See Installation / TLS for
the end-to-end custom-certificate setup.
At-rest encryption key. Sensitive values stored in the database
(output-backend credentials, device passwords) are encrypted with an
AES-256 key that gweb generates automatically on first start and
persists to storage/keys/prelude-collector.key. There is nothing to
set. Persist the storage/ volume and back up storage/keys/ — if
that key is lost, every existing encrypted value becomes unreadable.
Storage folder
Set with COLLECTOR_STORAGE (default ./storage, /app/storage in
the container). This is the root directory for persistent runtime
files: YANG models (storage/yang/), vendor MIBs
(storage/mibs/vendor/), and license artifacts. Mount this directory
as a volume so it survives container restarts.
NATS
NATS is not configured through environment variables. You configure
it once, in the web UI under Output Settings → NATS. That single
connection powers both data export (telemetry published to
collector.data.{model}.{deviceId}) and the collector's internal
signaling (ICMP reachability, OneBoard device-sync).
The bundled Compose stack runs a nats service. After first boot, open
Output Settings → NATS, set the URL to nats://nats:4222, and
enable it. Use nats:// for plain TCP or tls:// for TLS.
Migrations
| Variable | Default | Description |
|---|---|---|
COLLECTOR_AUTO_MIGRATE |
true |
Apply pending migrations automatically on startup. When false, startup blocks until the schema is current; run prelude-collector migrate up manually. |
COLLECTOR_DEV_DB_URL |
- | An empty scratch PostgreSQL URL that Atlas replays migrations onto to compute diffs. Only needed when generating new migrations (migrate makemigrations); leave unset at runtime. |
Metrics
| Variable | Default | Description |
|---|---|---|
COLLECTOR_METRICS_ENABLED |
true |
Run the internal runtime metrics manager. |
COLLECTOR_METRICS_ENABLED toggles the internal runtime metrics
manager — the collector's in-memory counters and gauges that drive
the Metrics dashboard in the web UI and the JSON read at
GET /api/v1/metrics. It does not stand up an HTTP scrape endpoint; to
expose collected device data to Prometheus, attach the
Prometheus output backend instead. The
manager's tuning values (update interval, retention, worker count, …)
are set via COLLECTOR_METRICS_* variables — see the
Configuration reference.
Protocol tuning
The per-protocol timeouts and retries for gNMI, SNMP, CLI, and NETCONF
are set via the COLLECTOR_GNMI_*, COLLECTOR_SNMP_*, COLLECTOR_CLI_*,
and COLLECTOR_NETCONF_* variables. The defaults are listed on each
protocol page and in the
Configuration reference.
Concurrency
| Variable | Default | Description |
|---|---|---|
COLLECTOR_MAX_SUBSCRIPTIONS |
1000 |
Hard cap on simultaneously active subscriptions. |
COLLECTOR_WORKER_POOL_SIZE |
10 |
Workers for non-streaming collection tasks (SNMP, NETCONF, CLI). |
Tune these for your platform: a single 2 vCPU collector typically
handles a few hundred subscriptions comfortably. Add more collectors
before pushing past COLLECTOR_MAX_SUBSCRIPTIONS=1000.
Logging
COLLECTOR_LOG_LEVEL (default INFO) sets the minimum log level
(DEBUG, INFO, WARN, ERROR); COLLECTOR_DEBUG=true forces
DEBUG. Log rotation is controlled by COLLECTOR_LOG_COMPRESS_AFTER_DAYS
and COLLECTOR_LOG_DELETE_AFTER_DAYS — see the
Configuration reference.
Reloading
Changes take effect after a restart:
docker compose restart collector
Complete example
A complete .env for a single-host install:
COLLECTOR_DEBUG=false
COLLECTOR_TIMEZONE=Europe/Paris
COLLECTOR_STORAGE=/app/storage
COLLECTOR_PORT=4030
COLLECTOR_APP_URL=https://collector.example.com
COLLECTOR_DB_HOST=postgres
COLLECTOR_DB_PORT=5432
COLLECTOR_DB_USER=prelude
COLLECTOR_DB_PASSWORD=change-me-sE43kapqD8df5fds
COLLECTOR_DB_NAME=collector
COLLECTOR_DB_SSL=false
COLLECTOR_AUTO_MIGRATE=true
COLLECTOR_METRICS_ENABLED=true
COLLECTOR_MAX_SUBSCRIPTIONS=1000
COLLECTOR_WORKER_POOL_SIZE=10
Once the collector restarts cleanly with your environment, move on to Licensing.