mirror of
https://github.com/netbirdio/docs.git
synced 2026-05-04 08:16:35 +00:00
DEX Docs Overall Updates
This commit is contained in:
Brandon Hopkins
@@ -3,22 +3,22 @@
|
||||
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 an identity provider (available options will be listed later in this guide).
|
||||
a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn), and a built-in identity provider.
|
||||
|
||||
If you would like to learn more about the architecture please refer to the [Architecture section](/about-netbird/how-netbird-works).
|
||||
|
||||
<Note>
|
||||
It might be a good idea to try NetBird before self-hosting on your servers.
|
||||
We run NetBird in the cloud, and it will take a few clicks to get started with our managed version. [Check it out!](https://netbird.io/pricing)
|
||||
It might be a good idea to try NetBird before self-hosting on your servers.
|
||||
We run NetBird in the cloud, and it will take a few clicks to get started with our managed version. [Check it out!](https://netbird.io/pricing)
|
||||
</Note>
|
||||
|
||||
## Quick self-hosting with Zitadel IdP
|
||||
In this guide, we will guide you through deploying NetBird with [Zitadel](https://zitadel.com/)
|
||||
as the identity provider for user management using a single-line setup script and docker containers.
|
||||
## Quick self-hosting with embedded IdP
|
||||
|
||||
Starting with version X.XX, NetBird includes a **built-in identity provider** powered by [Dex](https://dexidp.io/). This eliminates the need for external IdP setup and is the recommended approach for new deployments.
|
||||
|
||||
<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](/selfhosted/selfhosted-guide#advanced-self-hosting-guide-with-a-custom-identity-provider) for installations with different IDPs.
|
||||
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.
|
||||
For advanced setups with custom IdPs, see the [Advanced guide](/selfhosted/selfhosted-guide).
|
||||
</Note>
|
||||
|
||||
### Requirements
|
||||
@@ -30,42 +30,72 @@ as the identity provider for user management using a single-line setup script an
|
||||
|
||||
**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`
|
||||
- [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
|
||||
export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.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
|
||||
curl -sSLO https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh
|
||||
# check the script
|
||||
cat getting-started-with-zitadel.sh
|
||||
cat getting-started.sh
|
||||
# run the script
|
||||
export NETBIRD_DOMAIN=netbird.example.com
|
||||
bash getting-started-with-zitadel.sh
|
||||
bash getting-started.sh
|
||||
```
|
||||
<Note>
|
||||
Replace `netbird.example.com` with your domain name.
|
||||
Replace `netbird.example.com` with your domain name.
|
||||
</Note>
|
||||
|
||||
### Initial setup
|
||||
|
||||
Once the script completes, open your browser and navigate to `https://netbird.example.com/setup`. You'll be prompted to create your first admin user:
|
||||
|
||||
1. Enter your email address
|
||||
2. Set a secure password
|
||||
3. Click **Create Account**
|
||||
|
||||
This creates the owner account for your NetBird instance. You can now log in to the Dashboard.
|
||||
|
||||
<Note>
|
||||
The `/setup` page is only accessible once. After creating the first user, it will redirect to the login page.
|
||||
</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.
|
||||
|
||||
### Add 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).
|
||||
|
||||
You can add users directly from the NetBird Dashboard:
|
||||
|
||||
1. Navigate to **Team** → **Users**
|
||||
2. Click **Create User**
|
||||
3. Enter the user's email and name
|
||||
4. Click **Create**
|
||||
|
||||
A password will be generated and displayed once. Share this securely with the user—it cannot be retrieved later.
|
||||
|
||||
### Add SSO (Optional)
|
||||
|
||||
Want users to sign in with Google, Microsoft, or your corporate IdP? You can add SSO connectors directly from the Dashboard:
|
||||
|
||||
1. Navigate to **Settings** → **Identity Providers**
|
||||
2. Click **Add Identity Provider**
|
||||
3. Select your provider (Google, Microsoft, Okta, etc.)
|
||||
4. Follow the provider-specific setup instructions
|
||||
|
||||
For detailed setup guides, see [Identity Provider Connectors](/selfhosted/identity-providers/connectors).
|
||||
|
||||
### Backup
|
||||
To backup your NetBird installation, you need to copy the configuration files, the Management service databases, and Zitadel's database.
|
||||
|
||||
To backup your NetBird installation, you need to copy the configuration files and the Management service databases.
|
||||
|
||||
The configuration files are located in the folder where you ran the installation script. To backup, copy the files to a backup location:
|
||||
```bash
|
||||
mkdir backup
|
||||
cp docker-compose.yml Caddyfile zitadel.env dashboard.env turnserver.conf management.json relay.env zdb.env backup/
|
||||
cp docker-compose.yml Caddyfile dashboard.env turnserver.conf management.json relay.env backup/
|
||||
```
|
||||
To save the Management service databases, you need to stop the Management service and copy the files from the store directory using a docker compose command as follows:
|
||||
```bash
|
||||
@@ -73,7 +103,6 @@ docker compose stop management
|
||||
docker compose cp -a management:/var/lib/netbird/ backup/
|
||||
docker compose start management
|
||||
```
|
||||
You can follow the [Cockroach backup guide](https://www.cockroachlabs.com/docs/stable/backup) to backup Zitadel's database, which holds user information.
|
||||
|
||||
### Upgrade
|
||||
<Note>
|
||||
@@ -110,15 +139,91 @@ To remove the NetBird installation and all related data from your server, run th
|
||||
# remove all NetBird-related containers and volumes (data)
|
||||
docker compose down --volumes
|
||||
# remove downloaded and generated config files
|
||||
rm -f docker-compose.yml Caddyfile zitadel.env dashboard.env machinekey/zitadel-admin-sa.token turnserver.conf management.json
|
||||
rm -f docker-compose.yml Caddyfile dashboard.env turnserver.conf management.json relay.env
|
||||
```
|
||||
|
||||
### Troubleshoot
|
||||
|
||||
- I'm trying to register a user but I didn't receive a verification code. What's the problem?
|
||||
- **I can't access the `/setup` page**
|
||||
|
||||
The setup page is only available when no users exist. If you've already created a user, go to the main login page instead.
|
||||
|
||||
The NetBird quickstart script generates a user name and a password for the administrator. This should be enough to login and manage your network.
|
||||
If you want to register a new user and invite them via email, you need to configure a SMTP server in Zitadel. See [this guide](https://zitadel.com/docs/guides/manage/console/instance-settings#smtp) or details.
|
||||
- **I forgot my admin password**
|
||||
|
||||
You can create a new user via the API using a PAT (Personal Access Token) from an existing admin, or reset the database to start fresh.
|
||||
|
||||
- **SSO provider not appearing on login page**
|
||||
|
||||
Check that the connector is properly configured in **Settings** → **Identity Providers**. Ensure the redirect URL is correctly configured in your IdP.
|
||||
|
||||
For more troubleshooting help, see the [Troubleshooting guide](/selfhosted/troubleshooting).
|
||||
|
||||
---
|
||||
|
||||
## Legacy: Quick self-hosting with Zitadel IdP
|
||||
|
||||
<Note>
|
||||
This section is for users who prefer to use Zitadel as a standalone IdP instead of the embedded IdP. For new installations, we recommend the [embedded IdP approach](#quick-self-hosting-with-embedded-idp) above.
|
||||
</Note>
|
||||
|
||||
If you want to deploy NetBird with [Zitadel](https://zitadel.com/) as the identity provider, you can use the legacy quickstart script:
|
||||
|
||||
### Download and run the script
|
||||
|
||||
```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:
|
||||
```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
|
||||
```
|
||||
|
||||
Once the script execution is complete, you can access your NetBird instance via `https://netbird.example.com` using the credentials displayed in your terminal.
|
||||
|
||||
### Add users (Zitadel)
|
||||
To add additional users, access Zitadel's management console via `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).
|
||||
|
||||
### Backup (Zitadel)
|
||||
To backup your NetBird installation with Zitadel, you need to copy the configuration files, the Management service databases, and Zitadel's database.
|
||||
|
||||
```bash
|
||||
mkdir backup
|
||||
cp docker-compose.yml Caddyfile zitadel.env dashboard.env turnserver.conf management.json relay.env zdb.env backup/
|
||||
```
|
||||
|
||||
To save the Management service databases:
|
||||
```bash
|
||||
docker compose stop management
|
||||
docker compose cp -a management:/var/lib/netbird/ backup/
|
||||
docker compose start management
|
||||
```
|
||||
|
||||
You can follow the [Cockroach backup guide](https://www.cockroachlabs.com/docs/stable/backup) to backup Zitadel's database, which holds user information.
|
||||
|
||||
### Remove (Zitadel)
|
||||
```bash
|
||||
# remove all NetBird-related containers and volumes (data)
|
||||
docker compose down --volumes
|
||||
# remove downloaded and generated config files
|
||||
rm -f docker-compose.yml Caddyfile zitadel.env dashboard.env machinekey/zitadel-admin-sa.token turnserver.conf management.json
|
||||
```
|
||||
|
||||
### Migrating from Zitadel to Embedded IdP
|
||||
|
||||
If you have an existing Zitadel deployment and want to migrate to the embedded IdP:
|
||||
|
||||
1. **Option A**: Keep Zitadel as a connector—add it as an SSO provider in the embedded IdP
|
||||
2. **Option B**: Recreate users in the embedded IdP and decommission Zitadel
|
||||
|
||||
See the [Migration Guide](/selfhosted/identity-providers/migration) for detailed steps.
|
||||
|
||||
---
|
||||
|
||||
## Get in touch
|
||||
|
||||
@@ -126,4 +231,4 @@ Feel free to ping us on [Slack](/slack-url) if you have any questions
|
||||
|
||||
- NetBird managed version: [https://app.netbird.io](https://app.netbird.io)
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
|
||||
- Follow us [on X](https://x.com/netbird)
|
||||
- Follow us [on X](https://x.com/netbird)
|
||||
Reference in New Issue
Block a user