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

Self Hosted Quickstart and Other Changes (#543)

Browse Source
This commit is contained in:
Brandon Hopkins
2026-01-13 01:59:05 -08:00
committed by GitHub
parent 2901b505ba
commit 105e6774db
21 changed files with 196 additions and 209 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,49 +1,34 @@
# Self-hosting quickstart guide (5 min)
import {Tiles} from "@/components/Tiles"
NetBird is open source and can be self-hosted on your servers.
# Self-Hosting Quickstart Guide (5 min)
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),
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).
## Quick self-hosting
NetBird is open source and can be self-hosted on your servers. If you would like to learn more about the architecture please refer to the [Architecture section](/about-netbird/how-netbird-works).
<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.
For advanced setups, see the [Advanced guide](/selfhosted/selfhosted-guide).
</Note>
### Requirements
**Infrastructure requirements:**
## Infrastructure requirements
- A Linux VM with at least **1CPU** and **2GB** of memory.
- The VM should be publicly accessible on TCP ports **80 (Let's Encrypt)**, **443 (NetBird control plane)**; and UDP ports: **3478 (STUN)**.
- **Public domain** name pointing to the VM.
- The VM must be publicly accessible on **TCP ports 80 and 443**, and **UDP port 3478**.
- A **public domain** name that resolves to the VM’s public IP address.
**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`
## Software requirements
### Download and run the script
- Docker with docker-compose plugin ([Docker installation guide](https://docs.docker.com/engine/install/)) or Docker with docker-compose version 2 or higher
- [jq](https://jqlang.github.io/jq/) — install with `sudo apt install jq` or `sudo yum install jq`
- [curl](https://curl.se/) — install with `sudo apt install curl` or `sudo yum install curl`
Usually available in the official repositories and can be installed with `sudo apt install curl` or `sudo yum install curl`
## Installation Script
Download and run the installation 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.sh | bash
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>
Once finished, you can manage the resources via `docker compose`.
An example output of the script:
@@ -94,47 +79,38 @@ You can then log in with your email and password.
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
## Add More Users
NetBird includes built-in local user management powered by an embedded <a href="https://dexidp.io/" target="_blank" rel="noopener noreferrer">Dex</a> server, allowing you to create and manage users directly from the Dashboard without requiring an external identity provider. You can also add external identity providers for SSO authentication alongside local users.
<Tiles
id="user-management"
items={[
{
href: '/selfhosted/identity-providers/local',
name: 'Local User Management',
description: 'Create and manage users directly from the NetBird Dashboard. No external identity provider required.',
},
{
href: '/selfhosted/identity-providers',
name: 'Identity Providers',
description: 'Connect external identity providers like Google, Microsoft, Okta, or self-hosted IdPs for SSO authentication.',
},
]}
/>
#### 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).
## Manage Installation
### Backup
To backup your NetBird installation, you need to copy the configuration files and the Management service databases.
To back up 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:
The configuration files are located in the folder where you ran the installation script. To back up, 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:
To save the Management service databases, stop the Management service and copy the files from the store directory:
```bash
docker compose stop management
docker compose cp -a management:/var/lib/netbird/ backup/
@@ -169,7 +145,7 @@ docker compose down --volumes
rm -f docker-compose.yml Caddyfile dashboard.env turnserver.conf management.json relay.env
```
### Troubleshoot
## Troubleshoot
- **I can't access the `/setup` page**
@@ -187,82 +163,9 @@ For more troubleshooting help, see the [Troubleshooting guide](/selfhosted/troub
---
## 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
# 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 Local Users
If you have an existing Zitadel deployment and want to migrate:
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
Feel free to ping us on [Slack](/slack-url) if you have any questions
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)