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

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:

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.

Manage Installation

Backup

To back up 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 back up, copy the files to a backup location:

mkdir backup
cp docker-compose.yml Caddyfile dashboard.env management.json relay.env backup/

To save the Management service databases, stop the Management service and copy the files from the store directory:

docker compose stop management
docker compose cp -a management:/var/lib/netbird/ backup/
docker compose start management

Upgrade

To upgrade NetBird to the latest version:

1. Run the backup steps described in the backup section.
2. Review the release notes for any breaking changes.
3. Pull the latest NetBird docker images:

   docker compose pull management dashboard signal relay
   

   CopyCopied!
4. Restart the NetBird containers with the new images:

   docker compose up -d --force-recreate management dashboard signal relay
   

   CopyCopied!

Remove

To remove the NetBird installation and all related data from your server, run these commands from the folder where you installed NetBird:

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

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