Docker Compose Deployment

BirdNET-NG runs as a 7-container stack behind a Traefik reverse proxy.

Containers

Container	Image	Purpose
postgres	PostgreSQL 17	Multi-tenant data store
redis	Redis 7	BullMQ job queue backend
mosquitto	Mosquitto 2.x	MQTT broker (dynamic security plugin)
minio	MinIO	S3-compatible audio + image storage
hub	Node.js	API gateway, MQTT ingester, background workers
web	nginx	React SPA, proxies /api/* to hub
worker	Python 3.11	BirdNET inference (scalable)

Networks

• traefik (external) — Traefik routes HTTPS/MQTTS/WSS traffic
• backend (internal) — Inter-container communication

Storage

All persistent data uses bind mounts under BNG_VOLUMES_ROOT (default: ./storage/):

storage/
├── postgres/    # Database files
├── redis/       # Redis AOF
├── mosquitto/   # Broker data + dynamic security DB
└── minio/       # Audio blobs + species images

Scaling Workers

docker compose up --scale worker=4 -d

Workers are stateless — add as many as needed for your detection volume.

Commands

# Start full stack
docker compose up -d

# Rebuild after code changes
docker compose up -d --build

# View logs
docker compose logs -f hub

# Run database migrations
docker compose exec hub node packages/hub/dist/db/migrate.js

# Stop everything
docker compose down

Traefik Configuration

Three entrypoints are needed:

Entrypoint	Port	Protocol	Service
websecure	443	HTTPS	Web UI + API
mqtts	8883	TCP (TLS)	MQTT broker
websecure	443	HTTPS	MinIO console

The docker-compose.yml includes Traefik labels for automatic routing.