some file

Self-hosting quickstart guide (5 min)

NetBird is open-source and can be self-hosted on your servers.

It relies on components developed by NetBird Authors Management Service, Management UI Dashboard, Signal Service, a 3rd party open-source STUN/TURN service Coturn, and an identity provider (available options will be listed later in this guide).

If you would like to learn more about the architecture please refer to the Architecture section.

It might be a good idea to try NetBird before self-hosting on your servers. We run NetBird in the cloud, and it will take a few clicks to get started with our managed version. Check it out!

Quick self-hosting with Zitadel IdP

In this guide, we will guide you through deploying NetBird with Zitadel as the identity provider for user management using a single-line setup script and docker containers.

This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM. Follow the Advanced guide with a custom identity provider for installations with different IDPs.

Requirements

Infrastructure requirements:

  • A Linux VM with at least 1CPU and 2GB of memory.
  • The VM should be publicly accessible on TCP ports 80, 443, 33073 and 10000; and UDP ports: 3478, 49152-65535.
  • Public domain name pointing to the VM.

Software requirements:

  • Docker installed on the VM with the docker compose plugin (Docker installation guide) or docker with docker-compose in version 2 or higher.
  • jq installed. In most distributions Usually available in the official repositories and can be installed with sudo apt install jq or sudo yum install jq
  • curl installed. Usually available in the official repositories and can be installed with sudo apt install curl or sudo yum install curl

Download and run the script

Download and run the installation script in a single line:

export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh | bash

If you want to check the script before running it, you can download it and run it locally:

curl -sSLO https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh
# check the script
cat getting-started-with-zitadel.sh
# run the script
export NETBIRD_DOMAIN=netbird.example.com
bash getting-started-with-zitadel.sh

Replace netbird.example.com with your domain name.

Once the script execution is complete, you can access your netbird instance via the URL https://netbird.example.com using the credentials displayed in your terminal.

Add users

If you want to add additional users, you can access Zitadel's management console via the URL https://netbird.example.com/ui/console with the same credentials. Follow the Users guide from Zitadel to add additional local users or integrate Zitadel with your existing identity provider by following the guide Configure identity providers.

Backup

To backup your NetBird installation, you need to copy the configuration files, the Management service databases, and Zitadel's database.

The configuration files are located in the folder where you ran the installation script. To backup, copy the files to a backup location:

mkdir backup
cp docker-compose.yml Caddyfile zitadel.env dashboard.env turnserver.conf management.json backup/

To save the Management service databases, you need to stop the Management service and copy the files from the store directory using a docker compose command as follows:

docker compose stop management
docker compose cp -a management:/var/lib/netbird/ backup/
docker compose start management

You can follow the Cockroach backup guide to backup Zitadel's database, which holds user information.

Upgrade

The users with management on version < v0.15.3 should first upgrade their systems to v0.25.9, run management to properly migrate rules to policies, and then upgrade to 0.26.0+.

To upgrade NetBird to the latest version, you need to review the release notes for any breaking changes and follow the upgrade steps below:

  1. Run the backup steps described in the backup section.
  2. Pull the latest NetBird docker images: 
    docker compose pull management dashboard signal
  3. Restart the NetBird containers with the new images: 
    docker compose up -d --force-recreate management dashboard signal

Remove

To remove the NetBird installation and all related data from your server, run these commands from the folder where you installed NetBird:

# remove all NetBird-related containers and volumes (data)
docker compose down --volumes
# remove downloaded and generated config files
rm -f docker-compose.yml Caddyfile zitadel.env dashboard.env machinekey/zitadel-admin-sa.token turnserver.conf management.json

Troubleshoot

  • I'm trying to register a user but I didn't receive a verification code. What's the problem?

    The NetBird quickstart script generates a user name and a password for the administrator. This should be enough to login and manage your network. If you want to register a new user and invite them via email, you need to configure a SMTP server in Zitadel. See this guide or details.

Get in touch

Feel free to ping us on Slack if you have any questions