Configuration reference

Canonical reference for every COLLECTOR_* environment variable Prelude Collector reads - defaults and descriptions.

This page is the canonical reference for every COLLECTOR_* environment variable the collector reads. For a guided introduction see Configuration. This page is the exhaustive lookup.

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. Every variable has a sensible default, so a minimal deployment only needs the database connection.

Conventions used in the tables below:

Default - the value the collector falls back to if the variable is unset. A dash (-) means there is no default.
Booleans accept true / false.

General

Variable	Default	Description
`COLLECTOR_DEBUG`	`false`	Enable debug-level structured logging. With `false`, only INFO and above are emitted.
`COLLECTOR_TIMEZONE`	`UTC`	IANA timezone name used for log timestamps and scheduled tasks.
`COLLECTOR_STORAGE`	`./storage`	Root directory for persistent runtime files: the auto-generated TLS certificate (`certs/`), the at-rest encryption key (`keys/`), YANG models, vendor MIBs, and file output. Inside the container this is `/app/storage`.
`COLLECTOR_LOG_LEVEL`	`INFO`	Minimum log level (`DEBUG`, `INFO`, `WARN`, `ERROR`). `COLLECTOR_DEBUG=true` forces `DEBUG`.

Server

Variable	Default	Description
`COLLECTOR_PORT`	`4030`	TCP port for the REST API and web UI. Sets the listen address to `0.0.0.0:PORT`.
`COLLECTOR_APP_URL`	`http://localhost:4030`	Public base URL of the collector application.
`COLLECTOR_TLS_CERT`	-	Path (inside the container) to the TLS certificate (or fullchain) file. Set together with `COLLECTOR_TLS_KEY`.
`COLLECTOR_TLS_KEY`	-	Path (inside the container) to the matching TLS private key. Set together with `COLLECTOR_TLS_CERT`.

HTTPS is always on. Set both COLLECTOR_TLS_CERT and COLLECTOR_TLS_KEY to serve your own certificate. If either is unset, gweb auto-generates a self-signed certificate at storage/certs/main.{crt,key} on first start and serves with it.

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.

Database

Prelude Collector is PostgreSQL-only.

Variable	Default	Description
`COLLECTOR_DB_HOST`	`postgres`	PostgreSQL hostname. Use the Compose or Podman service name in containerized deployments, `localhost` for local dev.
`COLLECTOR_DB_PORT`	`5432`	PostgreSQL TCP 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`	Require TLS on the connection to PostgreSQL.

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`	-	Empty scratch PostgreSQL URL that Atlas replays migrations onto to compute diffs. Only needed when generating migrations (`migrate makemigrations`); leave unset at runtime.

Application

Variable	Default	Description
`COLLECTOR_MAX_SUBSCRIPTIONS`	`1000`	Maximum number of concurrent collection subscriptions across all devices.
`COLLECTOR_WORKER_POOL_SIZE`	`10`	Number of workers in the collection job dispatch pool (SNMP, NETCONF, CLI).
`COLLECTOR_METRICS_ENABLED`	`true`	Run the internal metrics manager that drives the Metrics dashboard and `GET /api/v1/metrics`.

NATS has no environment variable. It is configured once in the web UI under Output Settings → NATS; that single connection powers both data export and the collector's internal signaling (ICMP reachability, OneBoard device-sync).

Security

Variable	Default	Description
`COLLECTOR_CIPHER_TYPE`	`gcm`	Symmetric cipher for at-rest encryption. AES-GCM (`gcm`) is the default; `cfb` is the legacy unauthenticated alternative.
`COLLECTOR_ENABLE_HSTS`	`false`	Send the HTTP Strict-Transport-Security header. Enable when serving behind a trusted TLS chain.

Metrics manager

COLLECTOR_METRICS_ENABLED (see Application) toggles the manager; the variables below tune its behaviour.

Variable	Default	Description
`COLLECTOR_METRICS_UPDATE_INTERVAL`	`10`	Seconds between metrics aggregation updates.
`COLLECTOR_METRICS_MAX_DROP_METADATA`	`100`	Recent drop events kept in memory for inspection.
`COLLECTOR_METRICS_RATE_WINDOW_MINUTES`	`5`	Minutes for rate calculations.
`COLLECTOR_METRICS_WORKER_COUNT`	`4`	Async workers processing metric events.
`COLLECTOR_METRICS_EVENT_CHANNEL_SIZE`	`10000`	Buffer size for the internal metric event channel.
`COLLECTOR_METRICS_RATE_BUCKETS_PER_WINDOW`	`60`	Time buckets within the rate window.
`COLLECTOR_METRICS_PERSISTENCE_ENABLED`	`true`	Persist metric snapshots to the database.
`COLLECTOR_METRICS_RETENTION_DAYS`	`30`	Days of historical metric data retained.
`COLLECTOR_METRICS_PERSIST_INTERVAL`	`5`	Minutes between metric persistence snapshots.

gNMI protocol

These apply to every gNMI Protocol record.

Variable	Default	Description
`COLLECTOR_GNMI_TIMEOUT`	`30`	gRPC call timeout in seconds.
`COLLECTOR_GNMI_MAX_RETRIES`	`3`	Maximum reconnect attempts before the protocol is marked failed.
`COLLECTOR_GNMI_RETRY_INTERVAL`	`5`	Seconds between reconnect attempts.
`COLLECTOR_GNMI_KEEPALIVE_TIME`	`600`	Seconds between gRPC keepalive pings.
`COLLECTOR_GNMI_PERMIT_WITHOUT_STREAM`	`false`	Allow keepalive pings even when there are no active subscriptions.
`COLLECTOR_GNMI_SUBSCRIPTION_STAGGER_DELAY`	`500`	Milliseconds between successive subscription requests to the same device.
`COLLECTOR_GNMI_MAX_CONCURRENT_SUBSCRIPTIONS`	`3`	Maximum in-flight subscription requests per device.

SNMP protocol

Variable	Default	Description
`COLLECTOR_SNMP_TIMEOUT`	`5`	SNMP request timeout in seconds.
`COLLECTOR_SNMP_RETRIES`	`2`	Number of SNMP request retries before failure.
`COLLECTOR_SNMP_MAX_REPETITIONS`	`10`	Maximum repetitions for SNMP GetBulk requests.

CLI / SSH protocol

Variable	Default	Description
`COLLECTOR_CLI_TIMEOUT`	`30`	SSH session timeout in seconds.
`COLLECTOR_CLI_COMMAND_TIMEOUT`	`10`	Individual command execution timeout in seconds.

NETCONF protocol

Variable	Default	Description
`COLLECTOR_NETCONF_DEFAULT_PORT`	`830`	Default NETCONF port when not specified on the protocol.
`COLLECTOR_NETCONF_TIMEOUT`	`30`	NETCONF session timeout in seconds.

YANG repository

Variable	Default	Description
`COLLECTOR_YANG_REPO_URL`	`https://github.com/YangModels/yang`	Upstream Git repository for standard YANG models.
`COLLECTOR_YANG_REPO_PATH`	-	Local clone path. Leave unset to use the default path under the storage folder.

Logging

COLLECTOR_LOG_LEVEL (see General) sets the level; the rotation variables below control archival.

Variable	Default	Description
`COLLECTOR_LOG_COMPRESS_AFTER_DAYS`	`7`	Compress rotated log files after N days.
`COLLECTOR_LOG_DELETE_AFTER_DAYS`	`30`	Delete rotated log files after N days.

Complete example

A complete .env file for a single-host install (Compose reads it automatically when placed next to docker-compose.yml):

# General
COLLECTOR_DEBUG=false
COLLECTOR_TIMEZONE=Europe/Paris
COLLECTOR_STORAGE=/app/storage
COLLECTOR_LOG_LEVEL=INFO

# Server
COLLECTOR_PORT=4030
COLLECTOR_APP_URL=https://collector.example.com
# Bring your own TLS cert (set both, or omit both for self-signed):
COLLECTOR_TLS_CERT=/app/storage/certs/collector.crt
COLLECTOR_TLS_KEY=/app/storage/certs/collector.key

# Database
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

# Migrations
COLLECTOR_AUTO_MIGRATE=true

# Application
COLLECTOR_MAX_SUBSCRIPTIONS=1000
COLLECTOR_WORKER_POOL_SIZE=10
COLLECTOR_METRICS_ENABLED=true