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.

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) or Docker with docker-compose version 2 or higher
• jq - install with sudo apt install jq or sudo yum install jq
• curl - install with sudo apt install curl or sudo yum install curl

Installation Script

Download and run the installation script:

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

Generated Files

The script generates the following files:

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

Example Output

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:

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.

Add More Users

NetBird includes built-in local user management powered by an embedded Dex 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.

Enable the Reverse Proxy Feature

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 exposes internal NetBird network resources to the internet.
Enable proxy? [y/N]:

If you answer y, the script prompts for a proxy domain:

WARNING: The proxy domain MUST NOT be a subdomain of the NetBird management
domain (netbird.example.com). Using a subdomain will cause TLS certificate conflicts.

Enter the domain for the NetBird Proxy (e.g. proxy.my-domain.com):

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 (*.proxy.example.com) to your server's IP address so that service subdomains resolve correctly.

If you skipped the proxy during initial setup, you can add it later by following the Enable Reverse Proxy migration guide.

Maintenance

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

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.

Get In Touch

Feel free to ping us on Slack if you have any questions.

• NetBird managed version: https://app.netbird.io
• Make sure to star us on GitHub
• Follow us on X