Configuration

All runtime configuration is via environment variables in .env. See .env.example for the full template.

FQDNs

Three subdomains are required. All route through Traefik.

Variable	Default	Description
`API_PORT`	`3000`	HTTP listen port (internal)
`JWT_SECRET`	required	Secret for signing JWT session tokens
`PLATFORM_ADMIN_EMAILS`	—	Comma-separated emails for platform admin access
`HUB_INTERNAL_API_KEY`	—	Backwards-compatible machine access key
`LOG_LEVEL`	`info`	Log level: `debug`, `info`, `warn`, `error`

Variable	Default	Description
`PG_HOST`	`localhost`	Database host
`PG_PORT`	`5432`	Database port
`PG_DATABASE`	`birdnet`	Database name
`PG_USER`	`birdnet`	Database user
`PG_PASSWORD`	`birdnet`	Database password
`BNG_POSTGRES_PASSWORD`	—	Docker Compose alias for PG_PASSWORD

Variable	Default	Description
`REDIS_HOST`	`localhost`	Redis host
`REDIS_PORT`	`6379`	Redis port
`REDIS_PASSWORD`	—	Redis auth password (empty = no auth)

Variable	Default	Description
`MQTT_BROKER_URL`	`mqtt://localhost:1883`	Broker URL (internal)
`MQTT_HUB_PASSWORD`	`hub-internal-secret`	Hub ingester MQTT password
`MQTT_ADMIN_USER`	`admin`	Mosquitto dynamic security admin
`MQTT_ADMIN_PASSWORD`	`admin`	Mosquitto dynamic security password

Variable	Default	Description
`MINIO_ENDPOINT`	`localhost`	MinIO host
`MINIO_PORT`	`9000`	MinIO port
`MINIO_ACCESS_KEY`	`minioadmin`	MinIO access key
`MINIO_SECRET_KEY`	`minioadmin`	MinIO secret key
`MINIO_BUCKET`	`birdnet-audio`	Bucket name (audio + species images)
`MINIO_USE_SSL`	`false`	Use SSL for MinIO connection

Variable	Default	Description
`BNG_VOLUMES_ROOT`	`./storage`	Root directory for all persistent data
`PUID`	—	Container user ID
`PGID`	—	Container group ID

Variable	Default	Description
`SATELLITE_ID`	required	UUID from satellite registration
`TENANT_ID`	required	Tenant UUID
`MQTT_BROKER_URL`	`mqtt://localhost:1883`	Broker URL (`mqtts://` for production)
`MQTT_USERNAME`	required	MQTT username (= satellite ID)
`MQTT_PASSWORD`	required	MQTT password (from registration)
`CAPTURE_MODE`	`simulate`	`alsa`, `simulate`, or `replay`
`AUDIO_DEVICE`	`default`	ALSA device name
`SAMPLE_RATE`	`48000`	Audio sample rate (Hz)
`CHUNK_DURATION_MS`	`3000`	Chunk duration (ms)
`OVERLAP_MS`	`0`	Overlap between chunks
`RECORDING_PROFILE`	`continuous`	Default recording profile
`LATITUDE`	`0`	Static latitude
`LONGITUDE`	`0`	Static longitude
`GPS_MODE`	`static`	`static` or `gpsd`
`GPSD_HOST`	`localhost`	gpsd daemon host
`GPSD_PORT`	`2947`	gpsd daemon port
`DATA_DIR`	`./data`	Local storage directory
`RETENTION_HOURS`	`48`	Keep chunks after acknowledgment
`TELEMETRY_INTERVAL_MS`	`60000`	Telemetry report interval
`AUDIO_FILTER`	`true`	Enable on-device audio pre-filtering
`REPLAY_DIR`	`fixtures/`	Directory for replay mode WAV files

Configured in Platform Settings page, stored in platform_settings table.

Setting	Default	Description
`allow_self_registration`	`true`	Users can register without invite
`allow_tenant_creation`	`false`	Logged-in users can create tenants
`allow_invite_links`	`true`	Admins can generate invite links
`image_download_delay_seconds`	`5`	Delay between Wikipedia image downloads

Configured in Tenant Settings page, stored in tenant_settings table.

Setting	Default	Description
`confidence_high`	`0.7`	High confidence threshold
`confidence_low`	`0.4`	Low/uncertain confidence threshold
`min_confidence`	`0.1`	Minimum display threshold
`offline_timeout_minutes`	`5`	Satellite offline detection timeout
`verification_consensus`	`3`	Votes needed for consensus
`retention_hours`	`48`	Satellite local storage retention
`watchlist_species`	`[]`	Custom species watchlist for rare alerts