import {Tiles} from "@/components/Tiles"

<YouTube videoId="bZAgpT6nzaQ" />

# Self-Hosting Quickstart Guide (5 min)

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.
</Note>

## Infrastructure requirements
- A Linux VM with at least **1CPU** and **2GB** of memory.
- 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 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`

## Installation Script

Download and run the installation script:

```bash
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash
```

Once finished, you can manage the resources via `docker compose`. The quick start script generates a full, production-ready NetBird installation. If you'd like to customize the install or gain a better understanding of the files
generated by the script, including the docker compose file, please refer to our [Configuration files](/selfhosted/configuration-files) guide.

### Reverse Proxy Selection

The script will prompt you to select a reverse proxy option:

```
Which reverse proxy will you use?
  [0] Traefik (recommended - automatic TLS, included in Docker Compose)
  [1] Existing Traefik (labels for external Traefik instance)
  [2] Nginx (generates config template)
  [3] Nginx Proxy Manager (generates config + instructions)
  [4] External Caddy (generates Caddyfile snippet)
  [5] Other/Manual (displays setup documentation)

Enter choice [0-5] (default: 0):
```

**For this quickstart guide, select option `[0]` (Traefik)** - just press Enter to use the default. This option includes a Traefik container in the Docker Compose that handles TLS certificates automatically via Let's Encrypt and requires no additional configuration.

<Note>
If you already have a reverse proxy (Traefik, Nginx, etc.) and want to use it instead, the script will guide you through the setup. See the [Reverse Proxy Configuration](/selfhosted/reverse-proxy) guide for detailed instructions on each option.
</Note>

### Generated Files

The script generates the following files:

| File | Description |
|------|-------------|
| `docker-compose.yml` | Docker Compose configuration with all services |
| `config.yaml` | Combined server configuration (management, signal, relay, STUN) |
| `dashboard.env` | Environment variables for the dashboard container |

For options 2-4, additional configuration files are generated (e.g., `nginx-netbird.conf`, `caddyfile-netbird.txt`, or `npm-advanced-config.txt`).

### Example Output

```bash
root@selfhosted-1:~/netbird# bash getting-started.sh

Which reverse proxy will you use?
  [0] Traefik (recommended - automatic TLS, included in Docker Compose)
  [1] Existing Traefik (labels for external Traefik instance)
  [2] Nginx (generates config template)
  [3] Nginx Proxy Manager (generates config + instructions)
  [4] External Caddy (generates Caddyfile snippet)
  [5] Other/Manual (displays setup documentation)

Enter choice [0-5] (default: 0):
Rendering initial files...

Starting NetBird services

[+] up 6/6
 ✔ Network combined_netbird                    Created                                                0.1s
 ✔ Volume combined_netbird_data                Created                                                0.0s
 ✔ Volume combined_netbird_traefik_letsencrypt Created                                                0.0s
 ✔ Container netbird-server                    Created                                                0.1s
 ✔ Container netbird-traefik                   Created                                                0.1s
 ✔ Container netbird-dashboard                 Created                                                0.1s
Waiting for NetBird server to become ready . . . done

Done!

You can access the NetBird dashboard at https://netbird.example.com
Follow the onboarding steps to set up your NetBird instance.
```

### Initial setup (Onboarding)

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

<p>
    <img src="/docs-static/img/selfhosted/quickstart/setup.png" alt="NetBird setup page" width="600"/>
</p>

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
   - Enter a password
   - Click **Create Account**

You can then log in with your email and 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 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.',
    },
  ]}
/>

## Enable the Reverse Proxy Feature

The quickstart installation does not include the [Reverse Proxy](/manage/reverse-proxy) feature by default. To enable it, you need to add the `netbird-proxy` container to your deployment and configure a separate proxy domain.

<Warning>
The proxy domain **must not** be a subdomain of your NetBird management domain. For example, if your management server is at `netbird.example.com`, do not use `proxy.netbird.example.com`. Use a separate subdomain like `proxy.example.com` instead. Using a subdomain of the management domain causes TLS and routing conflicts between the proxy and management services.
</Warning>

See the [Enable Reverse Proxy migration guide](/selfhosted/migration/enable-reverse-proxy) for step-by-step instructions on adding the proxy to an existing deployment, including token generation, Docker Compose configuration, and DNS setup.

## Maintenance

Once your NetBird instance is running, refer to these guides for ongoing maintenance:

<Tiles
  id="maintenance"
  items={[
    {
      href: '/selfhosted/maintenance/backup',
      name: 'Backup',
      description: 'Back up your NetBird configuration and data to protect against data loss.',
    },
    {
      href: '/selfhosted/maintenance/upgrade',
      name: 'Upgrade',
      description: 'Upgrade your NetBird installation to the latest version.',
    },
  ]}
/>

<Tiles
    id="scaling"
    items={[
        {
            href: '/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment',
            name: 'Scaling Your Self-Hosted Deployment',
            description: 'Split your NetBird deployment into multiple nodes to scale your deployment.',
        },
        {
            href: '/selfhosted/configuration-files',
            name: 'Configuration Files Reference',
            description: 'Learn more about the configuration files generated by the quick start script and how to customize them.',
        },
    ]}
/>

---

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

---

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