some file

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.

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.

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 Usually available in the official repositories and can be installed 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] Built-in Caddy (recommended - automatic TLS)
  [1] Traefik (labels added to containers)
  [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] (Built-in Caddy) - just press Enter to use the default. This option handles TLS certificates automatically via Let's Encrypt and requires no additional configuration.

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 guide for detailed instructions on each option.

Example Output

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

Which reverse proxy will you use?
  [0] Built-in Caddy (recommended - automatic TLS)
  [1] Traefik (labels added to containers)
  [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

[+] Running 5/5
 ✔ Network netbird                   Created
 ✔ Container netbird-dashboard       Started
 ✔ Container netbird-management      Started
 ✔ Container netbird-relay           Started
 ✔ Container netbird-signal          Started
 ✔ Container netbird-caddy           Started
Waiting for Management 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:

NetBird setup page

  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.

The /setup page is only accessible when no users exist. After creating the first user, it redirects to the regular login page.

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.

Local User Management

Create and manage users directly from the NetBird Dashboard. No external identity provider required.

Identity Providers

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:

Backup

Back up your NetBird configuration and data to protect against data loss.

Upgrade

Upgrade your NetBird installation to the latest version.

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.