Configuration

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

FQDNs

Variable	Description	Example
`BNG_APP_FQDN`	Web UI + API domain	`birdnet.example.com`
`BNG_MQTT_FQDN`	MQTT broker domain	`mqtt.birdnet.example.com`
`BNG_S3_FQDN`	MinIO console domain	`s3.birdnet.example.com`
`BNG_DOCS_FQDN`	Documentation site domain	`docs.birdnet.example.com`

Four subdomains are required. All route through Traefik.

Hub API

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`

PostgreSQL

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

Redis

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

MQTT (Hub side)

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

MinIO

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

Docker Compose

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

Satellite (Pi)

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

Platform Settings (UI)

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`	`0` (auto)	Delay between Wikipedia image downloads. `0` derives from authenticated/unauthenticated rate tier
`wikimedia_access_token`	—	OAuth 2.0 token for Wikimedia API (raises rate limit from 500 to 10 000 req/hr)
`wikimedia_contact_email`	—	Contact email for Wikimedia User-Agent header
`inaturalist_enabled`	`false`	Opt-in fallback for gallery extras when Wikipedia is exhausted (v0.29+)
`image_license_filter`	`["cc0","cc-by","cc-by-sa"]`	License codes accepted by iNaturalist fetches; admin can widen to `cc-by-nc` / `cc-by-nc-sa` / `cc-by-nc-nd`. Photos with no license_code (= all rights reserved) are always rejected (v0.29+)
`species_extra_images_count`	`5`	Gallery extras per species beyond the primary. No upper bound; 0 disables extras (v0.29+ removed the hard 20 cap)
`audio_storage_cap_gb`	`50`	Soft cap (GB). When total usage crosses, next sweep purges oldest unprotected audio
`audio_storage_hard_cap_gb`	`60` (= soft × 1.2)	Hard cap (GB). Same eviction policy as soft pass — protected (keep-best + pinned) audio is never auto-deleted (v0.29 correctness pass)
`audio_retention_days`	`30`	Delete non-keep-best audio older than this
`keep_best_per_species`	`10`	Top-N detections by confidence per species, never auto-deleted
`silent_chunk_retention_hours`	`6`	Purge chunks with 0 detections after this many hours
`apk_keep_last_n`	`5`	Keep the N most recent APK builds in mobile_releases; older ones drop on next sweep
`retention_enabled`	`false`	Run scheduled retention sweeps every 6h
`inference_mode`	`single`	`single` = default model only / `compare` = also run enabled non-default models on sampled chunks (writes to `shadow_detections`)
`inference_compare_sample_rate`	`10`	Percentage of chunks routed through compare mode (1–100)
`dismissed_catalog_ids`	`[]`	Catalog template IDs admin has hidden via the × button

Tenant Settings (UI)

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)