mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-16 15:36:36 +00:00
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:
File diff suppressed because it is too large
Load Diff
@@ -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)
|
||||
</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 ...).
|
||||
- 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.
|
||||
|
||||
## Step 1: Get the latest stable NetBird code
|
||||
### Step 1: Get the latest stable NetBird code
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
@@ -43,7 +94,7 @@ Then switch to the infra folder that contains docker-compose file:
|
||||
```bash
|
||||
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.
|
||||
|
||||
@@ -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).
|
||||
</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.
|
||||
|
||||
@@ -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 [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.
|
||||
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)
|
||||
`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:
|
||||
|
||||
```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.
|
||||
|
||||
## Step 6: Run docker compose:
|
||||
### Step 6: Run docker compose:
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
## Step 7: Check docker logs (Optional)
|
||||
### Step 7: Check docker logs (Optional)
|
||||
|
||||
```bash
|
||||
docker-compose logs signal
|
||||
|
||||
Reference in New Issue
Block a user