Self Hosted Quickstart and Other Changes (#543)
|
Before Width: | Height: | Size: 174 KiB After Width: | Height: | Size: 235 KiB |
|
After Width: | Height: | Size: 275 KiB |
|
After Width: | Height: | Size: 167 KiB |
|
After Width: | Height: | Size: 244 KiB |
|
After Width: | Height: | Size: 465 KiB |
|
After Width: | Height: | Size: 439 KiB |
|
After Width: | Height: | Size: 116 KiB |
|
After Width: | Height: | Size: 214 KiB |
|
After Width: | Height: | Size: 203 KiB |
|
After Width: | Height: | Size: 261 KiB |
|
After Width: | Height: | Size: 345 KiB |
|
After Width: | Height: | Size: 207 KiB |
@@ -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}
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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.',
|
||||
},
|
||||
]}
|
||||
/>
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||