netbird-docs/src/pages/selfhosted/selfhosted-guide.mdx

# Advanced guide

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 (IDP).

If you would like to learn more about the architecture please refer to the [architecture section](/about-netbird/how-netbird-works).

<Note>
**New to self-hosting?** The [Quickstart guide](/selfhosted/selfhosted-quickstart) uses the built-in identity provider and is the fastest way to get started. This advanced guide is for users who need to integrate with an existing IdP or have specific enterprise requirements.
</Note>

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

## When to use this guide

Use this advanced guide if you:

- Need to integrate with an **existing identity provider** (Okta, Azure AD, Auth0, etc.)
- Require **SCIM provisioning** for user/group sync (Enterprise)
- Have **compliance requirements** that mandate a specific IdP
- Want **full control** over the authentication infrastructure

For simpler deployments, the [Quickstart with embedded IdP](/selfhosted/selfhosted-quickstart) is recommended.

## Advanced self-hosting guide with a custom identity provider

### Requirements

- Virtual machine offered by any cloud provider (e.g., AWS, DigitalOcean, Hetzner, Google Cloud, Azure ...).
- Any Linux OS.
- Docker Compose installed (see [Install Docker Compose](https://docs.docker.com/compose/install/)).
- [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`
- Domain name pointing to the public IP address of your server.
- **Firewall ports** (see below for your setup type).
- Maybe a cup of coffee or tea :)

#### Port requirements

Since version 0.29, NetBird uses a consolidated port architecture where Management and Signal services share ports via HTTP/2 protocol negotiation. This significantly reduces the number of ports you need to open.

**With reverse proxy (recommended):**
| Port | Protocol | Description |
|------|----------|-------------|
| 80   | TCP      | HTTP (Let's Encrypt certificate validation, redirects to HTTPS) |
| 443  | TCP      | HTTPS (Dashboard, Management API/gRPC, Signal gRPC, Relay WebSocket) |
| 3478 | UDP      | Coturn STUN/TURN server |

**Without reverse proxy (direct exposure):**
| Port  | Protocol | Description |
|-------|----------|-------------|
| 80    | TCP      | HTTP (redirects to HTTPS) |
| 443   | TCP      | HTTPS (Dashboard, Management HTTP API) |
| 33073 | TCP      | Management gRPC API |
| 10000 | TCP      | Signal gRPC API |
| 33080 | TCP      | Relay (WebSocket/QUIC) |
| 3478  | UDP      | Coturn STUN/TURN server |

<Note>
The default setup script configures a Caddy reverse proxy that consolidates all services behind ports 80 and 443. If you're running NetBird behind your own reverse proxy, see the [advanced configuration](#advanced-running-net-bird-behind-an-existing-reverse-proxy) section.
</Note>

<Note>
**Legacy port requirements (pre-v0.29):** TCP `80, 443, 33073, 10000, 33080` plus UDP `3478` and UDP `49152-65535` (Coturn TURN relay port range). If you have any clients running versions below v0.29, you must keep these legacy ports open even if your server is upgraded - older clients cannot use the consolidated ports.
</Note>

For this tutorial we will be using domain ```demo.netbird.io``` which points to our Ubuntu 22.04 machine hosted at Hetzner.

### Step 1: Get the latest stable NetBird code

```bash
#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
# this command will fetch the latest release e.g. v0.8.7
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
echo $LATEST_TAG

# this command will clone the latest tag
git clone --depth 1 --branch $LATEST_TAG $REPO
```

Then switch to the infra folder that contains docker-compose file:

```bash
cd netbird/infrastructure_files/
```
### Step 2:  Prepare configuration files

To simplify the setup we have prepared a script to substitute required properties in the [docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl) and [management.json.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/management.json.tmpl) files.

The [setup.env.example](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/setup.env.example) file contains multiple properties that have to be filled. You need to copy the example file to `setup.env` before updating it.

```bash
## example file, you can copy this file to setup.env and update its values
##
# Dashboard domain. e.g. app.mydomain.com
NETBIRD_DOMAIN=""
# OIDC configuration e.g., https://example.eu.auth0.com/.well-known/openid-configuration
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=""
NETBIRD_AUTH_AUDIENCE=""
# e.g. netbird-client
NETBIRD_AUTH_CLIENT_ID=""
# indicates whether to use Auth0 or not: true or false
NETBIRD_USE_AUTH0="false"
NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"
# enables Interactive SSO Login feature (Oauth 2.0 Device Authorization Flow)
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
# e.g. hello@mydomain.com
NETBIRD_LETSENCRYPT_EMAIL=""
```

<Note>
    The changes made to `setup.env` will not take any effect until you run `configure.sh` (mentioned later on).
</Note>

- Set ```NETBIRD_DOMAIN``` to your domain, e.g.  `demo.netbird.io`
- Configure ```NETBIRD_LETSENCRYPT_EMAIL``` property.
This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will create an account while generating a new certificate.

<Note>
    NetBird supports automatic renewal by default when using Let's Encrypt.
</Note>

<Note>
    If you want to setup NetBird with your own reverse-Proxy and without using the integrated letsencrypt, follow [this step here instead](#advanced-running-net-bird-behind-an-existing-reverse-proxy).
</Note>

### Step 3: Configure Identity Provider (IDP)

NetBird supports generic OpenID (OIDC) protocol allowing integration with any IDP following the specification.

NetBird's management service integrates with some of the most popular IDP APIs, allowing the service to cache and display user names and email addresses without storing sensitive data.

Pick the one that suits your needs, follow the **Standalone Setup (Advanced)** section in each guide, and continue with this guide:

**Self-hosted options**
- [Zitadel](/selfhosted/identity-providers/zitadel) - Previously used in the quickstart script
- [Keycloak](/selfhosted/identity-providers/keycloak) - Popular open-source IAM
- [Authentik](/selfhosted/identity-providers/authentik) - Flexible open-source IdP
- [PocketID](/selfhosted/identity-providers/pocketid) - Lightweight self-hosted option

**Managed options**
- [Microsoft Entra ID](/selfhosted/identity-providers/managed/microsoft-entra-id) - Azure AD / Microsoft 365
- [Google Workspace](/selfhosted/identity-providers/managed/google-workspace) - Google accounts
- [Okta](/selfhosted/identity-providers/managed/okta) - Enterprise SSO
- [Auth0](/selfhosted/identity-providers/managed/auth0) - Flexible auth platform
- [JumpCloud](/selfhosted/identity-providers/managed/jumpcloud) - Cloud directory

<Note>
Each provider page includes both "Management Setup (Recommended)" (for use with the embedded IdP) and "Standalone Setup (Advanced)" sections. For this guide, follow the **Standalone Setup (Advanced)** section.
</Note>

### Step 4: Disable single account mode (optional)

NetBird Management service runs in a single account mode by default since version v0.10.1.
Management service was creating a separate account for each registered user before v0.10.1.
Single account mode ensures that all the users signing up for your self-hosted installation will join the same account/network.
In most cases, this is the desired behavior.

If you want to disable the single-account mode, set `--disable-single-account-mode` flag in the
[docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl)
`command` section of the `management` service.

### Step 5: Run configuration script
Make sure all the required properties set in the ```setup.env``` file and run:

```bash
./configure.sh
```

This will export all the properties as environment variables and generate ```artifacts/docker-compose.yml```, ```artifacts/management.json``` and ```artifacts/turnserver.conf``` files substituting required variables.

<Note>
    The changes made to `setup.env` will not take any effect until you run `configure.sh` again
</Note>

### Step 6: Run docker compose:

```bash
cd artifacts
docker compose up -d
```
### Step 7: Check docker logs (Optional)

```bash
cd artifacts
docker compose logs signal
docker compose logs management
docker compose logs coturn
docker compose logs relay
docker compose logs dashboard
```

## Advanced: Running NetBird behind an existing reverse-proxy

If you want to run NetBird behind your own reverse-proxy, some additional configuration-steps have to be taken to [Step 2](#step-2--prepare-configuration-files).

<Note>
    Not all reverse-proxies are supported as NetBird uses *gRPC* for various components.
</Note>

### Configuration for NetBird

In `setup.env`:
- Set ```NETBIRD_DOMAIN``` to your domain, e.g.  `demo.netbird.io`
- Set ```NETBIRD_DISABLE_LETSENCRYPT=true```
- Add ```NETBIRD_MGMT_API_PORT``` to your reverse-proxy TLS-port (default: 443)
- Add ```NETBIRD_SIGNAL_PORT``` to your reverse-proxy TLS-port

Optional:
- Add ```TURN_MIN_PORT``` and ```TURN_MAX_PORT``` to configure the port-range used by the Turn-server

<Note>
    The `coturn`-service still needs to be directly accessible under your set-domain as it uses UDP for communication.
</Note>

Now you can continue with [Step 3](#step-3-configure-identity-provider-idp).

### Configuration for your reverse-proxy

Depending on your port-mappings and choice of reverse-proxy, how you configure the forwards differs greatly.

The following endpoints have to be setup:

Endpoint                        | Protocol  | Target service and internal-port
------------------------------- | --------- | --------------------------------
/                               | HTTP      | dashboard:80
/signalexchange.SignalExchange/ | gRPC      | signal:80
/ws-proxy/signal                | WebSocket | signal:80
/api                            | HTTP      | management:443
/management.ManagementService/  | gRPC      | management:443
/ws-proxy/management            | WebSocket | management:443
/relay                          | WebSocket | relay:33080
:33080 (UDP)                    | QUIC      | relay:33080 (direct or L4 proxy)

Make sure your reverse-Proxy is setup to use the HTTP2-Protocol when forwarding.

<Note>
    The relay service supports two transport options: WebSocket (via `/relay`) or QUIC over UDP on port 33080 (not HTTP/3). You only need to configure one - either the WebSocket endpoint through your reverse proxy, or direct UDP access for QUIC. QUIC cannot be proxied through typical HTTP reverse proxies and must either be exposed directly or proxied using an L4 (transport layer) proxy that supports UDP. Some reverse proxies may support QUIC proxying, but this typically requires specific configuration for the custom application protocol.
</Note>

<Note>
    You can find helpful templates with the reverse-proxy-name as suffix (e.g. `docker-compose.yml.tmpl.traefik`)
    Simply replace the file `docker-compose.yml.tmpl` with the chosen version.
</Note>

## Advanced: Additional configurations for cloud providers

### Hetzner
Hetzner uses stateless [firewall](https://docs.hetzner.com/robot/dedicated-server/firewall/), which means it doesn't "keep track of" whether or not an incoming packet belongs to an established connection. In this case, you may add to this server firewall an UDP port range equals to the result of:
```bash
sudo cat /proc/sys/net/ipv4/ip_local_port_range
```
More info can be found at this GitHub [issue](https://github.com/netbirdio/netbird/issues/390#issuecomment-1185298689).

### Oracle Cloud Infrastructure (OCI)
Linux images provided by Oracle Cloud includes some default [firewall rules](https://docs.oracle.com/en-us/iaas/Content/Compute/References/bestpracticescompute.htm#Essentia) which block ingress UDP on port 3478. This is required by Coturn without which only peers in same LAN would be able to communicate with each other but not peers on different networks. Besides opening the [required ports](#port-requirements) on _Security Rules_, you also need to run below command on the virtual machine.
```bash
sudo iptables -I INPUT -p udp -m udp --dport 3478 -j ACCEPT
```
<Note>
Oracle Cloud discourages use of UFW. You will have to use IPTABLES.
</Note>

## 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
cd netbird/infrastructure_files/artifacts/
mkdir backup
cp docker-compose.yml turnserver.conf management.json openid-configuration.json 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
<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-net-bird) section.
2. Pull the latest NetBird docker images:
   ```bash
   cd netbird/infrastructure_files/artifacts/
   docker compose pull
    ```
3. Restart the NetBird containers with the new images:
   ```bash
   docker compose up -d --force-recreate
    ```

## Migrating to Embedded IdP

If you've deployed NetBird using this advanced guide and want to simplify your setup by migrating to the embedded IdP:

1. Your existing IdP can be added as an embedded IdP directly in the NetBird Management Dashboard
2. Users can continue logging in with their existing credentials
3. You can gradually transition to local user management

See the [Migration Guide](/selfhosted/identity-providers#migration-guide) for detailed instructions.

## Get in touch

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)