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.
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
curlandjq- 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.

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:

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:

- 1Email
- 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:

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:

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:

- 1Name
- 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:

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:

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:

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:

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:

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:

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-hosted | Headscale | Tailscale | |
|---|---|---|---|
| Control plane | One container on your VM | One binary on your VM | Hosted by Tailscale |
| Identity | Embedded Dex, local users or external IdP | Bring your own OIDC provider | Hosted accounts plus SSO on paid plans |
| Admin UI | Full dashboard included | None built in, add a third-party UI | Full admin console |
| Setup effort | One script, three containers | Manual service, config and users | Two commands per peer |
| Best fit | Self-hosted mesh with a UI and ACLs | Minimal self-hosted tailnet control | Least 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:
- Read the release notes for store or identity changes
- Back up the store volume and the
~/netbirddirectory docker compose pull, thendocker compose up -d- Watch
docker logs netbird-serveruntil 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.