NetBird VPN
NetBird is a WireGuard-based mesh VPN. HMS-Docker can run the NetBird client so your server joins your NetBird network as a peer. This works with NetBird Cloud and with a self-hosted NetBird server. HMS-Docker does not install the NetBird server itself.
-
In the NetBird dashboard, go to Setup Keys and create a key. A one-off key is enough for a single server.
-
Set the key in
inventory/group_vars/all/netbird.yml:hmsdocker_netbird_setup_key: <your setup key> -
Enable
netbirdin the Container Map and run the playbook.
The server then shows up under Peers in the NetBird dashboard.
Settings
Section titled “Settings”| Variable | Default | Description |
|---|---|---|
hmsdocker_netbird_setup_key |
Setup key used to register the server. Required when netbird is enabled. |
|
hmsdocker_netbird_management_url |
Only for a self-hosted NetBird server, for example https://netbird.example.com:443. Leave empty for NetBird Cloud. |
|
hmsdocker_netbird_hostname |
this server’s hostname | The peer name shown in NetBird. |
- The setup key is only used to register the server the first time. NetBird stores the peer’s identity in
<hmsdocker_apps_path>/netbird/state. If the key later expires or is revoked, the server stays connected. If you delete the state folder, the server registers again and needs a valid key. - If the key is invalid, the container keeps restarting. Check
docker logs netbirdfor the reason. - The container runs on its own Docker network, not the host network. To reach your server or other devices on its network from other NetBird peers, add a Network in the NetBird dashboard with this server as the routing peer, and add your server’s IP or local subnet as a resource.
Homepage widget
Section titled “Homepage widget”To show the number of online peers and users in Homepage, set homepage: true for netbird in the Container Map and add a personal access token:
hmsdocker_homepage_netbird_key: <personal access token>The token must belong to a user with the Admin role. NetBird recommends creating a service user for this. The widget uses https://api.netbird.io, or your hmsdocker_netbird_management_url if set.