Self Hosted Quickstart and Other Changes (#543)

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

Binary file not shown.

Before

Width:  |  Height:  |  Size: 174 KiB

After

Width:  |  Height:  |  Size: 235 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 275 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 167 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 244 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 465 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 439 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 116 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 214 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 203 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 261 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 345 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 207 KiB

View File

@@ -23,6 +23,8 @@ const variantStyles = {
'rounded-full bg-zinc-900 py-1 px-3 text-white hover:bg-zinc-700 dark:bg-netbird dark:text-white dark:hover:bg-netbird-dark',
outline:
'rounded-full py-1 px-3 text-zinc-700 ring-1 ring-inset ring-zinc-900/10 hover:bg-zinc-900/2.5 hover:text-zinc-900 dark:text-zinc-400 dark:ring-white/10 dark:hover:bg-white/5 dark:hover:text-white',
'outline-arrow':
'rounded-[5px] text-zinc-700 ring-1 ring-inset ring-zinc-900/10 hover:bg-zinc-900/2.5 hover:text-zinc-900 dark:text-zinc-400 dark:ring-white/10 dark:hover:bg-white/5 dark:hover:text-white duration-300 relative overflow-hidden group',
text: 'text-netbird hover:text-netbird-dark dark:text-netbird dark:hover:text-netbird-light',
}
@@ -52,12 +54,16 @@ export function Button({
/>
)
if (variant === 'primary') {
if (variant === 'primary' || variant === 'outline-arrow') {
return (
<div className="relative inline-flex group transition-all" onClick={props.href ? undefined : props.onClick}>
{variant === 'primary' && (
<span className="absolute h-full w-full left-0 top-0 blur-sm bg-netbird z-0 transition-all duration-200 transform-gpu opacity-0 group-hover:opacity-100 pointer-events-none"></span>
)}
<Component className={className} {...props}>
{variant === 'primary' && (
<span className="absolute h-full w-full left-0 top-0 z-10 bg-gradient-to-br from-netbird to-netbird-dark transition-all duration-200 transform-gpu opacity-0 group-hover:opacity-100 pointer-events-none"></span>
)}
<span className="z-20 relative flex gap-2 items-center transition-all">
{arrow === 'left' && arrowIcon}
{children}

View File

@@ -77,7 +77,7 @@ export const Header = forwardRef(function Header({ className }, ref) {
<ModeToggle />
</div>
<div className="hidden min-[416px]:contents">
<Button href="https://app.netbird.io/" target="_blank">Try NetBird</Button>
<Button href="https://app.netbird.io/" target="_blank" className="!py-1.5 !px-3 text-xs">Try NetBird</Button>
</div>
</div>
</motion.div>

View File

@@ -42,16 +42,26 @@ function TilePattern({ mouseX, mouseY }) {
*
* @param {string} title - The heading title for the tiles section
* @param {string} [id] - Optional id for the heading anchor
* @param {string} [description] - Optional description text to display below the title
* @param {Array<{href: string, name: string, description: string}>} items - Array of tile items
* @param {string} [buttonText='Read more'] - Optional button text (defaults to "Read more")
*/
export function Tiles({ title, id, items, buttonText = 'Read more' }) {
export function Tiles({ title, id, description, items, buttonText = 'Read more' }) {
const hasHeader = title || description;
return (
<div className="my-16 xl:max-w-none">
{title && (
<Heading level={2} id={id} anchor={!!id}>
{title}
</Heading>
<div className="not-prose mt-4 grid grid-cols-1 gap-8 border-t border-zinc-900/5 pt-10 dark:border-white/5 sm:grid-cols-2">
)}
{description && (
<div className={`text-sm text-zinc-600 dark:text-zinc-400 ${title ? 'mt-4' : ''}`}>
{description}
</div>
)}
<div className={`not-prose grid grid-cols-1 gap-8 sm:grid-cols-2 ${hasHeader ? 'mt-4 border-t border-zinc-900/5 pt-10 dark:border-white/5' : ''}`}>
{items.map((item) => {
let mouseX = useMotionValue(0)
let mouseY = useMotionValue(0)

View File

@@ -25,52 +25,22 @@ It creates a high-performance point-to-point [WireGuard®](https://www.wireguard
It literally takes less than 5 minutes to deploy a secure point-to-point VPN with NetBird.
<div className="not-prose mb-16 mt-6 flex gap-3">
<Button href="https://app.netbird.io/install" arrow="right" children="Get started" />
<Button href="https://github.com/netbirdio/netbird" variant="outline" children="Explore Github" />
<Button href="https://app.netbird.io/install" arrow="right" children="Try NetBird Cloud" />
<Button href="/selfhosted/selfhosted-quickstart" variant="outline-arrow" arrow="right" children="Deploy NetBird Self-Hosted" />
</div>
<Tiles
title="About NetBird"
id="about-netbird"
items={[
{
href: '/about-netbird/how-netbird-works',
name: 'How NetBird Works',
description: 'Learn about NetBird concepts, architecture, protocols, and how it creates secure networks.',
},
{
href: '/about-netbird/netbird-vs-traditional-vpn',
name: 'NetBird vs. Traditional VPN',
description:
'Discover how NetBird compares to traditional VPNs and understand the advantages of Zero Trust networking.',
},
{
href: '/about-netbird/why-wireguard-with-netbird',
name: 'Why WireGuard with NetBird',
description:
'Explore why NetBird uses WireGuard and how it provides fast, secure, and modern networking.',
},
{
href: '/about-netbird/browser-client-architecture',
name: 'Browser Client Architecture',
description:
'Understand how the Browser Client enables secure remote access directly from web browsers using WebAssembly.',
},
]}
/>
<Tiles
title="Guides"
id="guides"
items={[
{
href: '/get-started',
name: 'Quickstart Guide',
name: 'Onboarding Guide',
description: 'Get started with NetBird in under 5 minutes. Learn the basics of installation and setup.',
},
{
href: '/selfhosted/selfhosted-quickstart',
name: 'Self-Hosted Quickstart',
name: 'Self-Host NetBird',
description: 'Get started with self-hosted NetBird in 5 minutes. Learn how to deploy and configure your own NetBird instance.',
},
{
@@ -110,4 +80,33 @@ It literally takes less than 5 minutes to deploy a secure point-to-point VPN wit
]}
/>
<Tiles
title="About NetBird"
id="about-netbird"
items={[
{
href: '/about-netbird/how-netbird-works',
name: 'How NetBird Works',
description: 'Learn about NetBird concepts, architecture, protocols, and how it creates secure networks.',
},
{
href: '/about-netbird/netbird-vs-traditional-vpn',
name: 'NetBird vs. Traditional VPN',
description:
'Discover how NetBird compares to traditional VPNs and understand the advantages of Zero Trust networking.',
},
{
href: '/about-netbird/why-wireguard-with-netbird',
name: 'Why WireGuard with NetBird',
description:
'Explore why NetBird uses WireGuard and how it provides fast, secure, and modern networking.',
},
{
href: '/about-netbird/browser-client-architecture',
name: 'Browser Client Architecture',
description:
'Understand how the Browser Client enables secure remote access directly from web browsers using WebAssembly.',
},
]}
/>

View File

@@ -1,6 +1,6 @@
import {Note} from "@/components/mdx";
# Authentik
# Authentik with NetBird Self-Hosted
[Authentik](https://goauthentik.io) is an open-source identity provider focused on flexibility and security. It serves as a self-hosted alternative to commercial solutions like Okta and Auth0, providing single sign-on (SSO), multi-factor authentication (MFA), access policies, user management, and support for SAML and OIDC protocols.

View File

@@ -1,6 +1,6 @@
import {Note} from "@/components/mdx";
# Keycloak
# Keycloak with NetBird Self-Hosted
[Keycloak](https://www.keycloak.org/) is an open-source Identity and Access Management solution maintained by Red Hat. It provides single sign-on, social login, user federation, fine-grained authorization, and supports OpenID Connect, OAuth 2.0, and SAML 2.0 protocols.

View File

@@ -1,6 +1,6 @@
import {Note} from "@/components/mdx";
# PocketID
# PocketID with NetBird Self-Hosted
[PocketID](https://pocket-id.org/) is a simplified identity management solution designed for self-hosted environments, offering a lightweight and easy-to-deploy option for authentication.

View File

@@ -1,6 +1,6 @@
import {Note} from "@/components/mdx";
# Zitadel
# Zitadel with NetBird Self-Hosted
[Zitadel](https://zitadel.com) is an open-source identity infrastructure platform designed for cloud-native environments. It provides multi-tenancy, customizable branding, passwordless authentication, and supports protocols like OpenID Connect, OAuth2, SAML2, and LDAP.
@@ -17,49 +17,118 @@ Add Zitadel as an external IdP directly in the NetBird Management Dashboard. Thi
- NetBird self-hosted with embedded IdP enabled
- Zitadel instance (cloud or self-hosted)
### Step 1: Create Application in Zitadel
### Step 1: Create a Project in Zitadel
1. Log in to your Zitadel Console
2. Navigate to your project (or create one)
3. Click **New** in the **Applications** section
4. Fill in:
2. If you don't have a project yet, click **New Project** (or navigate to an existing project)
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/01_create-project-zitadel.png" alt="Create project" className="imagewrapper-big"/>
</p>
3. Fill in the project details:
- **Name**: `NetBird` (or your preferred name)
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/02_name-project-zitadel.png" alt="Name project" className="imagewrapper-big"/>
</p>
4. Click **Create**
### Step 2: Create Application in Zitadel
1. Make sure you're in your project (select it from the project dropdown if needed)
2. Click **New** in the **Applications** section
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/03_new-app-zitadel.png" alt="New application" className="imagewrapper-big"/>
</p>
3. Fill in:
- **Name**: `NetBird`
- **Type**: `Web`
5. Click **Continue**
6. Configure authentication:
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/04_app-new-type-web-zitadel.png" alt="Application type Web" className="imagewrapper-big"/>
</p>
4. Click **Continue**
5. Configure authentication:
- **Authentication Method**: `Code` (not PKCE)
7. Leave redirect URIs empty for now
8. Click **Create**
9. Go to **Token Settings** and enable **User Info inside ID Token**
10. Note the **Client ID** and generate a **Client Secret**
### Step 2: Add Identity Provider in NetBird
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/05_app-select-code-zitadel.png" alt="Select Code authentication" className="imagewrapper-big"/>
</p>
1. Log in to your NetBird Dashboard
6. **Don't click Create yet** — you'll add the redirect URI in Step 4
### Step 3: Get Redirect URL from NetBird
1. Open a new tab or window and log in to your NetBird Dashboard
2. Navigate to **Settings** → **Identity Providers**
3. Click **Add Identity Provider**
4. Fill in the fields:
4. Fill in the fields (you can leave **Client ID and Secret** empty for now):
| Field | Value |
|-------|-------|
| Type | Zitadel |
| Name | Zitadel (or your preferred display name) |
| Client ID | From Zitadel application |
| Client Secret | From Zitadel application |
| Issuer | Your Zitadel URL (e.g., `https://your-instance.zitadel.cloud`) |
| Issuer URL | Your Zitadel URL (e.g., `https://your-instance.zitadel.cloud`) |
| Client ID | Leave empty for now |
| Client Secret | Leave empty for now |
5. Click **Save**
5. NetBird will display a **Redirect URL** — **copy this URL** (but don't click **Save** yet)
### Step 3: Configure Redirect URI
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/06_copy-callback-url-netbird-zitadel.png" alt="Copy callback URL from NetBird" className="imagewrapper-big"/>
</p>
After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Zitadel application:
### Step 4: Complete Application Configuration in Zitadel
1. Return to the Zitadel Console tab
2. In the redirect URIs field, paste the redirect URL you copied from NetBird
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/07_add_redirect-uri-zitadel.png" alt="Add redirect URI" className="imagewrapper-big"/>
</p>
3. Click **Create**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/08_click-create-app-zitadel.png" alt="Click Create application" className="imagewrapper-big"/>
</p>
4. Now you will have the Client ID and Secret displayed.
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/09_copy-client-id-zitadel.png" alt="Copy Client ID" className="imagewrapper-big"/>
</p>
### Step 5: Complete NetBird Setup
1. Return to the NetBird tab
2. In the identity provider form, paste the **Client ID and Secret** you displayed in Step 4
3. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/10_fill-netbird-config-zitadel.png" alt="Fill NetBird configuration" className="imagewrapper-big"/>
</p>
### Step 6: Configure Token Settings in Zitadel
1. Return to the Zitadel Console tab
2. Navigate to your NetBird application → **Token Settings**
3. Enable:
- **Include user's profile info in the ID Token**
- **User roles inside ID Token** (if group mapping is needed)
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/11_token-settings-zitadel.png" alt="Token settings" className="imagewrapper-big"/>
</p>
1. Return to Zitadel Console
2. Go to your application → **Redirect Settings**
3. Add the redirect URL from NetBird to **Redirect URIs**
4. Click **Save**
### Step 4: Test the Connection
### Step 7: Test the Connection
1. Log out of NetBird Dashboard
2. On the login page, you should see a "Zitadel" button

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 VMs 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)