You are viewing archived documentation for v0.5. Go to latest →

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 (4 subdomains needed)
  • Traefik reverse proxy (or adapt for nginx/caddy)
  • Node.js 20+ and pnpm (for development)

Quick Start

1. Clone and configure

# Clone the repository (replace with your Git server URL)
git clone <your-git-server>/birdnet-ng.git
cd birdnet-ng
cp .env.example .env

Note: If the repository is hosted on a private Git server (Gitea, GitLab, etc.), make sure you have access configured (SSH key or HTTPS credentials). For SSH: git clone git@your-server:org/birdnet-ng.git

Edit .env with your settings:

# Required: your domains (4 FQDNs)
BNG_APP_FQDN=birdnet.example.com
BNG_MQTT_FQDN=mqtt.birdnet.example.com
BNG_S3_FQDN=s3.birdnet.example.com
BNG_DOCS_FQDN=docs.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 8 containers: PostgreSQL, Redis, Mosquitto, MinIO, Hub API, Web UI, Documentation site, 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 Satellite: Raspberry Pi or Satellite: Android 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 (Express + markdown-it)
├── 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