mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-15 23:16:36 +00:00
Add Reverse Proxy Templates + Wizard Instructions to Docs (#551)
* Add Reverse Proxy Templates + Wizard Instructions to Docs - Updated quickstart guide to include instructions on new reverse proxy wizard in setup script - Add new reverse proxy page including quickstart script instructions and templates - Updated advanced guide to refer to new reverse proxy page * Update lazy-connection documentation to clarify inactivity threshold configuration. from #452 * Added <Note> * Update lazy connection documentation to reflect new minimum supported agent version and server requirements. From PR#338 * traefik ssl amendments + nginx fixes * - add youtube video to self hosted quickstart guide page - clarify quickstart script reverse proxy wizard behaviour in advanced guide * added in-depth TLS instructions for nginx * add individual proxy hyperlinks to self hosted advanced guide --------- Co-authored-by: Brandon Hopkins <brandon@techhut.tv>
This commit is contained in:
shuuri-labs
@@ -314,7 +314,8 @@ export const docsNavigation = [
|
||||
},
|
||||
]
|
||||
},
|
||||
{ title: 'Advanced guide', href: '/selfhosted/selfhosted-guide' },
|
||||
{ title: 'Reverse Proxy', href: '/selfhosted/reverse-proxy' },
|
||||
{ title: 'Advanced Guide', href: '/selfhosted/selfhosted-guide' },
|
||||
{ title: 'Management SQLite Store', href: '/selfhosted/sqlite-store' },
|
||||
{ title: 'Management Postgres Store', href: '/selfhosted/postgres-store' },
|
||||
{ title: 'Activity Events Postgres Store', href: '/selfhosted/activity-postgres-store' },
|
||||
|
||||
@@ -6,13 +6,13 @@ NetBird now includes an experimental lazy connection feature designed to improve
|
||||
This guide walks you through enabling and configuring this feature in your NetBird client.
|
||||
|
||||
<Note>
|
||||
Minimum supported agent version: <strong>v0.45.0</strong>.
|
||||
Minimum supported agent version: <strong>v0.50.1</strong>.
|
||||
This or higher version must also be installed on the peers you are trying to access for lazy connections to function.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
This feature also requires an upgraded NetBird Management server.
|
||||
If you're self-hosting NetBird, ensure your server is updated to version <strong>v0.45.0</strong>, which adds support for lazy connections.
|
||||
This feature also requires an upgraded NetBird Management and Signal server.
|
||||
If you're self-hosting NetBird, ensure your server is updated to version <strong>v0.50.1</strong>, which adds support for lazy connections.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
@@ -25,7 +25,7 @@ When enabled, lazy connections allow the NetBird agent to:
|
||||
|
||||
- Establish peer-to-peer connections **only when needed** (e.g., when pinging a remote peer).
|
||||
- Monitor peer activity and **automatically disconnect peers** that remain inactive **and unreachable** for a specified time.
|
||||
- Keep critical peers (such as routers or excluded peers) **always connected** to ensure uninterrupted communication.
|
||||
- Keep critical peers (such as excluded peers) **always connected** to ensure uninterrupted communication.
|
||||
|
||||
This feature is especially useful in **large-scale deployments** or **resource-constrained environments**, where maintaining full-mesh, permanent connections to all peers is unnecessary and inefficient.
|
||||
|
||||
@@ -36,16 +36,12 @@ This feature is especially useful in **large-scale deployments** or **resource-c
|
||||
|
||||
### How Automatic Disconnection Works
|
||||
|
||||
Once a connection between two peers is established, it will remain open **as long as the remote peer is reachable**. The connection is **not** closed just because there is no data transfer.
|
||||
|
||||
In other words, the inactivity timer only triggers a disconnect if the peer is both <em>inactive</em> and <em>unreachable</em> for the full duration of the threshold.
|
||||
Once a connection between two peers is established, it will remain open only if there is ongoing traffic from the remote peer. If no traffic is received for 15 minutes, the connection will be closed — even if the remote peer is still reachable.
|
||||
|
||||
<Note>
|
||||
The default inactivity threshold is <strong>60 minutes</strong>, and can be configured via the <code>NB_LAZY_CONN_INACTIVITY_THRESHOLD</code> environment variable.
|
||||
The default inactivity threshold is <strong>60 minutes</strong>, and can be configured via the <code>NB_LAZY_CONN_INACTIVITY_THRESHOLD</code> environment variable (`60`).
|
||||
</Note>
|
||||
|
||||
Additionally, the disconnection logic is being improved and will be enhanced in future releases to better support mobile devices—providing more intelligent reconnection behavior and improved handling of intermittent connectivity.
|
||||
|
||||
## Enabling Lazy Connections on agent
|
||||
|
||||
Lazy connections are disabled by default. You can enable Lazy Connections using the following environment variable:
|
||||
|
||||
949
src/pages/selfhosted/reverse-proxy.mdx
Normal file
949
src/pages/selfhosted/reverse-proxy.mdx
Normal file
@@ -0,0 +1,949 @@
|
||||
# Reverse Proxy Configuration
|
||||
|
||||
NetBird includes a built-in Caddy reverse proxy that handles TLS certificates automatically. However, if you already have an existing reverse proxy (Traefik, Nginx, etc.), you can configure NetBird to work with it instead.
|
||||
|
||||
<Note>
|
||||
Not all reverse proxies are supported as NetBird uses *gRPC* for various components. Your reverse proxy must support HTTP/2 and gRPC proxying.
|
||||
</Note>
|
||||
|
||||
## Quick Setup
|
||||
|
||||
### New Deployments
|
||||
|
||||
The `getting-started.sh` script supports multiple reverse proxy configurations. During initial deployment, you'll be prompted to select your reverse proxy:
|
||||
|
||||
```
|
||||
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)
|
||||
```
|
||||
|
||||
The script will generate the appropriate configuration files and provide setup instructions for your chosen proxy.
|
||||
|
||||
<Note>
|
||||
This option is only available during initial setup with `getting-started.sh`. For existing deployments, use the manual configuration templates below.
|
||||
</Note>
|
||||
|
||||
### Existing Deployments
|
||||
|
||||
For existing NetBird installations, use the configuration templates in the sections below to manually configure your reverse proxy.
|
||||
|
||||
## Required Routing Endpoints
|
||||
|
||||
All reverse proxy configurations must route the following endpoints:
|
||||
|
||||
| Path | Protocol | Target | Notes |
|
||||
|------|----------|--------|-------|
|
||||
| `/relay*` | WebSocket | relay:80 | WebSocket upgrade required |
|
||||
| `/ws-proxy/signal*` | WebSocket | signal:80 | WebSocket upgrade required |
|
||||
| `/signalexchange.SignalExchange/*` | gRPC | signal:10000 | HTTP/2 (h2c) required |
|
||||
| `/api/*` | HTTP | management:80 | REST API |
|
||||
| `/ws-proxy/management*` | WebSocket | management:80 | WebSocket upgrade required |
|
||||
| `/management.ManagementService/*` | gRPC | management:80 | HTTP/2 (h2c) required |
|
||||
| `/oauth2/*` | HTTP | management:80 | Embedded IdP |
|
||||
| `/*` | HTTP | dashboard:80 | Catch-all for dashboard |
|
||||
|
||||
<Note>
|
||||
The `coturn` service still needs to be directly accessible on UDP port 3478 as it handles STUN/TURN traffic.
|
||||
</Note>
|
||||
|
||||
## Docker Compose for External Proxy
|
||||
|
||||
When using an external reverse proxy, expose the NetBird container ports to the host:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
dashboard:
|
||||
image: netbirdio/dashboard:latest
|
||||
ports:
|
||||
- '127.0.0.1:8080:80'
|
||||
# ... other config
|
||||
|
||||
signal:
|
||||
image: netbirdio/signal:latest
|
||||
ports:
|
||||
- '127.0.0.1:8083:80'
|
||||
- '127.0.0.1:10000:10000'
|
||||
# ... other config
|
||||
|
||||
relay:
|
||||
image: netbirdio/relay:latest
|
||||
ports:
|
||||
- '127.0.0.1:8084:80'
|
||||
# ... other config
|
||||
|
||||
management:
|
||||
image: netbirdio/management:latest
|
||||
ports:
|
||||
- '127.0.0.1:8081:80'
|
||||
# ... other config
|
||||
```
|
||||
|
||||
<Note>
|
||||
Binding to `127.0.0.1` is recommended when your reverse proxy runs on the same host. This prevents direct access to the containers and ensures all traffic goes through the proxy.
|
||||
</Note>
|
||||
|
||||
### Container Port Reference
|
||||
|
||||
| Service | Host Port | Container Port | Protocol |
|
||||
|---------|-----------|----------------|----------|
|
||||
| Dashboard | 8080 | 80 | HTTP |
|
||||
| Signal (HTTP) | 8083 | 80 | HTTP/WebSocket |
|
||||
| Signal (gRPC) | 10000 | 10000 | gRPC (h2c) |
|
||||
| Management | 8081 | 80 | HTTP/gRPC |
|
||||
| Relay | 8084 | 80 | WebSocket |
|
||||
|
||||
---
|
||||
|
||||
## Configuration Templates
|
||||
|
||||
### Traefik
|
||||
|
||||
For Traefik, NetBird containers are configured with Docker labels for automatic service discovery. The `getting-started.sh` script will prompt for your Traefik configuration:
|
||||
|
||||
- **External network**: The Docker network your Traefik container uses
|
||||
- **HTTPS entrypoint**: Your Traefik entrypoint for HTTPS traffic (commonly `websecure`)
|
||||
- **Certificate resolver**: Your Traefik certresolver for automatic TLS (e.g., `letsencrypt`)
|
||||
|
||||
#### Complete Docker Compose with Traefik Labels
|
||||
|
||||
Add the following labels to your NetBird services in `docker-compose.yml`. Replace:
|
||||
- `netbird.example.com` with your domain
|
||||
- `websecure` with your HTTPS entrypoint name
|
||||
- `letsencrypt` with your certificate resolver name (or remove the certresolver lines if handling TLS externally)
|
||||
|
||||
```yaml
|
||||
services:
|
||||
dashboard:
|
||||
image: netbirdio/dashboard:latest
|
||||
networks: [traefik-network]
|
||||
labels:
|
||||
- traefik.enable=true
|
||||
- traefik.http.routers.netbird-dashboard.rule=Host(`netbird.example.com`)
|
||||
- traefik.http.routers.netbird-dashboard.entrypoints=websecure
|
||||
- traefik.http.routers.netbird-dashboard.tls=true
|
||||
- traefik.http.routers.netbird-dashboard.tls.certresolver=letsencrypt
|
||||
- traefik.http.routers.netbird-dashboard.priority=1
|
||||
- traefik.http.services.netbird-dashboard.loadbalancer.server.port=80
|
||||
|
||||
signal:
|
||||
image: netbirdio/signal:latest
|
||||
networks: [traefik-network]
|
||||
labels:
|
||||
- traefik.enable=true
|
||||
# WebSocket router
|
||||
- traefik.http.routers.netbird-signal-ws.rule=Host(`netbird.example.com`) && PathPrefix(`/ws-proxy/signal`)
|
||||
- traefik.http.routers.netbird-signal-ws.entrypoints=websecure
|
||||
- traefik.http.routers.netbird-signal-ws.tls=true
|
||||
- traefik.http.routers.netbird-signal-ws.tls.certresolver=letsencrypt
|
||||
- traefik.http.routers.netbird-signal-ws.service=netbird-signal-ws
|
||||
- traefik.http.services.netbird-signal-ws.loadbalancer.server.port=80
|
||||
# gRPC router
|
||||
- traefik.http.routers.netbird-signal-grpc.rule=Host(`netbird.example.com`) && PathPrefix(`/signalexchange.SignalExchange/`)
|
||||
- traefik.http.routers.netbird-signal-grpc.entrypoints=websecure
|
||||
- traefik.http.routers.netbird-signal-grpc.tls=true
|
||||
- traefik.http.routers.netbird-signal-grpc.tls.certresolver=letsencrypt
|
||||
- traefik.http.routers.netbird-signal-grpc.service=netbird-signal-grpc
|
||||
- traefik.http.services.netbird-signal-grpc.loadbalancer.server.port=10000
|
||||
- traefik.http.services.netbird-signal-grpc.loadbalancer.server.scheme=h2c
|
||||
|
||||
relay:
|
||||
image: netbirdio/relay:latest
|
||||
networks: [traefik-network]
|
||||
labels:
|
||||
- traefik.enable=true
|
||||
- traefik.http.routers.netbird-relay.rule=Host(`netbird.example.com`) && PathPrefix(`/relay`)
|
||||
- traefik.http.routers.netbird-relay.entrypoints=websecure
|
||||
- traefik.http.routers.netbird-relay.tls=true
|
||||
- traefik.http.routers.netbird-relay.tls.certresolver=letsencrypt
|
||||
- traefik.http.services.netbird-relay.loadbalancer.server.port=80
|
||||
|
||||
management:
|
||||
image: netbirdio/management:latest
|
||||
networks: [traefik-network]
|
||||
labels:
|
||||
- traefik.enable=true
|
||||
# API router
|
||||
- traefik.http.routers.netbird-api.rule=Host(`netbird.example.com`) && PathPrefix(`/api`)
|
||||
- traefik.http.routers.netbird-api.entrypoints=websecure
|
||||
- traefik.http.routers.netbird-api.tls=true
|
||||
- traefik.http.routers.netbird-api.tls.certresolver=letsencrypt
|
||||
- traefik.http.routers.netbird-api.service=netbird-api
|
||||
- traefik.http.services.netbird-api.loadbalancer.server.port=80
|
||||
# Management WebSocket router
|
||||
- traefik.http.routers.netbird-mgmt-ws.rule=Host(`netbird.example.com`) && PathPrefix(`/ws-proxy/management`)
|
||||
- traefik.http.routers.netbird-mgmt-ws.entrypoints=websecure
|
||||
- traefik.http.routers.netbird-mgmt-ws.tls=true
|
||||
- traefik.http.routers.netbird-mgmt-ws.tls.certresolver=letsencrypt
|
||||
- traefik.http.routers.netbird-mgmt-ws.service=netbird-mgmt-ws
|
||||
- traefik.http.services.netbird-mgmt-ws.loadbalancer.server.port=80
|
||||
# Management gRPC router
|
||||
- traefik.http.routers.netbird-mgmt-grpc.rule=Host(`netbird.example.com`) && PathPrefix(`/management.ManagementService/`)
|
||||
- traefik.http.routers.netbird-mgmt-grpc.entrypoints=websecure
|
||||
- traefik.http.routers.netbird-mgmt-grpc.tls=true
|
||||
- traefik.http.routers.netbird-mgmt-grpc.tls.certresolver=letsencrypt
|
||||
- traefik.http.routers.netbird-mgmt-grpc.service=netbird-mgmt-grpc
|
||||
- traefik.http.services.netbird-mgmt-grpc.loadbalancer.server.port=80
|
||||
- traefik.http.services.netbird-mgmt-grpc.loadbalancer.server.scheme=h2c
|
||||
# OAuth2 router (embedded IdP)
|
||||
- traefik.http.routers.netbird-oauth2.rule=Host(`netbird.example.com`) && PathPrefix(`/oauth2`)
|
||||
- traefik.http.routers.netbird-oauth2.entrypoints=websecure
|
||||
- traefik.http.routers.netbird-oauth2.tls=true
|
||||
- traefik.http.routers.netbird-oauth2.tls.certresolver=letsencrypt
|
||||
- traefik.http.routers.netbird-oauth2.service=netbird-oauth2
|
||||
- traefik.http.services.netbird-oauth2.loadbalancer.server.port=80
|
||||
|
||||
networks:
|
||||
traefik-network:
|
||||
external: true
|
||||
```
|
||||
|
||||
#### Traefik Configuration Requirements
|
||||
|
||||
Your Traefik instance must have the following configured:
|
||||
|
||||
**1. HTTPS Entrypoint** (listening on port 443):
|
||||
```yaml
|
||||
# In traefik.yml or as command args
|
||||
entryPoints:
|
||||
websecure:
|
||||
address: ":443"
|
||||
```
|
||||
|
||||
**2. Certificate Resolver** (for automatic Let's Encrypt certificates):
|
||||
```yaml
|
||||
certificatesResolvers:
|
||||
letsencrypt:
|
||||
acme:
|
||||
email: your-email@example.com
|
||||
storage: /letsencrypt/acme.json
|
||||
httpChallenge:
|
||||
entryPoint: web
|
||||
```
|
||||
|
||||
**3. Docker Provider** with exposedByDefault disabled:
|
||||
```yaml
|
||||
providers:
|
||||
docker:
|
||||
exposedByDefault: false
|
||||
```
|
||||
|
||||
**4. HTTP to HTTPS Redirect** (recommended):
|
||||
```yaml
|
||||
entryPoints:
|
||||
web:
|
||||
address: ":80"
|
||||
http:
|
||||
redirections:
|
||||
entryPoint:
|
||||
to: websecure
|
||||
scheme: https
|
||||
```
|
||||
|
||||
#### Example Traefik Docker Compose
|
||||
|
||||
If you don't have Traefik set up yet, here's a complete example:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
traefik:
|
||||
image: traefik:v3.2
|
||||
command:
|
||||
- "--api.insecure=true"
|
||||
- "--providers.docker=true"
|
||||
- "--providers.docker.exposedByDefault=false"
|
||||
- "--entrypoints.web.address=:80"
|
||||
- "--entrypoints.web.http.redirections.entrypoint.to=websecure"
|
||||
- "--entrypoints.web.http.redirections.entrypoint.scheme=https"
|
||||
- "--entrypoints.websecure.address=:443"
|
||||
- "--certificatesresolvers.letsencrypt.acme.email=your-email@example.com"
|
||||
- "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
|
||||
- "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
- "8080:8080" # Traefik dashboard (optional)
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
- ./letsencrypt:/letsencrypt
|
||||
networks:
|
||||
- traefik-network
|
||||
|
||||
networks:
|
||||
traefik-network:
|
||||
name: traefik-network
|
||||
```
|
||||
|
||||
<Note>
|
||||
When using `getting-started.sh` with Traefik, the script will ask for your network name, entrypoint, and certresolver. It will then generate a docker-compose.yml with all the correct labels pre-configured.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
### Nginx
|
||||
|
||||
#### Nginx running in Docker
|
||||
|
||||
If Nginx is running in Docker, the easiest approach is to have NetBird join the same Docker network. The `getting-started.sh` script will ask for your Nginx network name and configure everything automatically.
|
||||
|
||||
```nginx
|
||||
# NetBird Nginx Configuration (Docker network)
|
||||
# Uses container names for upstream servers
|
||||
|
||||
upstream netbird_dashboard {
|
||||
server netbird-dashboard:80;
|
||||
keepalive 10;
|
||||
}
|
||||
upstream netbird_signal {
|
||||
server netbird-signal:10000;
|
||||
}
|
||||
upstream netbird_signal_ws {
|
||||
server netbird-signal:80;
|
||||
}
|
||||
upstream netbird_management {
|
||||
server netbird-management:80;
|
||||
}
|
||||
upstream netbird_relay {
|
||||
server netbird-relay:80;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
server_name netbird.example.com;
|
||||
location / {
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name netbird.example.com;
|
||||
|
||||
ssl_certificate /path/to/fullchain.pem;
|
||||
ssl_certificate_key /path/to/privkey.pem;
|
||||
|
||||
# Required for long-lived gRPC connections
|
||||
client_header_timeout 1d;
|
||||
client_body_timeout 1d;
|
||||
|
||||
# Common proxy headers
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Scheme $scheme;
|
||||
proxy_set_header X-Forwarded-Proto https;
|
||||
proxy_set_header X-Forwarded-Host $host;
|
||||
grpc_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
|
||||
# Relay (WebSocket)
|
||||
location /relay {
|
||||
proxy_pass http://netbird_relay;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "Upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_read_timeout 1d;
|
||||
}
|
||||
|
||||
# Signal WebSocket
|
||||
location /ws-proxy/signal {
|
||||
proxy_pass http://netbird_signal_ws;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "Upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_read_timeout 1d;
|
||||
}
|
||||
|
||||
# Signal gRPC
|
||||
location /signalexchange.SignalExchange/ {
|
||||
grpc_pass grpc://netbird_signal;
|
||||
grpc_read_timeout 1d;
|
||||
grpc_send_timeout 1d;
|
||||
grpc_socket_keepalive on;
|
||||
}
|
||||
|
||||
# Management API
|
||||
location /api/ {
|
||||
proxy_pass http://netbird_management;
|
||||
proxy_set_header Host $host;
|
||||
}
|
||||
|
||||
# Management WebSocket
|
||||
location /ws-proxy/management {
|
||||
proxy_pass http://netbird_management;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "Upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_read_timeout 1d;
|
||||
}
|
||||
|
||||
# Management gRPC
|
||||
location /management.ManagementService/ {
|
||||
grpc_pass grpc://netbird_management;
|
||||
grpc_read_timeout 1d;
|
||||
grpc_send_timeout 1d;
|
||||
grpc_socket_keepalive on;
|
||||
}
|
||||
|
||||
# Embedded IdP OAuth2
|
||||
location /oauth2/ {
|
||||
proxy_pass http://netbird_management;
|
||||
proxy_set_header Host $host;
|
||||
}
|
||||
|
||||
# Dashboard (catch-all)
|
||||
location / {
|
||||
proxy_pass http://netbird_dashboard;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Nginx running on host (not in Docker)
|
||||
|
||||
If Nginx is installed directly on the host, use localhost addresses:
|
||||
|
||||
```nginx
|
||||
# NetBird Nginx Configuration
|
||||
# Replace netbird.example.com with your domain
|
||||
# Update SSL certificate paths
|
||||
|
||||
upstream netbird_dashboard {
|
||||
server 127.0.0.1:8080;
|
||||
keepalive 10;
|
||||
}
|
||||
upstream netbird_signal {
|
||||
server 127.0.0.1:10000;
|
||||
}
|
||||
upstream netbird_signal_ws {
|
||||
server 127.0.0.1:8083;
|
||||
}
|
||||
upstream netbird_management {
|
||||
server 127.0.0.1:8081;
|
||||
}
|
||||
upstream netbird_relay {
|
||||
server 127.0.0.1:8084;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
server_name netbird.example.com;
|
||||
location / {
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name netbird.example.com;
|
||||
|
||||
ssl_certificate /path/to/fullchain.pem;
|
||||
ssl_certificate_key /path/to/privkey.pem;
|
||||
|
||||
# Required for long-lived gRPC connections
|
||||
client_header_timeout 1d;
|
||||
client_body_timeout 1d;
|
||||
|
||||
# Common proxy headers
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Scheme $scheme;
|
||||
proxy_set_header X-Forwarded-Proto https;
|
||||
proxy_set_header X-Forwarded-Host $host;
|
||||
grpc_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
|
||||
# Relay (WebSocket)
|
||||
location /relay {
|
||||
proxy_pass http://netbird_relay;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "Upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_read_timeout 1d;
|
||||
}
|
||||
|
||||
# Signal WebSocket
|
||||
location /ws-proxy/signal {
|
||||
proxy_pass http://netbird_signal_ws;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "Upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_read_timeout 1d;
|
||||
}
|
||||
|
||||
# Signal gRPC
|
||||
location /signalexchange.SignalExchange/ {
|
||||
grpc_pass grpc://netbird_signal;
|
||||
grpc_read_timeout 1d;
|
||||
grpc_send_timeout 1d;
|
||||
grpc_socket_keepalive on;
|
||||
}
|
||||
|
||||
# Management API
|
||||
location /api/ {
|
||||
proxy_pass http://netbird_management;
|
||||
proxy_set_header Host $host;
|
||||
}
|
||||
|
||||
# Management WebSocket
|
||||
location /ws-proxy/management {
|
||||
proxy_pass http://netbird_management;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "Upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_read_timeout 1d;
|
||||
}
|
||||
|
||||
# Management gRPC
|
||||
location /management.ManagementService/ {
|
||||
grpc_pass grpc://netbird_management;
|
||||
grpc_read_timeout 1d;
|
||||
grpc_send_timeout 1d;
|
||||
grpc_socket_keepalive on;
|
||||
}
|
||||
|
||||
# Embedded IdP OAuth2
|
||||
location /oauth2/ {
|
||||
proxy_pass http://netbird_management;
|
||||
proxy_set_header Host $host;
|
||||
}
|
||||
|
||||
# Dashboard (catch-all)
|
||||
location / {
|
||||
proxy_pass http://netbird_dashboard;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Installation:**
|
||||
|
||||
Debian/Ubuntu:
|
||||
```bash
|
||||
sudo ln -s /path/to/netbird.conf /etc/nginx/sites-available/netbird
|
||||
sudo ln -s /etc/nginx/sites-available/netbird /etc/nginx/sites-enabled/
|
||||
sudo nginx -t && sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
RHEL/CentOS:
|
||||
```bash
|
||||
sudo cp /path/to/netbird.conf /etc/nginx/conf.d/netbird.conf
|
||||
sudo nginx -t && sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
#### TLS Certificate Setup for Nginx
|
||||
|
||||
<Note>
|
||||
**Important difference:** Unlike Caddy which obtains and renews TLS certificates automatically, Nginx requires manual certificate setup and configuration.
|
||||
</Note>
|
||||
|
||||
You'll need to obtain SSL/TLS certificates and update the certificate paths in your Nginx configuration. Here are the most common options:
|
||||
|
||||
**Option 1: Let's Encrypt with Certbot (Recommended)**
|
||||
|
||||
Let's Encrypt provides free, automated TLS certificates with automatic renewal.
|
||||
|
||||
1. Install certbot:
|
||||
```bash
|
||||
# Debian/Ubuntu
|
||||
sudo apt install certbot python3-certbot-nginx
|
||||
|
||||
# RHEL/CentOS
|
||||
sudo yum install certbot python3-certbot-nginx
|
||||
```
|
||||
|
||||
2. Obtain certificate:
|
||||
```bash
|
||||
# If Nginx is already running
|
||||
sudo certbot certonly --nginx -d netbird.example.com
|
||||
|
||||
# If Nginx isn't running yet (standalone mode)
|
||||
sudo certbot certonly --standalone -d netbird.example.com
|
||||
```
|
||||
|
||||
3. Update your Nginx config with the certificate paths:
|
||||
```nginx
|
||||
ssl_certificate /etc/letsencrypt/live/netbird.example.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/netbird.example.com/privkey.pem;
|
||||
```
|
||||
|
||||
4. Set up automatic renewal:
|
||||
```bash
|
||||
# Certbot automatically installs a systemd timer for renewal
|
||||
# Test the renewal process:
|
||||
sudo certbot renew --dry-run
|
||||
```
|
||||
|
||||
<Note>
|
||||
**Requirements for Let's Encrypt:**
|
||||
- Your domain must point to your server's public IP
|
||||
- Port 80 must be accessible from the internet for certificate validation
|
||||
- Certificates are valid for 90 days and renewed automatically by certbot
|
||||
</Note>
|
||||
|
||||
**Option 2: Let's Encrypt with acme.sh**
|
||||
|
||||
[acme.sh](https://github.com/acmesh-official/acme.sh) is a lightweight alternative to certbot:
|
||||
|
||||
```bash
|
||||
# Install acme.sh
|
||||
curl https://get.acme.sh | sh
|
||||
|
||||
# Issue certificate
|
||||
~/.acme.sh/acme.sh --issue -d netbird.example.com --nginx
|
||||
|
||||
# Update Nginx config with paths:
|
||||
# ssl_certificate /root/.acme.sh/netbird.example.com/fullchain.cer;
|
||||
# ssl_certificate_key /root/.acme.sh/netbird.example.com/netbird.example.com.key;
|
||||
```
|
||||
|
||||
**Option 3: Custom/Commercial Certificates**
|
||||
|
||||
If you have certificates from another provider:
|
||||
|
||||
1. Place your certificate files on the server:
|
||||
```bash
|
||||
sudo cp fullchain.pem /etc/ssl/certs/netbird.crt
|
||||
sudo cp privkey.pem /etc/ssl/private/netbird.key
|
||||
sudo chmod 600 /etc/ssl/private/netbird.key
|
||||
```
|
||||
|
||||
2. Update your Nginx config:
|
||||
```nginx
|
||||
ssl_certificate /etc/ssl/certs/netbird.crt;
|
||||
ssl_certificate_key /etc/ssl/private/netbird.key;
|
||||
```
|
||||
|
||||
**TLS Best Practices**
|
||||
|
||||
The generated Nginx configurations include recommended TLS settings:
|
||||
|
||||
```nginx
|
||||
# Use modern TLS protocols only
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
|
||||
# Let clients choose the best cipher
|
||||
ssl_prefer_server_ciphers off;
|
||||
|
||||
# Strong cipher suites
|
||||
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
|
||||
```
|
||||
|
||||
These settings ensure:
|
||||
- Only TLS 1.2 and 1.3 are allowed (older protocols like TLS 1.0/1.1 are disabled)
|
||||
- Modern cipher suites that support forward secrecy
|
||||
- Compatibility with all modern browsers and NetBird clients
|
||||
|
||||
---
|
||||
|
||||
### Caddy (External)
|
||||
|
||||
#### Caddy running in Docker
|
||||
|
||||
If Caddy is running in Docker, the easiest approach is to have NetBird join the same Docker network. The `getting-started.sh` script will ask for your Caddy network name and configure everything automatically.
|
||||
|
||||
```
|
||||
netbird.example.com {
|
||||
# Relay (WebSocket)
|
||||
reverse_proxy /relay* netbird-relay:80
|
||||
|
||||
# Signal WebSocket
|
||||
reverse_proxy /ws-proxy/signal* netbird-signal:80
|
||||
|
||||
# Signal gRPC (h2c for plaintext HTTP/2)
|
||||
reverse_proxy /signalexchange.SignalExchange/* h2c://netbird-signal:10000
|
||||
|
||||
# Management API
|
||||
reverse_proxy /api/* netbird-management:80
|
||||
|
||||
# Management WebSocket
|
||||
reverse_proxy /ws-proxy/management* netbird-management:80
|
||||
|
||||
# Management gRPC
|
||||
reverse_proxy /management.ManagementService/* h2c://netbird-management:80
|
||||
|
||||
# Embedded IdP OAuth2
|
||||
reverse_proxy /oauth2/* netbird-management:80
|
||||
|
||||
# Dashboard (catch-all)
|
||||
reverse_proxy /* netbird-dashboard:80
|
||||
}
|
||||
```
|
||||
|
||||
#### Caddy running on host (not in Docker)
|
||||
|
||||
If Caddy is installed directly on the host, use localhost addresses:
|
||||
|
||||
```
|
||||
netbird.example.com {
|
||||
# Relay (WebSocket)
|
||||
reverse_proxy /relay* 127.0.0.1:8084
|
||||
|
||||
# Signal WebSocket
|
||||
reverse_proxy /ws-proxy/signal* 127.0.0.1:8083
|
||||
|
||||
# Signal gRPC (h2c for plaintext HTTP/2)
|
||||
reverse_proxy /signalexchange.SignalExchange/* h2c://127.0.0.1:10000
|
||||
|
||||
# Management API
|
||||
reverse_proxy /api/* 127.0.0.1:8081
|
||||
|
||||
# Management WebSocket
|
||||
reverse_proxy /ws-proxy/management* 127.0.0.1:8081
|
||||
|
||||
# Management gRPC
|
||||
reverse_proxy /management.ManagementService/* h2c://127.0.0.1:8081
|
||||
|
||||
# Embedded IdP OAuth2
|
||||
reverse_proxy /oauth2/* 127.0.0.1:8081
|
||||
|
||||
# Dashboard (catch-all)
|
||||
reverse_proxy /* 127.0.0.1:8080
|
||||
}
|
||||
```
|
||||
|
||||
After adding the configuration, reload Caddy:
|
||||
```bash
|
||||
sudo systemctl reload caddy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Nginx Proxy Manager
|
||||
|
||||
Nginx Proxy Manager requires all NetBird routing to be configured via the "Advanced" tab. The Custom Locations feature doesn't properly handle path prefixes.
|
||||
|
||||
<Note>
|
||||
NPM requires backend services to be running before you can create proxy hosts. The `getting-started.sh` script will start NetBird containers first, then display the configuration instructions.
|
||||
</Note>
|
||||
|
||||
#### NPM running in Docker (recommended)
|
||||
|
||||
If NPM is running in Docker, the easiest approach is to have NetBird join the same Docker network. The script will ask for your NPM network name and configure everything automatically.
|
||||
|
||||
**1. Create a Proxy Host in NPM:**
|
||||
- Domain: `netbird.example.com`
|
||||
- Forward Hostname/IP: `netbird-dashboard`
|
||||
- Forward Port: `80`
|
||||
- Block Common Exploits: enabled
|
||||
|
||||
**2. SSL tab:**
|
||||
- Request or select existing certificate
|
||||
- **Enable "HTTP/2 Support"** (required for gRPC)
|
||||
|
||||
**3. Advanced tab - paste this configuration:**
|
||||
|
||||
```nginx
|
||||
# Required for long-lived connections (gRPC and WebSocket)
|
||||
client_header_timeout 1d;
|
||||
client_body_timeout 1d;
|
||||
|
||||
# Relay WebSocket
|
||||
location /relay {
|
||||
proxy_pass http://netbird-relay:80;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_read_timeout 1d;
|
||||
}
|
||||
|
||||
# Signal WebSocket
|
||||
location /ws-proxy/signal {
|
||||
proxy_pass http://netbird-signal:80;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_read_timeout 1d;
|
||||
}
|
||||
|
||||
# Management WebSocket
|
||||
location /ws-proxy/management {
|
||||
proxy_pass http://netbird-management:80;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_read_timeout 1d;
|
||||
}
|
||||
|
||||
# API routes
|
||||
location /api/ {
|
||||
proxy_pass http://netbird-management:80;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
# OAuth2/IdP routes
|
||||
location /oauth2/ {
|
||||
proxy_pass http://netbird-management:80;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
# gRPC for Signal service
|
||||
location /signalexchange.SignalExchange/ {
|
||||
grpc_pass grpc://netbird-signal:10000;
|
||||
grpc_read_timeout 1d;
|
||||
grpc_send_timeout 1d;
|
||||
grpc_socket_keepalive on;
|
||||
}
|
||||
|
||||
# gRPC for Management service
|
||||
location /management.ManagementService/ {
|
||||
grpc_pass grpc://netbird-management:80;
|
||||
grpc_read_timeout 1d;
|
||||
grpc_send_timeout 1d;
|
||||
grpc_socket_keepalive on;
|
||||
}
|
||||
```
|
||||
|
||||
#### NPM running on host (not in Docker)
|
||||
|
||||
If NPM is installed directly on the host, use localhost addresses:
|
||||
|
||||
**1. Create a Proxy Host in NPM:**
|
||||
- Domain: `netbird.example.com`
|
||||
- Forward Hostname/IP: `127.0.0.1`
|
||||
- Forward Port: `8080`
|
||||
- Block Common Exploits: enabled
|
||||
|
||||
**2. SSL tab:**
|
||||
- Request or select existing certificate
|
||||
- **Enable "HTTP/2 Support"** (required for gRPC)
|
||||
|
||||
**3. Advanced tab - paste this configuration:**
|
||||
|
||||
```nginx
|
||||
# Required for long-lived connections (gRPC and WebSocket)
|
||||
client_header_timeout 1d;
|
||||
client_body_timeout 1d;
|
||||
|
||||
# Relay WebSocket
|
||||
location /relay {
|
||||
proxy_pass http://127.0.0.1:8084;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_read_timeout 1d;
|
||||
}
|
||||
|
||||
# Signal WebSocket
|
||||
location /ws-proxy/signal {
|
||||
proxy_pass http://127.0.0.1:8083;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_read_timeout 1d;
|
||||
}
|
||||
|
||||
# Management WebSocket
|
||||
location /ws-proxy/management {
|
||||
proxy_pass http://127.0.0.1:8081;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_read_timeout 1d;
|
||||
}
|
||||
|
||||
# API routes
|
||||
location /api/ {
|
||||
proxy_pass http://127.0.0.1:8081;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
# OAuth2/IdP routes
|
||||
location /oauth2/ {
|
||||
proxy_pass http://127.0.0.1:8081;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
# gRPC for Signal service
|
||||
location /signalexchange.SignalExchange/ {
|
||||
grpc_pass grpc://127.0.0.1:10000;
|
||||
grpc_read_timeout 1d;
|
||||
grpc_send_timeout 1d;
|
||||
grpc_socket_keepalive on;
|
||||
}
|
||||
|
||||
# gRPC for Management service
|
||||
location /management.ManagementService/ {
|
||||
grpc_pass grpc://127.0.0.1:8081;
|
||||
grpc_read_timeout 1d;
|
||||
grpc_send_timeout 1d;
|
||||
grpc_socket_keepalive on;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### gRPC connections failing
|
||||
|
||||
- Ensure your reverse proxy supports HTTP/2 and gRPC
|
||||
- **Nginx Proxy Manager**: Enable "HTTP/2 Support" in the SSL tab
|
||||
- Check that `h2c` (plaintext HTTP/2) is correctly configured for gRPC upstreams
|
||||
- Verify timeout settings are long enough (gRPC connections can be long-lived)
|
||||
|
||||
### WebSocket connections failing
|
||||
|
||||
- Ensure WebSocket upgrade headers are passed through
|
||||
- Check that `Connection: Upgrade` and `Upgrade: websocket` headers are preserved
|
||||
|
||||
### SSL/TLS certificate issues
|
||||
|
||||
- Verify your certificates are valid and not expired
|
||||
- Check certificate paths in your configuration
|
||||
- For Let's Encrypt, ensure ports 80 and 443 are accessible for validation
|
||||
|
||||
### Dashboard loads but API calls fail
|
||||
|
||||
- Check that `/api/*` routes are correctly configured
|
||||
- Verify the management container is running: `docker compose ps management`
|
||||
- Check management logs: `docker compose logs management`
|
||||
|
||||
### Signal or Relay connections failing
|
||||
|
||||
- Verify gRPC routes are using `h2c://` (plaintext HTTP/2)
|
||||
- Check that WebSocket routes have proper upgrade handling
|
||||
- Ensure coturn (STUN/TURN) is accessible on UDP port 3478
|
||||
|
||||
For more help, see the [Troubleshooting guide](/selfhosted/troubleshooting) or reach out on [Slack](/slack-url).
|
||||
@@ -197,56 +197,21 @@ docker compose logs dashboard
|
||||
|
||||
## Advanced: Running NetBird behind an existing reverse-proxy
|
||||
|
||||
If you want to run NetBird behind your own reverse-proxy, some additional configuration-steps have to be taken to [Step 2](#step-2--prepare-configuration-files).
|
||||
If you already have a reverse proxy (Traefik, Nginx, Caddy, etc.), you can configure NetBird to work with it instead of using the built-in Caddy.
|
||||
|
||||
<Note>
|
||||
Not all reverse-proxies are supported as NetBird uses *gRPC* for various components.
|
||||
Not all reverse proxies are supported as NetBird uses *gRPC* for various components. Your reverse proxy must support HTTP/2 and gRPC proxying.
|
||||
</Note>
|
||||
|
||||
### Configuration for NetBird
|
||||
**New deployments:** The `getting-started.sh` script can simplify the integration of NetBird into your existing reverse proxy setup by generating a drop-in config or bespoke instructions.
|
||||
|
||||
In `setup.env`:
|
||||
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
|
||||
- Set ```NETBIRD_DISABLE_LETSENCRYPT=true```
|
||||
- Add ```NETBIRD_MGMT_API_PORT``` to your reverse-proxy TLS-port (default: 443)
|
||||
- Add ```NETBIRD_SIGNAL_PORT``` to your reverse-proxy TLS-port
|
||||
**Existing deployments:** Use the configuration templates on the dedicated reverse proxy page.
|
||||
|
||||
Optional:
|
||||
- Add ```TURN_MIN_PORT``` and ```TURN_MAX_PORT``` to configure the port-range used by the Turn-server
|
||||
|
||||
<Note>
|
||||
The `coturn`-service still needs to be directly accessible under your set-domain as it uses UDP for communication.
|
||||
</Note>
|
||||
|
||||
Now you can continue with [Step 3](#step-3-configure-identity-provider-idp).
|
||||
|
||||
### Configuration for your reverse-proxy
|
||||
|
||||
Depending on your port-mappings and choice of reverse-proxy, how you configure the forwards differs greatly.
|
||||
|
||||
The following endpoints have to be setup:
|
||||
|
||||
Endpoint | Protocol | Target service and internal-port
|
||||
------------------------------- | --------- | --------------------------------
|
||||
/ | HTTP | dashboard:80
|
||||
/signalexchange.SignalExchange/ | gRPC | signal:80
|
||||
/ws-proxy/signal | WebSocket | signal:80
|
||||
/api | HTTP | management:443
|
||||
/management.ManagementService/ | gRPC | management:443
|
||||
/ws-proxy/management | WebSocket | management:443
|
||||
/relay | WebSocket | relay:33080
|
||||
:33080 (UDP) | QUIC | relay:33080 (direct or L4 proxy)
|
||||
|
||||
Make sure your reverse-Proxy is setup to use the HTTP2-Protocol when forwarding.
|
||||
|
||||
<Note>
|
||||
The relay service supports two transport options: WebSocket (via `/relay`) or QUIC over UDP on port 33080 (not HTTP/3). You only need to configure one - either the WebSocket endpoint through your reverse proxy, or direct UDP access for QUIC. QUIC cannot be proxied through typical HTTP reverse proxies and must either be exposed directly or proxied using an L4 (transport layer) proxy that supports UDP. Some reverse proxies may support QUIC proxying, but this typically requires specific configuration for the custom application protocol.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
You can find helpful templates with the reverse-proxy-name as suffix (e.g. `docker-compose.yml.tmpl.traefik`)
|
||||
Simply replace the file `docker-compose.yml.tmpl` with the chosen version.
|
||||
</Note>
|
||||
See the [Reverse Proxy Configuration](/selfhosted/reverse-proxy) page for:
|
||||
- Complete configuration templates for [Traefik](/selfhosted/reverse-proxy#traefik), [Nginx](/selfhosted/reverse-proxy#nginx), [Caddy](/selfhosted/reverse-proxy#caddy-external), and [Nginx Proxy Manager](/selfhosted/reverse-proxy#nginx-proxy-manager)
|
||||
- Required routing endpoints and port mappings
|
||||
- Docker Compose examples for external proxies
|
||||
- Troubleshooting tips
|
||||
|
||||
## Advanced: Additional configurations for cloud providers
|
||||
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
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).
|
||||
@@ -30,25 +32,54 @@ curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting
|
||||
|
||||
Once finished, you can manage the resources via `docker compose`.
|
||||
|
||||
An example output of the script:
|
||||
### 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.
|
||||
|
||||
<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>
|
||||
|
||||
### 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)
|
||||
[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
|
||||
|
||||
WARN[0000] No services to build
|
||||
[+] up 9/9
|
||||
✔ Network netbird-selfhosted-3_netbird Created 0.1s
|
||||
✔ Volume netbird-selfhosted-3_netbird_caddy_data Created 0.0s
|
||||
✔ Volume netbird-selfhosted-3_netbird_management Created 0.0s
|
||||
✔ Container netbird-caddy Created 0.2s
|
||||
✔ Container netbird-dashboard Created 0.2s
|
||||
✔ Container netbird-management Created 0.2s
|
||||
✔ Container netbird-relay Created 0.2s
|
||||
✔ Container netbird-coturn Created 0.2s
|
||||
✔ Container netbird-signal Created 0.2s
|
||||
[+] Running 6/6
|
||||
✔ Network netbird Created
|
||||
✔ Container netbird-dashboard Started
|
||||
✔ Container netbird-management Started
|
||||
✔ Container netbird-relay Started
|
||||
✔ Container netbird-coturn Started
|
||||
✔ Container netbird-signal Started
|
||||
✔ Container netbird-caddy Started
|
||||
Waiting for Management server to become ready . . done
|
||||
|
||||
Done!
|
||||
|
||||
Reference in New Issue
Block a user