Video tutorial coming soon.
🐦 Setup NetBird — Zero-Config Mesh VPN
Deploy NetBird, a zero-configuration WireGuard-based mesh VPN with a web dashboard. Connect all your devices into a private network without complex firewall or routing setup.
📦 Resources & Setup Scripts
Grab the automated bash script from GitHub to follow along.
Quick Install:
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/vpn/netbird/netbird-ubuntu.sh
chmod +x netbird-ubuntu.sh
sudo bash netbird-ubuntu.shTutorial Steps
1 Download & Run the Script
The script installs Docker, sets up the NetBird management server, signal server, relay, and dashboard in a single stack.
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/vpn/netbird/netbird-ubuntu.sh
chmod +x netbird-ubuntu.sh
sudo bash netbird-ubuntu.sh2 Access the Dashboard
Open your browser and navigate to the NetBird dashboard:
http://YOUR-SERVER-IP:80893 Create Your Network and Invite Users
Log in to the dashboard, create your network, and generate setup keys. Share these keys with peers to add them to your private network.
4 Install NetBird on Peer Devices
Install the NetBird client on each device (Linux, macOS, Windows, iOS, Android). Run netbird up --management-url http://YOUR-SERVER:8080 --setup-key YOUR-KEY
Ports Used
| Port | Protocol | Purpose |
|---|---|---|
| 8089 | TCP | Web Dashboard |
| 8080 | TCP | Management API |
| 10000 | UDP | Signal Server |
Files Location
/root/docker/netbird/docker-compose.ymlOverview
NetBird is an open-source, WireGuard-based overlay network that creates an encrypted peer-to-peer mesh VPN between your devices. Unlike traditional VPNs with a central gateway, NetBird uses a signal server for peer discovery while all actual traffic flows directly between devices. It includes a management UI, access control policies, and network segmentation.
Why Use It
NetBird combines the simplicity of Tailscale with the control of a fully self-hosted solution. It gives you a web dashboard, access control policies per user and group, and WireGuard peer-to-peer tunnels — all without sending any network metadata to a third-party cloud. Unlike Headscale (which requires Tailscale clients), NetBird ships its own cross-platform client with a simpler setup flow and richer built-in policy management, making it the stronger self-hosted choice for teams.
When You Need It
Who Should Use It
Real Use Cases
Main Features
How to Use After Installation
Security Best Practices
Ports and Firewall Notes
NetBird uses port 8089 for the web dashboard, port 8080 for the management API (gRPC), and UDP port 10000 for the signal server. In production, place 8089 and 8080 behind Nginx Proxy Manager on HTTPS and block direct access at the firewall. The signal server (10000/UDP) must be reachable by all peer clients. The TURN relay (typically port 3478/UDP and 5349/TCP) must also be open for clients behind strict NAT. WireGuard tunnel traffic itself uses whichever UDP port is negotiated between peers.
Backup and Maintenance
Common Mistakes
Troubleshooting
Alternatives
Headscale is the closest alternative — self-hosted, WireGuard-based, uses official Tailscale clients, but has fewer built-in policy features and requires the Tailscale ecosystem. Tailscale itself (cloud-hosted) is simpler to operate but sends network metadata to Tailscale's servers. ZeroTier uses its own virtual networking protocol (not WireGuard) and offers a self-hosted controller option; it is more complex but supports larger networks. WireGuard Easy is a far simpler option if you just need a hub-and-spoke VPN without mesh routing or access policies.
When Not to Use It
Skip NetBird if you only need a simple personal VPN — WireGuard Easy handles that with far less infrastructure. If you require enterprise-grade SAML SSO, detailed audit logging, or compliance guarantees, a commercial solution is more appropriate. NetBird also adds meaningful operational complexity (signal server, TURN relay, management API, dashboard) — if your team lacks the capacity to manage this stack reliably, Tailscale's managed offering eliminates that burden.
PrismaTechWork Professional Help
PrismaTechWork provides end-to-end infrastructure services — from initial deployment and security hardening to ongoing monitoring, automated backups, and dedicated support. Whether you need a single-server setup or a multi-site network, our team ensures your infrastructure is built right, secured properly, and maintained reliably.
Frequently Asked Questions
What is the difference between NetBird and Tailscale?
Both are WireGuard-based mesh VPN solutions with zero-config peer connectivity and access control. Tailscale is a managed cloud service — your network topology lives on Tailscale's servers and the free tier has user/device limits. NetBird is fully self-hosted — you run the management server, signal server, and TURN relay yourself. NetBird is open-source with no limits on users or devices.
What is the difference between NetBird and Headscale?
Headscale is a drop-in replacement for Tailscale's control plane that uses official Tailscale clients. NetBird is an independent project with its own client app, richer built-in access control policies, and a more complete web dashboard. NetBird does not require the Tailscale client ecosystem, making it more portable. Choose Headscale if you're already using Tailscale clients; choose NetBird for a more feature-complete standalone solution.
Does NetBird traffic pass through my server?
No for most connections. NetBird establishes direct WireGuard tunnels between peers — your server only coordinates peer discovery via the signal server. Traffic flows directly between devices. The exception is TURN relay traffic when two peers cannot establish a direct tunnel due to strict NAT; in that case traffic is relayed through your TURN server.
How do I add a new device to my NetBird network?
Generate a setup key in the dashboard under Setup Keys. Install the NetBird client on the device and run: netbird up --management-url https://your-netbird-domain.com --setup-key YOUR-KEY. The device appears in the Peers list within seconds and receives a NetBird IP. Apply group membership and access policies from the dashboard.
Can I expose a private subnet through a NetBird peer?
Yes. NetBird supports network routes. Designate one peer as a 'routing peer' for a specific subnet, then add a network route in the dashboard pointing that subnet through that peer. Other peers with access to that route can then reach devices in the private subnet without each device running the NetBird client.
How do I update NetBird?
Run: docker compose -f /root/docker/netbird/docker-compose.yml pull && docker compose -f /root/docker/netbird/docker-compose.yml up -d. Back up the management data directory before pulling new images since schema changes between versions may migrate the database. Check the NetBird GitHub releases page for breaking changes before upgrading.
Can I use NetBird with SSO like Google or GitHub?
Yes. NetBird supports OAuth2/OIDC providers including Google, GitHub, Azure AD, and Keycloak. Configure your identity provider in the NetBird management server's configuration file, set the client ID and secret, and users can log in to the dashboard with their existing credentials. SSO is strongly recommended over local password accounts for production deployments.
Is NetBird suitable for large deployments with hundreds of peers?
Yes. NetBird is designed to scale. The management server handles large peer counts efficiently. For very large deployments, the signal server and TURN relay can be scaled horizontally. The dashboard's group and policy system is designed for enterprise-scale segmentation. Open-source NetBird has no artificial peer count limits — only the compute and bandwidth capacity of your servers.