mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-19 00:46:35 +00:00
Add Reverse Proxy documentation and update self-hosted quickstart (#594)
- 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)
This commit is contained in:
shuuri-labs
@@ -13,14 +13,13 @@ This is the quickest way to try self-hosted NetBird. It should take around 5 min
|
||||
## 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.
|
||||
- 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`
|
||||
Usually available in the official repositories and can be installed with `sudo apt install curl` or `sudo yum install curl`
|
||||
- [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
|
||||
|
||||
@@ -30,8 +29,8 @@ 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](/selfhosted/configuration-files) guide.
|
||||
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
|
||||
|
||||
@@ -39,8 +38,8 @@ 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)
|
||||
[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)
|
||||
@@ -49,20 +48,32 @@ Which reverse proxy will you use?
|
||||
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.
|
||||
**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] Built-in Caddy (recommended - automatic TLS)
|
||||
[1] Traefik (labels added to containers)
|
||||
[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)
|
||||
@@ -73,14 +84,14 @@ 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
|
||||
[+] 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!
|
||||
|
||||
@@ -112,7 +123,7 @@ The `/setup` page is only accessible when no users exist. After creating the fir
|
||||
|
||||
## 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
|
||||
<Tiles
|
||||
id="user-management"
|
||||
items={[
|
||||
{
|
||||
@@ -125,9 +136,19 @@ NetBird includes built-in local user management powered by an embedded <a href="
|
||||
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:
|
||||
@@ -148,20 +169,36 @@ Once your NetBird instance is running, refer to these guides for ongoing mainten
|
||||
]}
|
||||
/>
|
||||
|
||||
<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).
|
||||
|
||||
Reference in New Issue
Block a user