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

Embedded DEX and IdP Docs (#533)

Browse Source 
* DEX Docs Overall Updates

* No IdP required, Multiple IdPs supported, Onboarding flow

* File Name Change

* Add Announcement

* Specify that Embedded IdP is Recommended

* Condense Pages to index.mdx and Extra Remove Idp Info Quickstart

* Fix Links

* Remove API Reference

* Remove Gap

* Remove API Changes

* Update Quickstart

* New Local Page and Fixes

* Fixing Gaps

* Update idp doc

* Update quickstart

* Minor changes and banner

* Fix Broken Links

* Remove Password Reset

---------

Co-authored-by: braginini <bangvalo@gmail.com>
This commit is contained in:
Brandon Hopkins
2026-01-07 10:26:54 -08:00
committed by GitHub
parent c75d0884e8
commit de7571f552
25 changed files with 2673 additions and 952 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
src/pages/selfhosted/selfhosted-quickstart.mdx
View File

@@ -1,24 +1,17 @@
# Self-hosting quickstart guide (5 min)
NetBird is open-source and can be self-hosted on your servers.
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).
and a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn).
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)
</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
<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, see the [Advanced guide](/selfhosted/selfhosted-guide).
</Note>
### Requirements
@@ -30,19 +23,186 @@ 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.sh
# check the script
cat getting-started.sh
# run the script
export NETBIRD_DOMAIN=netbird.example.com
bash getting-started.sh
```
<Note>
Replace `netbird.example.com` with your domain name.
</Note>
An example output of the script:
```bash
root@selfhosted-1:~/netbird# bash getting-started.sh
Rendering initial files...
Starting NetBird services
WARN[0000] No services to build
[+] up 9/9
✔ Network netbird-selfhosted-3_netbird Created 0.1s
✔ Volume netbird-selfhosted-3_netbird_caddy_data Created 0.0s
✔ Volume netbird-selfhosted-3_netbird_management Created 0.0s
✔ Container netbird-caddy Created 0.2s
✔ Container netbird-dashboard Created 0.2s
✔ Container netbird-management Created 0.2s
✔ Container netbird-relay Created 0.2s
✔ Container netbird-coturn Created 0.2s
✔ Container netbird-signal Created 0.2s
Waiting for Management server to become ready . . done
Done!
You can access the NetBird dashboard at https://netbird.example.com
Follow the onboarding steps to set up your NetBird instance.
```
### Initial setup (Onboarding)
The script deploys NetBird **without any users**. Once complete, you'll need to create your first user:
<p>
<img src="/docs-static/img/selfhosted/quickstart/setup.png" alt="NetBird setup page" width="600"/>
</p>
1. Open your browser and navigate to `https://netbird.example.com`
2. You'll be redirected to the setup page (`/setup`)
3. Create your admin account:
- Enter your email address
- Enter your name
- Enter a password
- Click **Create Account**
You can then log in with your email and password.
<Note>
The `/setup` page is only accessible when no users exist. After creating the first user, it redirects to the regular login page.
</Note>
### Add more users
#### Local users
You can add users directly from the NetBird Dashboard:
<p>
<img src="/docs-static/img/selfhosted/quickstart/create-user.png" alt="Add user" width="600"/>
</p>
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.
#### Via Identity Provider (Optional)
If you want users to sign in with their existing accounts from Google, Microsoft, Okta, or other providers, you can connect external identity providers:
1. Navigate to **Settings** → **Identity Providers**
2. Click **Add Identity Provider**
3. Select your provider type (Google, Microsoft, Okta, or generic OIDC)
4. Enter the OAuth client credentials from your provider
5. Click **Save**
You can add multiple identity providers. Users will see all configured providers as login options.
For detailed setup guides, see [Identity Providers](/selfhosted/identity-providers).
### Backup
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 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
docker compose stop management
docker compose cp -a management:/var/lib/netbird/ backup/
docker compose start management
```
### Upgrade
To upgrade NetBird to the latest version:
1. Run the backup steps described in the [backup](#backup) section.
2. Review the [release notes](https://github.com/netbirdio/netbird/releases) for any breaking changes.
3. Pull the latest NetBird docker images:
```bash
docker compose pull management dashboard signal relay
```
4. Restart the NetBird containers with the new images:
```bash
docker compose up -d --force-recreate management dashboard signal relay
```
<Note>
For upgrades from older versions (pre-v0.26.0), see the [Legacy upgrade notes](#legacy-self-hosting-with-zitadel-idp).
</Note>
### Remove
To remove the NetBird installation and all related data from your server, run these commands from the folder where you installed NetBird:
```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 dashboard.env turnserver.conf management.json relay.env
```
### Troubleshoot
- **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.
- **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: Self-hosting with Zitadel IdP
<Note>
**Deprecated**: This method is no longer recommended for new installations. It is preserved as a reference for users who deployed NetBird using the Zitadel quickstart script prior to version 0.62. For new installations, use the [quickstart approach](#quick-self-hosting) above.
</Note>
The following instructions apply to deployments using the `getting-started-with-zitadel.sh` script, which bundled Zitadel as an external identity provider.
### 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
@@ -50,62 +210,30 @@ cat getting-started-with-zitadel.sh
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.
### 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).
Once the script execution is complete, you can access your NetBird instance via `https://netbird.example.com` using the credentials displayed in your terminal.
### Backup
To backup your NetBird installation, you need to copy the configuration files, the Management service databases, and Zitadel's database.
### 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.
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/
```
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:
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.
### Upgrade
<Note>
The users with management on version < [v0.15.3](https://github.com/netbirdio/netbird/releases/tag/v0.15.3)
should first upgrade their systems to [v0.25.9](https://github.com/netbirdio/netbird/releases/tag/v0.25.9),
run management to properly migrate rules to policies, and then upgrade to **0.26.0+**.
</Note>
To upgrade NetBird to the latest version, you need to review the [release notes](https://github.com/netbirdio/netbird/releases) for any breaking changes and follow the upgrade steps below:
1. Run the backup steps described in the [backup](#backup) section.
2. Pull the latest NetBird docker images:
```bash
docker compose pull management dashboard signal relay
```
3. Restart the NetBird containers with the new images:
```bash
docker compose up -d --force-recreate management dashboard signal relay
```
### Support browser clients
If you deployed NetBird before version **0.59.0** and want to use browser clients, you need to update your Signal, Management, Dashboard and Relay services, see [Upgrade](#upgrade), then you need to edit the `Caddyfile` file to enable support for browser clients by adding the following lines to the `Caddyfile`:
```
reverse_proxy /ws-proxy/management* management:80
reverse_proxy /ws-proxy/signal* signal:80
```
Then restart the Caddy service to apply the changes:
```bash
docker compose restart caddy
```
### Remove
To remove the NetBird installation and all related data from your server, run these commands from the folder where you installed NetBird:
### Remove (Zitadel)
```bash
# remove all NetBird-related containers and volumes (data)
docker compose down --volumes
@@ -113,12 +241,24 @@ docker compose down --volumes
rm -f docker-compose.yml Caddyfile zitadel.env dashboard.env machinekey/zitadel-admin-sa.token turnserver.conf management.json
```
### Troubleshoot
### Migrating from Zitadel to Local Users
- I'm trying to register a user but I didn't receive a verification code. What's the problem?
If you have an existing Zitadel deployment and want to migrate:
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.
1. **Option A**: Keep Zitadel as an external provider—add it as an identity provider in Settings
2. **Option B**: Recreate users as local users and decommission Zitadel
See the [Migration Guide](/selfhosted/identity-providers#migration-guide) for detailed steps.
### Upgrade (Legacy)
<Note>
If upgrading from management version < [v0.15.3](https://github.com/netbirdio/netbird/releases/tag/v0.15.3),
first upgrade to [v0.25.9](https://github.com/netbirdio/netbird/releases/tag/v0.25.9),
run management to migrate rules to policies, then upgrade to **0.26.0+**.
</Note>
---
## Get in touch
@@ -126,4 +266,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)