# Netbird

> WireGuard-based zero-config VPN.

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

## Overview

NetBird is a modern WireGuard-based mesh VPN platform that eliminates the traditional hub-and-spoke architecture by creating direct peer-to-peer connections between devices. The netbird-management component serves as the central control plane, handling device registration, key distribution, and network policies, while maintaining a web dashboard for administrative oversight. NetBird was designed to address the complexity of traditional VPN solutions by providing zero-configuration mesh networking with enterprise-grade security.

This stack combines three critical components to deliver a complete mesh VPN solution: netbird-management handles device authentication and network topology management, netbird-signal facilitates the initial WebRTC signaling required for peer discovery and connection establishment, and coturn provides STUN/TURN relay services when direct peer-to-peer connections cannot be established due to restrictive NAT or firewall configurations. Together, these services enable automatic mesh network formation where each client can communicate directly with others without routing through a central server.

This configuration is ideal for organizations seeking to replace traditional VPN infrastructure, remote teams requiring secure inter-device communication, and infrastructure teams managing distributed systems across multiple cloud providers. The self-hosted approach provides complete control over the VPN infrastructure while maintaining the simplicity of modern mesh networking protocols, making it particularly valuable for security-conscious organizations that need granular control over their networking stack.

## Features

- WireGuard-based mesh networking with automatic peer discovery and key exchange
- Web-based management dashboard for device enrollment and network policy configuration
- WebRTC signaling server for establishing direct peer-to-peer connections
- STUN/TURN relay services through coturn for NAT traversal and firewall bypass
- Zero-configuration client setup using setup keys and automatic endpoint discovery
- Real-time connection status monitoring and network topology visualization
- Support for multiple authentication backends through OIDC integration
- Automatic failover between direct connections and TURN relay when needed

## Use cases

- Replacing traditional hub-and-spoke VPN infrastructure with modern mesh networking
- Securing remote team communications with direct device-to-device connectivity
- Connecting distributed microservices across multiple cloud providers and regions
- Creating secure development environments with automatic peer discovery
- Establishing site-to-site connectivity for branch offices without dedicated hardware
- Building secure IoT device networks with centralized management and monitoring
- Implementing zero-trust network architecture with granular access controls

## Prerequisites

- Minimum 2GB RAM and 2 CPU cores for handling mesh network coordination
- Valid domain name with SSL certificate for production OIDC authentication
- OIDC provider configured (Auth0, Keycloak, Google Workspace, or Azure AD)
- UDP ports 3478 and 10000 accessible for STUN/TURN and signaling services
- Understanding of WireGuard concepts and mesh networking principles
- Network firewall configuration knowledge for proper service exposure

## docker-compose.yml

```yaml
services:
  management:
    image: netbirdio/management:latest
    container_name: netbird-management
    restart: unless-stopped
    environment:
      NETBIRD_DOMAIN: localhost
      NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT: ""
    volumes:
      - netbird_mgmt:/var/lib/netbird
    ports:
      - "8080:80"

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

  coturn:
    image: coturn/coturn:latest
    container_name: netbird-coturn
    restart: unless-stopped
    ports:
      - "3478:3478/udp"
      - "3478:3478/tcp"

volumes:
  netbird_mgmt:
```

## .env

```bash
# Configure OIDC provider for authentication
# See docs.netbird.io for full setup
```

## Usage notes

- Docs: https://docs.netbird.io/
- Management dashboard at http://localhost:8080
- Requires OIDC provider (Auth0, Keycloak, etc.) for authentication
- Clients download Netbird app and connect with setup key
- Signal server handles peer-to-peer connection negotiation
- TURN server (coturn) enables NAT traversal when direct connection fails

## Troubleshooting

- Management dashboard shows 'OIDC configuration error': Verify NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT points to valid OIDC provider discovery endpoint
- Clients fail to connect with 'signal server unreachable': Ensure port 10000 is accessible and netbird-signal container is running
- Peer connections fail with 'TURN server timeout': Check coturn container logs and verify UDP port 3478 is not blocked by firewall
- Setup key generation fails: Confirm netbird_mgmt volume has proper write permissions and sufficient disk space
- WebRTC connection establishment timeouts: Verify both signaling and TURN services are accessible from client networks
- Management API returns 500 errors: Check container logs for database connectivity issues and ensure volume persistence

