# NetBird Mesh VPN

> Open source WireGuard-based mesh VPN with zero-config, identity provider integration.

- Category: Security & Networking
- Difficulty: advanced
- Components: netbird-management, netbird-signal, coturn, nginx, postgres
- Tags: vpn, netbird, wireguard, mesh-vpn, zero-trust
- Source: https://docker.recipes/security/netbird-vpn-stack

## Overview

NetBird is a WireGuard-based mesh VPN solution that eliminates traditional VPN complexity through zero-configuration peer-to-peer networking. Built on modern zero-trust principles, NetBird creates encrypted tunnels between devices without requiring manual key exchanges or complex routing configurations. The platform emerged as an open-source alternative to proprietary mesh VPN solutions, leveraging WireGuard's proven cryptography while adding intelligent peer discovery and management capabilities.

This deployment combines NetBird's management server with its signaling infrastructure, TURN relay services via Coturn, and PostgreSQL for persistent configuration storage. The management component handles device enrollment, policy enforcement, and network topology decisions, while the signal server facilitates peer discovery and initial connection establishment. Coturn provides STUN/TURN relay capabilities for devices behind restrictive NATs, ensuring connectivity even in challenging network environments. NGINX serves as the web interface proxy and handles SSL termination for the management dashboard.

This stack is ideal for organizations seeking modern VPN infrastructure without the overhead of traditional hub-and-spoke architectures. IT teams managing remote workforces, developers requiring secure access to distributed development environments, and organizations implementing zero-trust network models will find NetBird's approach particularly valuable. The integration with identity providers through OIDC support makes it suitable for enterprises with existing SSO infrastructure.

## Features

- WireGuard-based mesh networking with automatic peer discovery and key rotation
- Zero-configuration client deployment with automated network topology management
- OIDC integration supporting major identity providers including Google, Azure AD, and Okta
- Real-time peer connection status monitoring through PostgreSQL-backed management interface
- STUN/TURN relay support via Coturn for NAT traversal in restrictive network environments
- Single account mode for simplified small-team deployments without external identity providers
- Policy-based access control with granular network segmentation capabilities
- Cross-platform client support with automatic updates and configuration synchronization

## Use cases

- Remote team secure access to internal development environments and staging servers
- Site-to-site connectivity for distributed offices without dedicated VPN appliances
- Secure IoT device management and monitoring across multiple geographic locations
- Development team collaboration requiring encrypted communication between workstations
- Freelancer and contractor access management with time-limited network permissions
- Home lab enthusiasts connecting personal devices across different network locations
- Small business secure file sharing and printer access for remote employees

## Prerequisites

- Public domain name with DNS control for SSL certificate generation and client discovery
- Minimum 2GB RAM and 20GB storage for production deployments with active peer management
- Firewall configuration allowing UDP 3478 for TURN relay and TCP 443/10000 for management services
- Basic understanding of WireGuard networking concepts and IP address allocation
- OIDC provider credentials if using SSO integration instead of single account mode
- SSL certificate management capability for HTTPS-enabled management interface

## docker-compose.yml

```yaml
services:
  management:
    image: netbirdio/management:latest
    environment:
      NETBIRD_DOMAIN: ${NETBIRD_DOMAIN}
      NETBIRD_MGMT_API_ENDPOINT: https://${NETBIRD_DOMAIN}:443
      NETBIRD_MGMT_SINGLE_ACCOUNT_MODE_DOMAIN: ${NETBIRD_DOMAIN}
    ports:
      - "443:443"
    volumes:
      - management:/var/lib/netbird
      - ./management.json:/etc/netbird/management.json:ro
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - netbird-net
    restart: unless-stopped

  signal:
    image: netbirdio/signal:latest
    ports:
      - "10000:80"
    networks:
      - netbird-net
    restart: unless-stopped

  coturn:
    image: coturn/coturn:latest
    command: -c /etc/turnserver.conf
    ports:
      - "3478:3478/udp"
      - "3478:3478/tcp"
    volumes:
      - ./turnserver.conf:/etc/turnserver.conf:ro
    networks:
      - netbird-net
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - netbird-net
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - management
    networks:
      - netbird-net
    restart: unless-stopped

volumes:
  management:
  postgres_data:

networks:
  netbird-net:
    driver: bridge
```

## .env

```bash
# NetBird Domain
NETBIRD_DOMAIN=netbird.example.com

# PostgreSQL
POSTGRES_USER=netbird
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=netbird

# TURN Server
TURN_SECRET=your_turn_secret_here
```

## Usage notes

- Dashboard at https://netbird.example.com
- Supports SSO with OIDC providers
- Clients auto-discover and connect via signal server
- TURN server handles NAT traversal

## Troubleshooting

- Clients unable to connect through NAT: Verify Coturn TURN server is accessible on UDP 3478 and check firewall rules for STUN/TURN traffic
- Management interface shows 502 Bad Gateway: Check PostgreSQL container health status and verify database connection string in management.json configuration
- Peer discovery failing in signal server: Ensure NetBird domain environment variable matches your public DNS name and signal service is reachable on port 10000
- OIDC authentication redirects failing: Verify callback URLs in identity provider match your NetBird domain and check management container logs for authentication errors
- PostgreSQL connection refused errors: Confirm POSTGRES_USER and POSTGRES_PASSWORD environment variables match between management and postgres services
- WireGuard tunnel established but no traffic flowing: Check IP address allocation conflicts and verify routing table entries on NetBird clients

