docker.recipes

Netbird

advanced

WireGuard-based zero-config VPN.

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.

Key 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

Common Use Cases

  • 1Replacing traditional hub-and-spoke VPN infrastructure with modern mesh networking
  • 2Securing remote team communications with direct device-to-device connectivity
  • 3Connecting distributed microservices across multiple cloud providers and regions
  • 4Creating secure development environments with automatic peer discovery
  • 5Establishing site-to-site connectivity for branch offices without dedicated hardware
  • 6Building secure IoT device networks with centralized management and monitoring
  • 7Implementing 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  management: 
3    image: netbirdio/management:latest
4    container_name: netbird-management
5    restart: unless-stopped
6    environment: 
7      NETBIRD_DOMAIN: localhost
8      NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT: ""
9    volumes: 
10      - netbird_mgmt:/var/lib/netbird
11    ports: 
12      - "8080:80"
13
14  signal: 
15    image: netbirdio/signal:latest
16    container_name: netbird-signal
17    restart: unless-stopped
18    ports: 
19      - "10000:80"
20
21  coturn: 
22    image: coturn/coturn:latest
23    container_name: netbird-coturn
24    restart: unless-stopped
25    ports: 
26      - "3478:3478/udp"
27      - "3478:3478/tcp"
28
29volumes: 
30  netbird_mgmt:

.env Template

.env
1# Configure OIDC provider for authentication
2# See docs.netbird.io for full setup

Usage Notes

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

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

management
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
signal:
  image: netbirdio/signal:latest
  container_name: netbird-signal
  restart: unless-stopped
  ports:
    - "10000:80"
coturn
coturn:
  image: coturn/coturn:latest
  container_name: netbird-coturn
  restart: unless-stopped
  ports:
    - 3478:3478/udp
    - 3478:3478/tcp

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  management:
5    image: netbirdio/management:latest
6    container_name: netbird-management
7    restart: unless-stopped
8    environment:
9      NETBIRD_DOMAIN: localhost
10      NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT: ""
11    volumes:
12      - netbird_mgmt:/var/lib/netbird
13    ports:
14      - "8080:80"
15
16  signal:
17    image: netbirdio/signal:latest
18    container_name: netbird-signal
19    restart: unless-stopped
20    ports:
21      - "10000:80"
22
23  coturn:
24    image: coturn/coturn:latest
25    container_name: netbird-coturn
26    restart: unless-stopped
27    ports:
28      - "3478:3478/udp"
29      - "3478:3478/tcp"
30
31volumes:
32  netbird_mgmt:
33EOF
34
35# 2. Create the .env file
36cat > .env << 'EOF'
37# Configure OIDC provider for authentication
38# See docs.netbird.io for full setup
39EOF
40
41# 3. Start the services
42docker compose up -d
43
44# 4. View logs
45docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/netbird/run | bash

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

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

netbird-managementnetbird-signalcoturn

Tags

#netbird#wireguard#vpn#mesh

Category

Security & Networking

Related Recipes

Ad Space