Getting Started

BirdNET-NG is a distributed bird sound identification system. Satellite nodes (Raspberry Pi or Android phones) capture audio and send it to a central hub that runs BirdNET inference and serves results through a web UI.

Prerequisites

• Docker + Docker Compose
• A domain name with DNS (3 subdomains needed)
• Traefik reverse proxy (or adapt for nginx/caddy)
• Node.js 20+ and pnpm (for development)

Quick Start

1. Clone and configure

git clone https://github.com/birdnet-ng/birdnet-ng.git
cd birdnet-ng
cp .env.example .env

Edit .env with your settings:

# Required: your domain
BNG_APP_FQDN=birdnet.example.com
BNG_MQTT_FQDN=mqtt.birdnet.example.com
BNG_S3_FQDN=s3.birdnet.example.com

# Required: generate secrets
JWT_SECRET=$(openssl rand -hex 32)
BNG_POSTGRES_PASSWORD=$(openssl rand -hex 16)
BNG_MINIO_SECRET_KEY=$(openssl rand -hex 16)
BNG_MOSQUITTO_HUB_PASSWORD=$(openssl rand -hex 16)

2. Start the stack

docker compose up -d

This starts 7 containers: PostgreSQL, Redis, Mosquitto, MinIO, Hub API, Web UI, and an inference worker.

3. Create your account

Open https://birdnet.example.com in your browser. Register an account, then create a tenant (team).

4. Deploy a satellite

See Raspberry Pi Satellite or Mobile App guides.

Project Structure

birdnet-ng/
├── packages/
│   ├── shared/      — TypeScript types, constants, MQTT protocol
│   ├── satellite/   — Node.js agent for Raspberry Pi
│   ├── hub/         — Fastify API gateway, MQTT ingester, job queue
│   ├── inference/   — Python BirdNET inference worker
│   ├── mobile/      — Android phone satellite (Capacitor)
│   └── web/         — React SPA (Vite)
├── docs/            — This documentation site (VitePress)
├── config/          — Mosquitto configuration
├── docker-compose.yml
└── .env.example

Development

pnpm install
pnpm build        # Build all TypeScript packages
pnpm dev           # Run all packages in dev mode
pnpm docs:dev      # Start documentation site locally