sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-18 08:26:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add IDP integrations for self-hosted Netbird

Browse Source
This commit is contained in:
braginini
2022-08-16 11:39:44 +02:00
parent 69324bab12
commit ec5e278f82
10 changed files with 562 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
docs/getting-started/self-hosting.md
View File

@@ -7,22 +7,11 @@ sidebar_position: 2
NetBird is open-source and can be self-hosted on your servers.
It relies on components developed by NetBird Authors [Management Service](https://github.com/netbirdio/netbird/tree/main/management), [Management UI Dashboard](https://github.com/netbirdio/dashboard), [Signal Service](https://github.com/netbirdio/netbird/tree/main/signal),
a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn) and a 3rd party service [Auth0](https://auth0.com/).
:::info auth0
All the components can be self-hosted except for the Auth0 service.
This service offers excellent support for multiple features that we need, and it saved us lots of time.
We couldn't find any suitable open-source solution that would be a good combination of effort and benefit.
There is a free plan that can fulfill most of the personal use-cases.
There were a few discussions about alternatives on [GitHub](https://github.com/netbirdio/dashboard/issues/9).
We'd greatly appreciate any help on integrating one of the open-source Auth0 alternatives.
:::
a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/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](/overview/architecture).
:::
### Requirements
@@ -34,89 +23,76 @@ If you would like to learn more about the architecture please refer to the [Arch
- 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 ```demo.netbird.io``` which points to our Ubuntu 22.04 machine hosted at Hetzner.
1. Create Auth0 account at [auth0.com](https://auth0.com/).
2. Get latest released NetBird code:
### Step 1: Get the latest stable NetBird code
```bash
#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
# this command will fetch the latest release e.g. v0.6.1
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
```
```bash
#!/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
and switch to the infra folder that contains docker-compose file:
# this comman will clone the latest tag
git clone --depth 1 --branch $LATEST_TAG $REPO
```
```bash
cd netbird/infrastructure_files/
```
3. Prepare configuration files.
Then switch to the infra folder that contains docker-compose file:
To simplify the setup we have prepared a script to substitute required properties in the [docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl) and [management.json.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/management.json.tmpl) files.
```bash
cd netbird/infrastructure_files/
```
### Step 2: Prepare configuration files
The [setup.env.example](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/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.
:::tip
You need to fill only the first 5 properties, the rest will be filled automatically at a later step.
:::
```bash
# 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=""
```
To simplify the setup we have prepared a script to substitute required properties in the [docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl) and [management.json.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/management.json.tmpl) files.
Please follow the steps to get the values.
The [setup.env.example](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/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.
4. Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
```bash
# 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=""
```
5. Configure Auth0 ```NETBIRD_AUTH0_DOMAIN``` ```NETBIRD_AUTH0_CLIENT_ID``` properties.
Please follow the steps to get the values.
* To obtain these, please use [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0) up until "Install the Auth0 React SDK".
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
- Configure ```NETBIRD_LETSENCRYPT_EMAIL``` property:
> 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```
* :warning: Make sure that `Token Endpoint Authentication Method` is set to `None` in your Auth0 Default Application
6. Configure ```NETBIRD_AUTH0_AUDIENCE``` property.
This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will create an account while generating a new certificate.
* Check [Auth0 Create An API](https://auth0.com/docs/quickstart/backend/golang#create-an-api) section to obtain AuthAudience.
* set the property in the ```setup.env``` file.
7. Configure ```NETBIRD_LETSENCRYPT_EMAIL``` property.
:::tip
Let's Encrypt will notify you via this email when certificates are about to expire. NetBird supports automatic renewal by default.
:::
This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will create an account while generating a new certificate.
### Step 3: Configure Identity Provider
:::tip
Let's Encrypt will notify you via this email when certificates are about to expire. NetBird supports automatic renewal by default.
:::
8. Make sure all the required properties set in the ```setup.env``` file and run:
### Step 4: Run configuration script
Make sure all the required properties set in the ```setup.env``` file and run:
```bash
./configure.sh
```
```bash
./configure.sh
```
This will export all the properties as environment variables and generate ```docker-compose.yml``` and ```management.json``` files substituting required variables.
This will export all the properties as environment variables and generate ```docker-compose.yml``` and ```management.json``` files substituting required variables.
9. Run docker compose:
### Step 5: Run docker compose:
```bash
docker-compose up -d
```
10. Optionally check the logs by running:
```bash
docker-compose up -d
```
### Step 5: Check docker logs (Optional)
```bash
docker-compose logs signal