netbird-docs/docs/getting-started/self-hosting.md

sidebar_position

sidebar_position
2

Self-hosting Guide

NetBird is open-source and 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 an identity provider (available options will be listed later in this guide).

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

Requirements

• Virtual machine offered by any cloud provider (e.g., AWS, DigitalOcean, Hetzner, Google Cloud, Azure ...).
• Any Linux OS.
• Docker Compose installed (see Install Docker Compose).
• Domain name pointing to the public IP address of your server.
• Open TCP ports 80, 443, 33071, 33073, 10000 (Dashboard, Management HTTP API, Management gRpc API, Signal gRpc respectively) 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 :)

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

Step 1: Get the latest stable NetBird code

#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
# this command will fetch the latest release e.g. v0.8.7
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
echo $LATEST_TAG

# this comman will clone the latest tag
git clone --depth 1 --branch $LATEST_TAG $REPO

Then switch to the infra folder that contains docker-compose file:

cd netbird/infrastructure_files/

Step 2: Prepare configuration files

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

The setup.env.example file contains multiple properties that have to be filled. You need to copy the example file to setup.env before updating it.

# 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=""

Please follow the steps to get the values.

• Set NETBIRD_DOMAIN to your domain, e.g. demo.netbird.io

• Configure NETBIRD_LETSENCRYPT_EMAIL property:

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

  :::tip Let's Encrypt will notify you via this email when certificates are about to expire. NetBird supports automatic renewal by default. :::

Step 3: Configure Identity Provider

Step 4: Run configuration script

Make sure all the required 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.

Step 5: Run docker compose:

docker-compose up -d

Step 5: Check docker logs (Optional)

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

Get in touch

Feel free to ping us on Slack if you have any questions

• NetBird managed version: https://app.netbird.io
• Make sure to star us on GitHub 🙏
• Follow us on Twitter