Skip to content

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.

  1. In the NetBird dashboard, go to Setup Keys and create a key. A one-off key is enough for a single server.

  2. Set the key in inventory/group_vars/all/netbird.yml:

    hmsdocker_netbird_setup_key: <your setup key>
  3. Enable netbird in the Container Map and run the playbook.

The server then shows up under Peers in the NetBird dashboard.

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 netbird for 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.

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:

inventory/group_vars/all/homepage_api_keys.yml
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.