sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-16 07:26:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

NetBird Proxy Service Edits (#603)

Browse Source 
* NetBird Proxy Service Edits

* Self-hosted setup clarification
This commit is contained in:
Brandon Hopkins
2026-02-15 03:26:55 -08:00
committed by GitHub
parent 024ce42bfa
commit 62b39cf8a1
2 changed files with 46 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
src/pages/selfhosted/reverse-proxy.mdx
View File

@@ -1,11 +1,13 @@
# Reverse Proxy Configuration
# Reverse Proxy Setup for Self-Hosted NetBird
NetBird includes a built-in Traefik reverse proxy that handles TLS certificates automatically via Let's Encrypt. However, if you already have an existing reverse proxy (Nginx, Caddy, 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.
This is not to be confused with our new NetBird reverse proxy service that launched with v0.65.0. To learn more about using NetBird as a reverse proxy, see the [NetBird Proxy documentation](/manage/reverse-proxy).
</Note>
Not all reverse proxies are supported as NetBird uses *gRPC* for various components. Your reverse proxy must support HTTP/2 and gRPC proxying.
## Quick Setup
### New Deployments

107
src/pages/selfhosted/selfhosted-quickstart.mdx
View File

@@ -49,12 +49,53 @@ Which reverse proxy will you use?
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.
**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, requires no additional configuration, and makes it easy to enable the NetBird Proxy in the next step.
<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>
## Enable the NetBird Proxy Service
When you select the built-in Traefik option (`[0]`), the script asks whether you want to enable the NetBird Proxy service:
```
Do you want to enable the NetBird Proxy service?
The proxy allows you to selectively expose internal NetBird network resources
to the internet. You control which resources are exposed through the dashboard.
Enable proxy? [y/N]:
```
If you answer `y`, the script prompts for a **proxy domain**:
```
NOTE: The proxy domain must be different from the management domain (netbird.example.com)
to avoid TLS certificate conflicts.
You also need to add a wildcard DNS record for the proxy domain,
e.g. *.proxy.netbird.example.com pointing to the same server IP as netbird.example.com.
Enter the domain for the NetBird Proxy (e.g. proxy.netbird.example.com):
```
<Warning>
The proxy domain **must be different** from your NetBird management domain to avoid TLS certificate conflicts.
</Warning>
The script then automatically generates a proxy access token, creates a `proxy.env` configuration file, and starts the proxy container alongside the other services. Point a wildcard DNS record (e.g. `*.proxy.netbird.example.com`) to your server's IP address so that service subdomains resolve correctly.
### CNAME Record for Proxy Domain
For certificates to work properly, ensure you have the proper records set with your domain name registrar. The first A record below should already be setup prior to starting the quick start script.
| Type | Name | Content | Proxy status (Cloudflare) |
|------|------|---------|--------------|
| A | `netbird` | `YOUR.SERVER.IP.ADDRESS` | DNS only |
| CNAME | `*.proxy.netbird` | `netbird.example.com` | DNS only |
If you skipped the proxy during initial setup, you can add it later by following the [Enable Reverse Proxy migration guide](/selfhosted/migration/enable-reverse-proxy).
### Generated Files
The script generates the following files:
@@ -68,39 +109,6 @@ The script generates the following files:
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:
@@ -141,37 +149,6 @@ NetBird includes built-in local user management powered by an embedded <a href="
]}
/>
## Enable the Reverse Proxy Feature
When you select the built-in Traefik option (`[0]`), the script asks whether you want to enable the NetBird Proxy service:
```
Do you want to enable the NetBird Proxy service?
The proxy allows you to selectively expose internal NetBird network resources
to the internet. You control which resources are exposed through the dashboard.
Enable proxy? [y/N]:
```
If you answer `y`, the script prompts for a **proxy domain**:
```
NOTE: The proxy domain must be different from the management domain (netbird.example.com)
to avoid TLS certificate conflicts.
You also need to add a wildcard DNS record for the proxy domain,
e.g. *.proxy.netbird.example.com pointing to the same server IP as netbird.example.com.
Enter the domain for the NetBird Proxy (e.g. proxy.netbird.example.com):
```
<Warning>
The proxy domain **must be different** from your NetBird management domain to avoid TLS certificate conflicts.
</Warning>
The script then automatically generates a proxy access token, creates a `proxy.env` configuration file, and starts the proxy container alongside the other services. Point a wildcard DNS record (e.g. `*.proxy.netbird.example.com`) to your server's IP address so that service subdomains resolve correctly.
If you skipped the proxy during initial setup, you can add it later by following the [Enable Reverse Proxy migration guide](/selfhosted/migration/enable-reverse-proxy).
## Maintenance
Once your NetBird instance is running, refer to these guides for ongoing maintenance: