How To

Install NetBird Self-Hosted on Ubuntu: Tested Setup Guide

Handing out WireGuard configs stops scaling once a team grows past a few machines. NetBird replaces the key copying with a management server, a dashboard and ACLs, and the current quickstart runs the whole control plane as one container with an embedded identity provider. This guide shows you how to install NetBird self-hosted on Ubuntu, from the quickstart script to two enrolled peers talking to each other.

Original content from computingforgeeks.com - post 63514

We ran the whole thing in our lab: a fresh server VM, two Ubuntu peers, a forced relay test, a firewall pass and the store migration that trips up 0.81.x servers. This update re-tests every step on Ubuntu 24.04 against NetBird 0.82.1, the release current in November 2026, and we rechecked every link in it the same month. Every prompt, table and log line below comes from that lab, so your terminal should match what you see here.

Prerequisites

The quickstart script checks its own requirements and stops early when one is missing, but it’s faster to arrive prepared. Gather these before you start:

  • Ubuntu 26.04 or 24.04, 1 CPU, 2 GB of RAM
  • Docker Engine with the Compose v2 plugin
  • curl and jq
  • A DNS name pointing at the server’s public IP
  • Ports 80/tcp, 443/tcp and 3478/udp reachable

Those specs are the documented floor, so give the VM 4 GB if you expect the mesh to grow. A wildcard service such as sslip.io works while you test, which is what our lab used, and the self-hosting quickstart guide keeps the current requirement list if your setup differs. Pick the DNS name carefully, because every peer will carry it in its config, and renaming later means you re-enroll the whole fleet.

Install the NetBird server

The install is a single-script quickstart. NetBird’s getting-started.sh writes a three-container Compose file, and each container has one job. The netbird-server container packs the management service, the signal service, the relay and a STUN server, plus an embedded Dex identity provider. The dashboard container serves the web UI. The netbird-traefik container terminates TLS and fetches certificates from Let’s Encrypt. Only the three public ports reach the server VM in the diagram below, and peer-to-peer traffic never passes through it except as a fallback.

Self-hosted NetBird architecture: a browser and two peers reach the Traefik edge and netbird-server container over 443, while the peers exchange WireGuard traffic directly

Run the script from an empty directory, such as ~/netbird. It asks for your dashboard domain and writes its files into the directory you run it from:

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

The installer finishes with a banner listing the open ports and the dashboard URL. The files it leaves behind are the ones you will edit later:

ls -1 ~/netbird
config.yaml
dashboard.env
docker-compose.yml

Three containers should be up a minute later. Confirm, then check that the dashboard answers over valid TLS:

sudo docker ps --format 'table {{.Names}}\t{{.Status}}'

Each of the three names reports Up:

NAMES             STATUS
netbird-server    Up 3 minutes
netbird-dashboard Up 3 minutes
netbird-traefik   Up 3 minutes

Let’s Encrypt issuance takes a few seconds on a fresh domain. Once it completes, the curl check returns 200:

curl -s -o /dev/null -w '%{http_code}\n' https://netbird.192.0.2.10.sslip.io/

A screenshot of the full install session, from the script to the 200, is here for comparison if your run stalls:

Terminal output of the NetBird quickstart installer on Ubuntu ending in the setup complete banner, the files in the install directory and the three running containers

If the curl check hangs instead of returning a code, the usual cause is a firewall in front of the VM that doesn’t allow 443/tcp yet. Fix that before the setup wizard, because the certificate flow needs the port open.

Create the first admin account

Open the dashboard URL and NetBird redirects to /setup, where the embedded identity provider creates its first owner. Enter an email address and a password for the admin account, then select Create Admin Account. This account owns the instance, so use credentials you wouldn’t mind typing into a production dashboard:

NetBird setup wizard page for creating the first admin account, with the email field and the Create Admin Account button marked
  1. 1Email
  2. 2Create Admin Account

The wizard moves to the dashboard and, in this version, drops you straight into a local sign-in page. Sign in with the credentials you just created:

NetBird dashboard sign-in page for local users

Because the identity provider is embedded, this account lives inside the netbird-server container’s own Dex instance and its store, not in any external directory. Adding teammates later is a matter of creating local users in the same dashboard. When the team outgrows local accounts, wire the instance to an external IdP, which the docs cover separately.

Create a setup key for the peers

Peers join the mesh with a setup key rather than an interactive browser login, which is what makes unattended servers practical. The Peers page starts empty:

NetBird dashboard Peers page with no peers enrolled, with the Settings entry in the sidebar marked

Setup keys live under Settings, in the Setup Keys tab. Open Create Setup Key, give the key a name that says what it enrolls, and switch Make this key reusable on if more than one machine will use it. A one-off key dies after its first peer, which is exactly what you want for a single laptop but not for a fleet:

Create New Setup Key dialog with the key name field and the reusable toggle marked
  1. 1Name
  2. 2Reusable

The dashboard shows the key value exactly once, right after creation. Copy it somewhere safe in that moment; there’s no way to read it back later, only to revoke it and cut a new one. Note the default expiry of 7 days, which you can widen in the same dialog:

Newly created setup key shown once in the NetBird dashboard with its copy button marked

Keep the expiry in mind for later too. A key that expires quietly stops enrolling new peers months from now, and the client side just shows an enrollment failure that doesn’t name the key.

Join Ubuntu peers to the network

The client package comes from NetBird’s own apt repository, not from the Ubuntu archive, so add the signing key and the repo definition first. Run this on each peer machine:

curl -sSL https://pkgs.netbird.io/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/netbird-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netbird-archive-keyring.gpg] https://pkgs.netbird.io/debian stable main' | sudo tee /etc/apt/sources.list.d/netbird.list

Then install the client. The post-install script starts the netbird service immediately:

sudo apt-get update && sudo apt-get install -y netbird
netbird version

The version command should print the current release, which was 0.82.1 on our lab peers:

0.82.1

Now join the mesh. The --management-url is your dashboard domain and the setup key is the value you copied. On our second peer, named scan01:

sudo netbird up --management-url https://netbird.192.0.2.10.sslip.io --setup-key 1A2B3C4D-5E6F-7890-ABCD-EF1234567890

A successful join prints a single word and returns you to the prompt:

Connected

Back on the first peer, netbird status --table shows the mesh as the client sees it. The row for scan01 proves the two machines found each other:

sudo netbird status --table
Peers (1/1 connected):
NAME     IP            STATUS      CONN   LATENCY   RX / TX
scan01   100.78.39.5   Connected   P2P    1ms       508 B / 532 B

Each peer gets a stable 100.x address from the management server, and traffic between them rides WireGuard. The full client session, from the repo line to the connected table, looks like this:

Terminal output of adding the NetBird apt repository, installing the client, joining with a setup key and showing the peer table

Both lab peers ran Ubuntu 24.04 here, and the same steps apply on 26.04. If netbird up reports a connection refused error, the management URL is usually mistyped or the server’s 443 isn’t reachable from that network yet.

Check the connection type between peers

The CONN column is the one to watch over time. P2P means the peers exchange traffic directly, which is the fast path. Relayed means they could not punch through and are bouncing packets off your server, which costs latency and server bandwidth. The detail view shows how the connection was made:

sudo netbird status -d | grep -E 'Connection type|ICE candidate|Relay server'
  Connection type: P2P
  ICE candidate (Local/Remote): host/host
  ICE candidate endpoints (Local/Remote): 10.132.0.3:51820/10.132.0.4:51820
  Relay server address: rels://netbird.192.0.2.10.sslip.io:443

host/host means both peers offered their real addresses and agreed on a direct path. To see the fallback in action, block the WireGuard port on one peer and reconnect. The iptables rule stands in for a hostile NAT:

sudo iptables -I INPUT -p udp --dport 51820 -j DROP
sudo netbird down && sudo netbird up

The same table now reports a relayed connection, with no latency figure because the path is no longer direct:

Peers (1/1 connected):
NAME     IP            STATUS      CONN      LATENCY   RX / TX
scan01   100.78.39.5   Connected   Relayed   -         148 B / 240 B

Remove the rule and the direct path returns on the next reconnect. This matters for capacity planning, because the relay isn’t optional infrastructure. It’s what keeps peers connected when NAT defeats them, and it runs inside your netbird-server container on 443. Our full test, including the forced fallback and the recovery, is captured here:

Terminal output showing a P2P connection in netbird status, the iptables rule that forces the relayed fallback and the relayed table

On cloud VMs in the same region we saw P2P connect immediately, because their internal addresses were routable. Peers behind home routers usually still connect directly thanks to the STUN server, with the relay catching the rare stubborn case.

Open the firewall with UFW

If you run UFW on the server, allow SSH before you enable it, or the enable command will drop your session. Then add the three NetBird ports. The order here is deliberate:

sudo ufw allow 22/tcp comment 'SSH'
sudo ufw allow 80,443/tcp comment 'NetBird dashboard and API'
sudo ufw allow 3478/udp comment 'NetBird STUN'
sudo ufw enable

UFW confirms that the firewall is active and enabled on startup. The numbered status shows all six rules, three for IPv4 and their IPv6 twins:

sudo ufw status numbered
Status: active

     To                         Action      From
     --                         ------      ----
[ 1] 22/tcp                     ALLOW IN    Anywhere                   # SSH
[ 2] 80,443/tcp                 ALLOW IN    Anywhere                   # NetBird dashboard and API
[ 3] 3478/udp                   ALLOW IN    Anywhere                   # NetBird STUN
[ 4] 22/tcp (v6)                ALLOW IN    Anywhere (v6)              # SSH
[ 5] 80,443/tcp (v6)            ALLOW IN    Anywhere (v6)              # NetBird dashboard and API
[ 6] 3478/udp (v6)              ALLOW IN    Anywhere (v6)              # NetBird STUN

The dashboard should still answer with the firewall on. Run the curl check again:

curl -s -o /dev/null -w '%{http_code}\n' https://netbird.192.0.2.10.sslip.io/

A 200 means every rule held and nothing NetBird needs is blocked:

200

The full firewall session, from the first rule to the 200, is captured here for comparison:

Terminal output of the ufw rules for NetBird, with SSH allowed first, then ports 80 and 443 over TCP and 3478 over UDP, and the dashboard still returning 200

If you do get locked out anyway, because the SSH rule was missed on a host you cannot reach physically, most cloud providers offer a serial console from their web panel. Log in there, run sudo ufw allow 22/tcp, and your session comes back. Nothing else in this setup needs a port beyond the three in the list, and peer traffic never arrives at the server on 51820.

Upgrade a server that still runs on MySQL

Older NetBird releases kept their state in MySQL, and the 0.82.x line removed that store engine outright. If you upgrade the container image without migrating first, the server does not degrade, it refuses to boot and crash-loops under the restart policy. One scope note before the steps: the quickstart this guide installs is a three-container Compose stack, but its management service is single-container (the netbird-server image packs management, signal, relay and the embedded IdP), so the section below edits config.yaml in the install directory. MySQL-era servers installed the older way often run a separate management container with the MySQL DSN in management.json or a compose variable instead, and the official migration guide has a section that covers removing that DSN setting.

FATAL management/internals/server/boot.go:101: failed to open database connection: the MySQL store engine is no longer supported

That is the exact line docker logs netbird-server shows, and our lab capture caught it repeating:

Terminal output of the FATAL MySQL store refusal logged repeatedly by NetBird while the container crash loops

This line repeats in docker logs netbird-server every few seconds while the container restarts. It’s not a corruption problem and there’s nothing wrong with your data. The engine is gone from the binary. The fix is to migrate to PostgreSQL, and the official MySQL to PostgreSQL migration guide describes the same steps we ran.

The migration tool only ships in the 0.81.5 release, so download it from that tag. Do this while the server still runs the older image, because the tool expects the old schema:

curl -sSL -o netbird-mysql-migrate.tar.gz https://github.com/netbirdio/netbird/releases/download/v0.81.5/netbird-mysql-migrate_0.81.5_linux_amd64.tar.gz  # pin: tool removed from 0.82.0 # https://github.com/netbirdio/netbird/releases/tag/v0.81.5
tar xzf netbird-mysql-migrate.tar.gz && chmod +x netbird-mysql-migrate

Before anything touches the old store, copy the server’s data volume out. That volume holds events.db and idp.db, the activity log and the embedded IdP store that owns your admin account and local users, and it also gives you a rollback path if the migration goes sideways. Run these commands from the install directory, which we call ~/netbird here. Compose names the volume <project>_netbird_data, so with the quickstart’s project name it is netbird_netbird_data:

mkdir -p backup && chmod 700 backup
sudo docker run --rm -v netbird_netbird_data:/data -v ./backup:/out alpine \
  sh -c 'cp /data/events.db /data/idp.db /out/; ls -la /out'

Because the tool reads the MySQL store and writes a Postgres one, both have to be reachable from where you run it. Our lab published both ports on the host’s loopback and ran the tool there; if your stack keeps MySQL on the internal Compose network, publish it the same way with -p 127.0.0.1:3306:3306 or run the tool itself on that network. If the server is still running, stop it with sudo docker compose stop netbird-server before the backup. Start a Postgres container on the same Compose network, with a named volume so the store survives image pruning, and a database and user matching what you will put in config.yaml:

sudo docker run -d --name netbird-pg --network netbird_netbird \
  -p 127.0.0.1:5432:5432 \
  -v netbird_pg_data:/var/lib/postgresql/data \
  -e POSTGRES_DB=netbird -e POSTGRES_USER=netbird -e POSTGRES_PASSWORD=******** \
  postgres:16

The tool reads the schema it expects, so if your server is older than 0.81.5, boot it once against MySQL on the 0.81.5 image before migrating. Then run the tool with a DSN for the old MySQL store and a DSN for the Postgres database you are moving to. It reports each store it migrates and the tables it read:

sudo ./netbird-mysql-migrate \
    --mysql-dsn 'netbird:********@tcp(127.0.0.1:3306)/netbird' \
    --postgres-dsn 'host=127.0.0.1 port=5432 user=netbird password=******** dbname=netbird sslmode=disable'
activity: /var/lib/netbird/events.db not found, skipping
auth: /var/lib/netbird/idp.db not found, skipping
management: 1 rows from 39 tables
Done. Point the store, activity and auth store settings at Postgres before starting the server.

Two lines in that output deserve a note. The tool migrates the activity and IdP stores only when it finds their sqlite files; we ran it from the host without pointing it at the copies in backup/, so it skipped them and the upgraded server keeps its activity store on sqlite. On a real 0.81.x server those files usually do exist in the data volume, and the official guide shows how to hand them to the tool with --events-db and --auth-db if you want them in Postgres too. Either way, keep the backup/ directory until the upgraded server is healthy. The row count reflects a small lab; a production instance shows its real peer and policy counts here. Both DSNs use sslmode=disable because the traffic never leaves the host’s loopback; the official guide’s examples use sslmode=require, which you should match if your databases run on another machine.

Next, point config.yaml at Postgres. The file lives in the install directory, not under /etc; /etc/netbird/config.yaml is the path inside the container. Open the host copy:

sudo vim ~/netbird/config.yaml

Find the store section and change the engine, then add the dsn line under it, because the generated file ships only engine and encryptionKey. Keep the encryptionKey line that is already there, because the migration tool copies encrypted values as they are and the server needs the same key to read them:

  store:
    engine: "postgres"
    dsn: "host=netbird-pg port=5432 user=netbird password=******** dbname=netbird sslmode=disable"
    encryptionKey: "********"

The tool’s last line mentions three stores because the server runs three: the management store you just moved, plus an activity store and an auth store. Leaving those two on sqlite is fine for most servers, and the healthy boot below shows exactly that. If you did migrate the events and IdP databases, point the activity and auth store settings at Postgres the same way.

Then switch the image tag back to 0.82.1 and start the server again. One trap to avoid while editing the compose file: the Docker tags carry no v prefix, so netbirdio/netbird-server:0.81.5 is the tag and v0.81.5 does not exist:

sudo sed -i 's|image: netbirdio/netbird-server:0.81.5|image: netbirdio/netbird-server:0.82.1|' docker-compose.yml
sudo docker compose up -d netbird-server
sudo docker logs --since 1m netbird-server 2>&1 | grep -m2 -E 'Store engine|using Postgres'

The log should confirm the new engine:

  Store engine: postgres
  using Postgres store engine

Our full migration run, from the crash loop to a healthy server on Postgres, is captured in one session here:

Terminal output of the netbird-mysql-migrate tool moving rows to Postgres and the server starting healthy with the postgres store engine

Peers survive the migration untouched, because their enrollment lives in the management store you just moved. Once the server is back, run netbird status on any peer and it should reconnect without re-enrollment. If a peer doesn’t reconnect, re-check the store lines in config.yaml before you touch the peer, because the client config is rarely the problem.

NetBird or Headscale or Tailscale

NetBird is not the only way to run your own mesh control plane, and the right choice depends on how much identity work you want to own. Tailscale is the hosted option with the least to run. Headscale is the community re-implementation of its control server. NetBird sits in between, with its own dashboard, ACL engine and an embedded IdP. Here is how they compare for a small team:

NetBird self-hostedHeadscaleTailscale
Control planeOne container on your VMOne binary on your VMHosted by Tailscale
IdentityEmbedded Dex, local users or external IdPBring your own OIDC providerHosted accounts plus SSO on paid plans
Admin UIFull dashboard includedNone built in, add a third-party UIFull admin console
Setup effortOne script, three containersManual service, config and usersTwo commands per peer
Best fitSelf-hosted mesh with a UI and ACLsMinimal self-hosted tailnet controlLeast maintenance, trusted hosted control

Our own deployments split the same way. When a small team wants a dashboard and ACLs on hardware they control, NetBird is the shortest path, and this guide is that path. When the goal is a bare control server with no UI to maintain, our guide to self-hosted Headscale on Ubuntu covers the leaner build. The follow-up on running Headscale with a web UI in Docker fills its biggest gap. If a hosted control plane is acceptable, installing Tailscale on Ubuntu remains the two-command route.

For a single fixed server with no mesh at all, plain WireGuard is still fine, as the WireGuard server setup on Fedora shows. A mesh only earns its keep once several peers need to reach each other, not just you reaching one box.

Keep the server running

The whole instance lives in ~/netbird and in the Docker volumes the Compose file defines, such as netbird_netbird_data and the Postgres volume you named during the migration, so a nightly tar of that directory plus docker compose down and a copy of the volumes gives you a restorable backup. The store you migrated to Postgres matters most; back up its volume with the same schedule.

Upgrades are a docker compose pull and restart, but the MySQL removal above is the cautionary tale: a store or identity change can turn a routine upgrade into a migration. The order that keeps a Saturday morning boring is short:

  1. Read the release notes for store or identity changes
  2. Back up the store volume and the ~/netbird directory
  3. docker compose pull, then docker compose up -d
  4. Watch docker logs netbird-server until boot is clean

The one log to watch day to day is docker logs netbird-server. A healthy server prints nothing alarming after boot, and any FATAL line there means the container is about to loop, so treat it as a stop-everything signal rather than a warning.

Peers, meanwhile, need nothing from you until they expire or a key does. When the fleet starts including travelers, a dedicated device that keeps the mesh reachable from hotel Wi-Fi helps; our roundup of travel routers that run WireGuard and Tailscale covers the options we would put in a laptop bag.

This tested setup is the current version of our walkthrough on running NetBird self-hosted on Ubuntu; that address now brings you to this page.

Keep reading

Upgrade Ubuntu 24.04 to Ubuntu 26.04 LTS (Step by Step) Ubuntu Upgrade Ubuntu 24.04 to Ubuntu 26.04 LTS (Step by Step) UFW Firewall Commands with Examples on Ubuntu 26.04 / 24.04 Security UFW Firewall Commands with Examples on Ubuntu 26.04 / 24.04 Backup and Restore Linux Systems with Timeshift Debian Backup and Restore Linux Systems with Timeshift Deploy Collabora Online Office on Ubuntu with Let’s Encrypt SSL Cloud Deploy Collabora Online Office on Ubuntu with Let’s Encrypt SSL Install CyberPanel on Ubuntu 26.04 / 24.04 with Let’s Encrypt Ubuntu Install CyberPanel on Ubuntu 26.04 / 24.04 with Let’s Encrypt Install Java (OpenJDK 25) on Ubuntu 26.04 LTS Ubuntu Install Java (OpenJDK 25) on Ubuntu 26.04 LTS

Leave a Comment

Press ESC to close