netbird/docs/self-hosting.md

Self-hosting

Netbird is an open-source platform that 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 a 3rd party service Auth0.

All the components can be self-hosted except for the Auth0 service. We chose Auth0 to "outsource" the user management part of the platform because we believe that implementing a proper user auth requires significant amount of time to make it right. We focused on connectivity instead. It also offers an always free plan that should be ok for most users as its limits are high enough for most teams.

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

Step-by-step video guide on YouTube:

Requirements

• Virtual machine offered by any cloud provider (e.g., AWS, DigitalOcean, Hetzner, Google Cloud, Azure ...).
• Any Unix OS.
• Docker Compose installed (see Install Docker Compose).
• Domain name pointing to the public IP address of your server.
• Netbird Open ports 443, 33071, 33073, 10000 (Dashboard, Management HTTP API, Management gRpc API, Signal gRpc) on your server.
• Coturn is used for relay using the STUN/TURN protocols. It requires a listening port, UDP 3478, and range of ports,UDP 49152-65535, for dynamic relay connections. These are set as defaults in setup file, but can be configured to your requirements.
• Maybe a cup of coffee or tea :)

Step-by-step guide

For this tutorial we will be using domain test.netbird.io which points to our Ubuntu 20.04 machine hosted at Hetzner.

1. Create Auth0 account at auth0.com.

2. Login to your server, clone Netbird repository:

   git clone https://github.com/netbirdio/netbird.git netbird/
   

   and switch to the netbird/infrastructure_files/ folder that contains docker compose file:

   cd netbird/infrastructure_files/
   

3. Prepare configuration files.

   To simplify the setup we have prepared a script to substitute required properties in the turnserver.conf.tmpl,docker-compose.yml.tmpl and management.json.tmpl files.

   The setup.env file contains the following properties that have to be filled:

   # Dashboard domain. e.g. app.mydomain.com
   NETBIRD_DOMAIN=""
   # e.g. dev-24vkclam.us.auth0.com
   NETBIRD_AUTH0_DOMAIN=""
   # e.g. 61u3JMXRO0oOevc7gCkZLCwePQvT4lL0
   NETBIRD_AUTH0_CLIENT_ID=""
   # e.g. https://app.mydomain.com/ or https://app.mydomain.com,
   # Make sure you used the exact same value for Identifier
   # you used when creating your Auth0 API
   NETBIRD_AUTH0_AUDIENCE=""
   # e.g. hello@mydomain.com
   NETBIRD_LETSENCRYPT_EMAIL=""
   

   Other options are available, but they are automatically updated.

   Please follow the steps to get the values.

4. Configure NETBIRD_AUTH0_DOMAIN NETBIRD_AUTH0_CLIENT_ID NETBIRD_AUTH0_AUDIENCE properties.

   • To obtain these, please use Auth0 React SDK Guide up until "Install the Auth0 React SDK".

     ❕ Use https://YOUR DOMAIN as Allowed Callback URLs, Allowed Logout URLs, Allowed Web Origins and Allowed Origins (CORS)

   • set the variables in the setup.env

5. Configure NETBIRD_AUTH0_AUDIENCE property.

   • Check Auth0 Golang API Guide to obtain AuthAudience.
   • set the property in the setup.env file.

6. Configure NETBIRD_LETSENCRYPT_EMAIL property.

   This can be any email address. Let's Encrypt will create an account while generating a new certificate.

7. Make sure all the properties set in the setup.env file and run:

   ./configure.sh
   

   This will export all the properties as environment variables and generate docker-compose.yml and management.json files substituting required variables.

8. Run docker compose:

   docker-compose up -d
   

9. Optionally check the logs by running:

   docker-compose logs signal
   docker-compose logs management
   docker-compose logs coturn
   docker-compose logs dashboard
   
   

10. Once the server is running, you can access the dashboard by https://$NETBIRD_DOMAIN

11. Adding a peer will require you to enter the management URL by following the steps in the page https://$NETBIRD_DOMAIN/add-peer and in the 3rd step:

sudo netbird up --setup-key <PASTE-SETUP-KEY> --management-url https://$NETBIRD_DOMAIN:33073