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

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

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

Prefer not to manage the infrastructure yourself? **[NetBird Cloud](/get-started)** is the managed version of NetBird, no servers or domain required.

<div className="not-prose mb-12 mt-6 flex justify-end gap-3">
  <Button href="/about-netbird/self-hosted-vs-cloud" variant="outline-arrow" arrow="right" children="Cloud vs Self-Hosted" />
  <Button href="https://app.netbird.io" arrow="right" children="Try NetBird Cloud" />
</div>

## 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 (e.g. `netbird.example.com`).

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

<YouTube videoId="bZAgpT6nzaQ" />

## 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/maintenance/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, requires no additional configuration, and makes it easy to enable the NetBird Proxy in the next step.

<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 [External Reverse Proxy Configuration](/selfhosted/external-reverse-proxy) guide for detailed instructions on each option.
</Note>


## Enable the NetBird Proxy Service

When you select the built-in Traefik option (`[0]`), the script asks whether you want to enable the NetBird Proxy service:

```
Do you want to enable the NetBird Proxy service?
The proxy allows you to selectively expose internal NetBird network resources
to the internet. You control which resources are exposed through the dashboard.
Enable proxy? [y/N]:
```

The script then automatically generates a proxy access token, creates a `proxy.env` configuration file, and starts the proxy container alongside the other services. Point a wildcard DNS record (e.g. `*.netbird.example.com`) to your server's IP address so that service subdomains resolve correctly.

### CNAME Record for Proxy Domain

For certificates to work properly, ensure you have the proper records set with your domain name registrar. The first A record below should already be setup prior to starting the quick start script.

| Type | Name | Content | Proxy status (Cloudflare) |
|------|------|---------|--------------|
| A | `netbird` | `YOUR.SERVER.IP.ADDRESS` | DNS only |
| CNAME | `*.netbird` | `netbird.example.com` | DNS only |

If you skipped the proxy during initial setup, you can add it later by following the [Enable Reverse Proxy migration guide](/selfhosted/migration/enable-reverse-proxy).

### CrowdSec IP Reputation (Optional)

When the proxy is enabled, the script also offers to add [CrowdSec](/selfhosted/maintenance/crowdsec) for automatic IP reputation blocking. A local CrowdSec LAPI container syncs community threat intelligence and the proxy checks every incoming connection against it. You can enable CrowdSec per service in enforce or observe mode through the dashboard.

### 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 |
| `proxy.env` | Environment variables for the proxy container (only when proxy is enabled) |

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

See an example `config.yaml` file in the [NetBird GitHub repository](https://github.com/netbirdio/netbird/blob/main/combined/config.yaml.example) for a complete configuration example.

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

For automated deployments, you can create the first owner user through the setup API and optionally receive a Personal Access Token for bootstrapping resources. See [Automated setup with a Personal Access Token](/selfhosted/automated-setup). 

## Unattended installation

When you install from cloud-init, a CI pipeline, or a Terraform provisioner, nobody is there to answer the script's questions. Answer them in advance with environment variables instead, and the script installs without prompting.

For each question, the script uses the matching environment variable if it is set and not empty. An empty variable counts as unset: the script asks on the terminal, or, when there is no terminal, uses the default, or stops if the answer is required. So with no terminal at all, the script runs unattended on its own. Set `NETBIRD_NON_INTERACTIVE=true` if your automation attaches a terminal that nobody is watching.

This installs the setup from the steps above (built-in Traefik with a Let's Encrypt certificate) with no prompts:

```bash
export NETBIRD_DOMAIN=netbird.my-domain.com
export NETBIRD_LETSENCRYPT_EMAIL=admin@my-domain.com
export NETBIRD_NON_INTERACTIVE=true
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash
```

<Note>
The variables must be set for `bash`, not `curl`. Export them first, as above, or set them after the pipe: `curl -fsSL <url> | NETBIRD_DOMAIN=netbird.my-domain.com bash`. If you set them before `curl`, only `curl` sees them, and the script stops with `NETBIRD_DOMAIN is required for a non-interactive install.`
</Note>

| Variable | Default | Used with | What it sets |
|----------|---------|-----------|--------------|
| `NETBIRD_DOMAIN` | Required | Every option | The domain of your NetBird server, for example `netbird.my-domain.com` |
| `NETBIRD_LETSENCRYPT_EMAIL` | Required | Option `0` | The email address for Let's Encrypt certificate notifications |
| `NETBIRD_REVERSE_PROXY_TYPE` | `0` | Every option | The reverse proxy option, `0` to `5`, from [Reverse Proxy Selection](#reverse-proxy-selection) |
| `NETBIRD_ENABLE_PROXY` | `false` | Option `0` | Whether to enable the [NetBird Proxy service](#enable-the-net-bird-proxy-service) |
| `NETBIRD_ENABLE_CROWDSEC` | `false` | Option `0`, proxy enabled | Whether to add [CrowdSec IP reputation](#crowd-sec-ip-reputation-optional) |
| `NETBIRD_TRAEFIK_EXTERNAL_NETWORK` | Empty | Option `1` | The Docker network of your existing Traefik |
| `NETBIRD_TRAEFIK_ENTRYPOINT` | `websecure` | Option `1` | The entrypoint of your existing Traefik |
| `NETBIRD_TRAEFIK_CERTRESOLVER` | Empty | Option `1` | The certificate resolver of your existing Traefik |
| `NETBIRD_BIND_LOCALHOST_ONLY` | `true` | Options `2` to `5` | Whether NetBird's HTTP ports listen on `127.0.0.1` only |
| `NETBIRD_EXTERNAL_PROXY_NETWORK` | Empty | Options `2` to `4` | The Docker network your reverse proxy runs on |
| `NETBIRD_TRUSTED_PEERS` | The built-in Traefik's address for option `0`, empty otherwise | Every option | The address your reverse proxy reaches the NetBird server from, for example `172.20.0.5/32` |
| `NETBIRD_NON_INTERACTIVE` | Not set | Every option | `true` never prompts, even when a terminal is available |

The comment block at the top of [`getting-started.sh`](https://github.com/netbirdio/netbird/blob/main/infrastructure_files/getting-started.sh) is the authoritative list. It also has `NETBIRD_AGENT_NETWORK`, which installs the [Agent Network](/agent-network/how-it-works) preset instead of this setup. The variables need NetBird v0.77.1 or later, and `NETBIRD_TRUSTED_PEERS` needs v0.79.0 or later.

Before you automate the install, know that:

- **An invalid domain stops the script.** Unattended, a domain with a scheme (`https://`) or a port, a bare IP address, or the placeholder `netbird.example.com` ends the run instead of asking for another. A domain that does not resolve yet only prints a warning, but certificate issuance and client connections fail until it does, so create the DNS record first.
- **Set `NETBIRD_TRUSTED_PEERS` if you use your own reverse proxy (options `1` to `5`).** Without it, the NetBird server trusts forwarded client IP headers from any source, not only from your proxy. The script only prints a warning, which is easy to miss in an unattended run.
- **The script does not wait for your reverse proxy.** Interactively, options `2`, `4` and `5` pause until you confirm that your proxy is configured. Unattended, the script starts the containers straight away, and you configure the proxy afterwards.
- **A rerun never overwrites an installation.** If the directory already has a generated `config.yaml`, the script stops and lists the files to remove. Run it in a fresh directory.

Like the interactive install, an unattended install creates no users. Create the first user in the browser, as described in [Initial setup](#initial-setup-onboarding), or from your automation with the [setup API](/selfhosted/automated-setup).

## 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.',
    },
  ]}
/>

## Maintenance

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

Traefik and CrowdSec are updated separately from NetBird. See [Upgrading Traefik and CrowdSec](/selfhosted/maintenance/upgrade#upgrading-traefik-and-crowd-sec) for version selection, update steps, and verification, including the optional dashboard AppSec plugin.

<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 NetBird, Traefik, and CrowdSec, and verify your deployment.',
    },
  ]}
/>

<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/maintenance/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)