mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-16 07:26:35 +00:00
432602e35e
- Add Reverse Proxy docs: overview, custom domains, authentication, access logs - Add Reverse Proxy section to sidebar navigation - Update self-hosted quickstart for new getting-started.sh (Traefik default, combined server)
215 lines
8.9 KiB
Plaintext
215 lines
8.9 KiB
Plaintext
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)
|