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

Three subdomains are required. All route through Traefik.

Hub API

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

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
BNG_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_VOLUMES_ROOT	./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 (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

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	5	Delay between Wikipedia image downloads

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
retention_hours	48	Satellite local storage retention
watchlist_species	[]	Custom species watchlist for rare alerts