Configuration

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

FQDNs

Four subdomains are required. All route through Traefik.

Variable	Default	Description
`HUB_MODE`	`full`	Hub process mode: `full` (single process), `api` (HTTP + WebSocket only, scalable), `dispatcher` (background workers only, single instance)
`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
`MFA_ENCRYPTION_KEY`	—	32-byte hex key (`openssl rand -hex 32`) used to AES-256-GCM-encrypt stored TOTP secrets. Required once MFA is enrolled — rotating it invalidates every existing TOTP and forces re-enrollment. Without it, MFA features fail-closed at boot.
`WEBAUTHN_RP_ID`	derived	WebAuthn Relying Party ID (must match the eTLD+1 the user logs in on). Defaults to `BNG_APP_FQDN`.
`WEBAUTHN_RP_NAME`	`BirdNET-NG`	Friendly display name shown by browser passkey prompts.
`WEBAUTHN_ORIGIN`	derived	Full origin URL passed to WebAuthn verification. Defaults to `https://${BNG_APP_FQDN}`.
`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
`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_APP_VOLUMES`	`./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 (`wss://` 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
`TELEMETRY_INTERVAL_MS`	`60000`	Telemetry report interval
`YAMNET_ENABLED`	`true` (alsa)	Enable on-device YAMNet VAD gate
`YAMNET_MIN_BIRD_PROB`	`0.05`	Bird-likelihood threshold (overridable by hub push)
`YAMNET_PYTHON`	(auto-discovered)	Python executable for the YAMNet sidecar
`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
`wikimedia_access_token`	—	OAuth 2.0 token for Wikimedia API (raises rate limit to 10,000 req/hr)
`wikimedia_contact_email`	—	Contact email for Wikimedia User-Agent header

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
`watchlist_species`	`[]`	Custom species watchlist for rare alerts
`heartbeat_interval_sec`	`30`	Satellite heartbeat interval (seconds)
`filter_enabled`	`true`	Enable on-device audio pre-filtering (silence + YAMNet)
`filter_min_rms`	`0.003`	RMS silence-gate threshold
`yamnet_min_bird_prob`	`0.05`	YAMNet bird-likelihood threshold (clear birds score 3.4–3.9)
`outbox_soft_size_mb`	`5000`	Below this, the satellite outbox keeps everything; above, oldest acked first
`outbox_hard_size_mb`	`8000`	Hard ceiling; above this, oldest of anything is dropped
`outbox_max_age_hours`	`720`	Final age safety valve (30 days)
`show_amphibians` / `show_insects` / `show_anthropogenic` / `show_human_voice` / `show_other_animals`	`false`	Per-category UI visibility (hide non-bird detections from the list)
`drop_amphibian_at_satellite` / `drop_insect_at_satellite` / `drop_anthropogenic_at_satellite` / `drop_human_voice_at_satellite` / `drop_other_animal_at_satellite`	`true`	Per-category YAMNet pre-upload drop (independent of `show_*`; overridable per satellite)