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,36 +79,27 @@ 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
@@ -134,7 +110,7 @@ The configuration files are located in the folder where you ran the installation
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)