NetBird is a mesh networking solution built on WireGuard protocol that provides an alternative to traditional VPN architectures. This guide covers the complete process of setting up a self-hosted NetBird instance, from initial planning through advanced optimization.

Self-hosting NetBird provides complete control over infrastructure and data while eliminating recurring cloud service costs. This comprehensive installation guide details each step required for successful deployment.

Understanding NetBird: The Foundation of Your Self-Hosted Setup

Traditional VPNs route all traffic through central servers, creating potential bottlenecks and single points of failure. NetBird implements mesh networking, enabling direct peer-to-peer connections between devices when possible.

NetBird's architecture comprises three core components. The Management Service handles authentication, access controls, and network policies. The Signal Service facilitates peer discovery and connection establishment. The TURN relay provides connectivity when direct connections cannot be established due to firewall restrictions.

This peer-to-peer approach reduces latency and improves overall network performance by eliminating unnecessary routing through central servers.

Why Self-Host NetBird?

Self-hosting NetBird offers several advantages over cloud-based solutions:

AspectCloud NetBirdSelf-Hosted NetBirdMonthly Cost$5-15/user$0 after infrastructureData ControlThird-party serversComplete ownershipCustomizationLimited optionsUnlimited flexibilityComplianceDepends on providerFull controlPerformanceShared resourcesDedicated hardwareScalingPay per userScale at will

Organizations report significant cost reductions and performance improvements after transitioning to self-hosted deployments.

NetBird System Requirements: Planning Your Infrastructure

Hardware requirements vary based on organizational size and usage patterns. The following specifications provide reliable performance:

Minimum Hardware Specifications

For deployments supporting up to 50 users:

  • 2 CPU cores (4 cores recommended)
  • 4GB RAM (8GB recommended)
  • 20GB SSD storage
  • 1Gbps network connection (100Mbps minimum)

Scaling guidelines for larger deployments:

User CountCPU CoresRAMStorageBandwidth1-5048GB40GB1Gbps50-200816GB80GB1Gbps200-5001632GB160GB10Gbps500+32+64GB+320GB+10Gbps+

Software Prerequisites

NetBird requires the following software components:

  • Operating System: Ubuntu 22.04 LTS (recommended), Debian 11, or Rocky Linux 9
  • Docker and Docker Compose
  • Domain name with DNS management access

Required network ports:

  • 443/tcp: HTTPS management console
  • 80/tcp: HTTP (redirects to HTTPS)
  • 33073/tcp: Signal service
  • 3478/tcp+udp: TURN/STUN server
  • 51820/udp: WireGuard connections

Complete NetBird Installation Guide: From Zero to Hero

This installation process assumes Ubuntu 22.04 LTS as the base operating system.

Step 1: Prepare Your Server

Update the system and install required packages:

sudo apt update && sudo apt upgrade -y

sudo apt install -y curl wget git ufw fail2ban

Create a dedicated user for NetBird services:

sudo adduser netbird

sudo usermod -aG sudo netbird

sudo su - netbird

Configure firewall rules:

sudo ufw allow 22/tcp

sudo ufw allow 80/tcp

sudo ufw allow 443/tcp

sudo ufw allow 33073/tcp

sudo ufw allow 3478/tcp

sudo ufw allow 3478/udp

sudo ufw allow 51820/udp

sudo ufw enable

Step 2: Install Docker and Dependencies

Install Docker using the official installation script:

curl -fsSL https://get.docker.com -o get-docker.sh

sudo sh get-docker.sh

sudo usermod -aG docker $USER

Log out and reconnect for group changes to take effect. Verify installation:

docker --version

docker compose version

Step 3: Deploy NetBird Infrastructure

Clone the NetBird repository and prepare configuration files:

git clone https://github.com/netbirdio/netbird.git

cd netbird/infrastructure_files/

cp setup.env.example setup.env

Edit the setup.env file with your configuration:

Your domain configuration

NETBIRD_DOMAIN="vpn.yourcompany.com"

NETBIRD_MGMT_API_ENDPOINT="https://api.vpn.yourcompany.com"

NETBIRD_SIGNAL_ENDPOINT="https://signal.vpn.yourcompany.com"

Db8980c1

Authentication provider

NETBIRD_AUTH_PROVIDER="authentik"

NETBIRD_AUTH_CLIENT_ID="your-client-id"

NETBIRD_AUTH_CLIENT_SECRET="your-secret"

Database password

POSTGRES_PASSWORD="GenerateAStrongPasswordHere123!"

Use strong, randomly generated passwords for database credentials.

Step 4: Launch Your NetBird Instance

Start the NetBird services:

sudo docker compose up -d

Monitor logs to verify successful startup:

sudo docker compose logs -f

Services should initialize in sequence: PostgreSQL database, management service, signal server, and dashboard.

Step 5: Configure SSL Certificates

Install SSL certificates using Let's Encrypt:

sudo apt install certbot python3-certbot-nginx -y

sudo certbot --nginx -d vpn.yourcompany.com -d api.vpn.yourcompany.com -d

signal.vpn.yourcompany.com

Enable automatic certificate renewal:

sudo systemctl enable certbot.timer

sudo systemctl start certbot.timer

Authentication and User Management

NetBird supports multiple authentication providers. This guide uses Authentik for comprehensive access control.

Configuring Authentik

Access Authentik at https://auth.vpn.yourcompany.com and create an admin account.

Create a new application:

  • Name: NetBird
  • Slug: netbird
  • Provider: OAuth2/OpenID
  • Client ID: Record for NetBird configuration
  • Client Secret: Generate and store securely

Creating User Groups and Policies

Implement role-based access control with logical group structures:

  1. Admins: Full network access
  2. Developers: Access to development and staging resources
  3. Support: Limited production access
  4. Contractors: Time-restricted access

Example access policy configuration:

groups:

name: "developers"

rules:

sources: ["dev-team"]

destinations: ["dev-servers", "staging-env"]

ports: ["22/tcp", "443/tcp", "8080/tcp"]

name: "production-access"

rules:

sources: ["ops-team"]

destinations: ["prod-servers"]

ports: ["22/tcp", "443/tcp"]

schedule: "Mon-Fri 09:00-18:00"

Client Deployment Strategies

Efficient client deployment requires platform-specific approaches.

Windows Deployment via Group Policy

Deploy NetBird using MSI packages:

Download latest MSI

Invoke-WebRequest -Uri

"https://github.com/netbirdio/netbird/releases/latest/download/netbird_installer_windows_amd64.msi" -OutFile "netbird.msi"

Deploy via GPO

msiexec /i netbird.msi ENDPOINT_URL=https://vpn.yourcompany.com /quiet

macOS Installation Script

Deploy on macOS using Homebrew:

brew install netbirdio/tap/netbird

Install Homebrew if missing

if ! command -v brew &> /dev/null; then

/bin/bash -c "$(curl -fsSL

https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" fi

Install NetBird

brew install netbirdio/tap/netbird

Configure and connect

sudo netbird up --setup-key YOUR_SETUP_KEY --management-url https://vpn.yourcompany.com

Linux One-Liner

Linux installation command:

curl -fsSL https://pkgs.netbird.io/install.sh | sudo bash

sudo netbird up --setup-key YOUR_SETUP_KEY --management-url https://vpn.yourcompany.com

Advanced Configuration and Optimization

Enhance performance and reliability with advanced configurations.

High Availability Setup

Implement redundancy with multiple service instances:

version: '3.8'

services:

netbird-management-1:

image: netbirdio/management

environment:

NETBIRD_STORE_ENGINE=postgres

NETBIRD_DB_DSN=postgresql://netbird@postgres-primary:5432/netbird

deploy:

replicas: 2

placement:

constraints:

node.labels.region == us-east

postgres-primary:

image: postgres:15-alpine

environment:

POSTGRES_REPLICATION_MODE=master

POSTGRES_REPLICATION_USER=replicator

POSTGRES_REPLICATION_PASSWORD=rep_password

volumes:

postgres_data:/var/lib/postgresql/data

postgres-replica:

image: postgres:15-alpine

environment:

POSTGRES_REPLICATION_MODE=slave

POSTGRES_MASTER_HOST=postgres-primary

POSTGRES_REPLICATION_USER=replicator

POSTGRES_REPLICATION_PASSWORD=rep_password

Performance Tuning

Optimize kernel parameters for improved networking performance:

Kernel parameters for better networking

cat << EOF | sudo tee /etc/sysctl.d/99-netbird.conf

net.core.rmem_max = 134217728

net.core.wmem_max = 134217728

net.ipv4.tcp_rmem = 4096 87380 134217728

net.ipv4.tcp_wmem = 4096 65536 134217728

net.ipv4.tcp_congestion_control = bbr

net.core.default_qdisc = fq

EOF

sudo sysctl -p /etc/sysctl.d/99-netbird.conf

Monitoring and Maintenance

Implement comprehensive monitoring for system health and performance tracking.

Prometheus Integration

Configure Prometheus for metrics collection:

prometheus.yml

global:

scrape_interval: 15s

scrape_configs:

job_name: 'netbird'

static_configs:

targets: ['management:8080']

metrics_path: '/metrics'

job_name: 'postgres'

static_configs: targets: ['postgres:9187']

Essential Metrics to Track

Monitor these key performance indicators:

  • Active peer connections
  • Authentication success/failure rates
  • TURN relay usage
  • API response times
  • Database query performance

Troubleshooting Common Issues

Address common problems with systematic troubleshooting approaches.

Connection Problems

Diagnose connection issues using this checklist:

  1. Verify firewall rules: sudo ufw status verbose
  2. Test STUN server: curl -v https://signal.vpn.yourcompany.com:3478
  3. Check Docker networking: docker network ls
  4. Examine peer logs: netbird status -d

Performance Issues

Common performance problems and solutions:

  • MTU mismatches: Set MTU to 1280 for maximum compatibility
  • DNS problems: Configure reliable DNS servers (1.1.1.1 or 8.8.8.8)
  • CPU throttling: Monitor resource usage with htop
  • Network congestion: Implement Quality of Service rules

Security Best Practices

Implement security measures to protect your NetBird deployment.

Essential Hardening Steps

Apply these security configurations:

Disable root SSH

sudo sed -i 's/PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config

Enable automatic security updates

sudo apt install unattended-upgrades

sudo dpkg-reconfigure -plow unattended-upgrades

Set up intrusion detection

sudo apt install fail2ban

sudo systemctl enable fail2ban

Regular Security Audits

Conduct monthly security reviews covering:

  • Certificate expiration dates
  • User access reviews
  • Log analysis for anomalies
  • Update availability checks
  • Backup restoration tests

Conclusion

This guide provides a complete framework for deploying and managing a self-hosted NetBird instance. The implementation delivers enterprise-grade networking capabilities with full administrative control and no recurring licensing costs.

Main implementation guidelines:

  • Begin with basic configuration and add complexity incrementally
  • Implement comprehensive monitoring from the start
  • Maintain detailed documentation of your configuration
  • Test disaster recovery procedures regularly
  • Participate in community forums for support and updates

NetBird's architecture provides powerful networking capabilities through an accessible interface. The platform scales effectively from small teams to enterprise deployments while maintaining performance and security.

For additional information, consult the NetBird documentation, explore API automation capabilities, or contribute to the open-source project. The NetBird community forums provide ongoing support and best practices sharing.