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

# Self-hosting quickstart guide (5 min)

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),
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).

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

## Quick self-hosting

<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:**
- 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.

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

### Download and run the 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
```
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>

### Initial setup (Onboarding)

The script deploys NetBird **without any users**. Once complete, you'll need to create your first user:

1. Open your browser and navigate to `https://netbird.example.com`
2. You'll be redirected to the setup page (`/setup`)
3. Create your admin account:
   - Enter your email address
   - Enter your name
   - Click **Create Account**

A password will be generated and displayed. Copy it securely—it will only be shown once. You can then log in with your email and the generated password.

<Note>
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 local users

You can add additional local users directly from the NetBird Dashboard—no external identity provider needed:

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.

### Connect identity providers (Optional)

Local users work great on their own, but 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**

**Multiple providers supported**: You can add as many OIDC-compatible identity providers as you need. Users will see all configured providers as login options.

For detailed setup guides, see [Identity Providers](/selfhosted/identity-providers).

### 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
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:
```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) section.
2. Pull the latest NetBird docker images:
    ```bash
    docker compose pull management dashboard signal relay
    ```
3. Restart the NetBird containers with the new images:
    ```bash
    docker compose up -d --force-recreate management dashboard signal relay
    ```

### Support browser clients
If you deployed NetBird before version **0.59.0** and want to use browser clients, you need to update your Signal, Management, Dashboard and Relay services, see [Upgrade](#upgrade), then you need to edit the `Caddyfile` file to enable support for browser clients by adding the following lines to the `Caddyfile`:
```
    reverse_proxy /ws-proxy/management* management:80
    reverse_proxy /ws-proxy/signal* signal:80
```
Then restart the Caddy service to apply the changes:
```bash
docker compose restart caddy
```

### Remove
To remove the NetBird installation and all related data from your server, run these commands from the folder where you installed NetBird:
```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 dashboard.env turnserver.conf management.json relay.env
```

### Troubleshoot

- **I can't access the `/setup` page**
  
  The setup page is only available when no users exist. If you've already created a user, go to the main login page instead.

- **I forgot my admin password**
  
  You can create a new user via the API using a PAT (Personal Access Token) from an existing admin, or reset the database to start fresh.

- **SSO provider not appearing on login page**
  
  Check that the connector is properly configured in **Settings** → **Identity Providers**. Ensure the redirect URL is correctly configured in your IdP.

For more troubleshooting help, see the [Troubleshooting guide](/selfhosted/troubleshooting).

---

## Legacy: Self-hosting with Zitadel IdP

<Note>
This section is for users who prefer to use Zitadel as a standalone IdP instead of local user management. For new installations, we recommend the [quickstart approach](#quick-self-hosting) above—you can always add Zitadel as an external identity provider later if needed.
</Note>

If you want to deploy NetBird with [Zitadel](https://zitadel.com/) as the identity provider, you can use the legacy quickstart script:

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

---

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