Add getting started script guide with Zitadel (#76)

Add getting started script guide with Zitadel

group and update order of IDPs
This commit is contained in:
Maycon Santos
2023-08-03 20:28:05 +02:00
committed by GitHub
parent c1e17dd31c
commit ff0d3e3cd6
2 changed files with 641 additions and 585 deletions

File diff suppressed because it is too large Load Diff

View File

@@ -13,7 +13,58 @@ If you would like to learn more about the architecture please refer to the [Arch
We run NetBird in the cloud, and it will take less than 5 minutes to get started with our managed version. [Check it out!](https://netbird.io/pricing) We run NetBird in the cloud, and it will take less than 5 minutes to get started with our managed version. [Check it out!](https://netbird.io/pricing)
</Note> </Note>
## Requirements
## Getting started with NetBird and Zitadel
In this guide, we will guide you through deploying NetBird with [Zitadel](https://zitadel.com/)
as the identity provider for user management using a getting started setup script and docker containers.
<Note>
This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM.
Follow the [Advanced guide with a custom identity provider](#advanced-guide-with-a-custom-identity-provider) for installations with different IDPs.
</Note>
### Requirements
**Infrastructure requirements:**
- A Linux VM with at least **1CPU** and **2GB** of memory.
- The VM should be publicly accessible on TCP ports **80** and **443** and UDP ports: **3478**, **49152-65535**.
- **Public domain** name pointing to the VM.
**Software requirements:**
- Docker installed on the VM with the docker compose plugin ([Docker installation guide](https://docs.docker.com/engine/install/)) or docker with docker-compose in version 2 or higher.
- [jq](https://jqlang.github.io/jq/) installed. In most distributions
Usually available in the official repositories and can be installed with `sudo apt install jq` or `sudo yum install jq`
- [curl](https://curl.se/) installed.
Usually available in the official repositories and can be installed with `sudo apt install curl` or `sudo yum install curl`
### Download and run the script
Download and run the installation script in a single line:
```bash
export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh | bash
```
If you want to check the script before running it, you can download it and run it locally:
```bash
curl -sSLO https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh
# check the script
cat getting-started-with-zitadel.sh
# run the script
export NETBIRD_DOMAIN=netbird.example.com
bash getting-started-with-zitadel.sh
```
<Note>
Replace `netbird.example.com` with your domain name.
</Note>
Once the script execution is complete, you can access your netbird instance via the URL `https://netbird.example.com` using the credentials displayed in your terminal.
### Creating users
If you want to add additional users, you can access Zitadel's management console via the URL `https://netbird.example.com/ui/console` with the same credentials. Follow the [Users guide](https://zitadel.com/docs/guides/manage/console/users)
from Zitadel to add additional local users or integrate Zitadel with your existing identity provider by following the guide [Configure identity providers](https://zitadel.com/docs/guides/integrate/identity-providers).
## Advanced guide with a custom identity provider
This guide will walk you through deploying NetBird with a custom identity provider for user management.
### Requirements
- Virtual machine offered by any cloud provider (e.g., AWS, DigitalOcean, Hetzner, Google Cloud, Azure ...). - Virtual machine offered by any cloud provider (e.g., AWS, DigitalOcean, Hetzner, Google Cloud, Azure ...).
- Any Linux OS. - Any Linux OS.
@@ -25,7 +76,7 @@ If you would like to learn more about the architecture please refer to the [Arch
For this tutorial we will be using domain ```demo.netbird.io``` which points to our Ubuntu 22.04 machine hosted at Hetzner. 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 ### Step 1: Get the latest stable NetBird code
```bash ```bash
#!/bin/bash #!/bin/bash
@@ -43,7 +94,7 @@ Then switch to the infra folder that contains docker-compose file:
```bash ```bash
cd netbird/infrastructure_files/ cd netbird/infrastructure_files/
``` ```
## Step 2: Prepare configuration 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](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. 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.
@@ -80,7 +131,7 @@ This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will cr
If you want to setup netbird with your own reverse-Proxy and without using the integrated letsencrypt, follow [this step here instead](#advanced-running-netbird-behind-an-existing-reverse-proxy). If you want to setup netbird with your own reverse-Proxy and without using the integrated letsencrypt, follow [this step here instead](#advanced-running-netbird-behind-an-existing-reverse-proxy).
</Note> </Note>
## Step 3: Configure Identity Provider (IDP) ### Step 3: Configure Identity Provider (IDP)
NetBird supports generic OpenID (OIDC) protocol allowing integration with any IDP following the specification. NetBird supports generic OpenID (OIDC) protocol allowing integration with any IDP following the specification.
@@ -99,7 +150,7 @@ Pick the one that suits your needs, follow the steps, and continue with this gui
- Continue with [Okta](/selfhosted/identity-providers#okta). - Continue with [Okta](/selfhosted/identity-providers#okta).
- Continue with [Auth0](/selfhosted/identity-providers#auth0). - Continue with [Auth0](/selfhosted/identity-providers#auth0).
## Step 4: Disable single account mode (optional) ### Step 4: Disable single account mode (optional)
NetBird Management service runs in a single account mode by default since version v0.10.1. NetBird Management service runs in a single account mode by default since version v0.10.1.
Management service was creating a separate account for each registered user before v0.10.1. Management service was creating a separate account for each registered user before v0.10.1.
@@ -110,7 +161,7 @@ If you want to disable the single-account mode, set `--disable-single-account-mo
[docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl) [docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl)
`command` section of the `management` service. `command` section of the `management` service.
## Step 5: Run configuration script ### Step 5: Run configuration script
Make sure all the required properties set in the ```setup.env``` file and run: Make sure all the required properties set in the ```setup.env``` file and run:
```bash ```bash
@@ -119,12 +170,12 @@ Make sure all the required properties set in the ```setup.env``` file and run:
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.
## Step 6: Run docker compose: ### Step 6: Run docker compose:
```bash ```bash
docker-compose up -d docker-compose up -d
``` ```
## Step 7: Check docker logs (Optional) ### Step 7: Check docker logs (Optional)
```bash ```bash
docker-compose logs signal docker-compose logs signal