diff --git a/src/pages/selfhosted/migration/enable-reverse-proxy.mdx b/src/pages/selfhosted/migration/enable-reverse-proxy.mdx index 667258b5..265f4346 100644 --- a/src/pages/selfhosted/migration/enable-reverse-proxy.mdx +++ b/src/pages/selfhosted/migration/enable-reverse-proxy.mdx @@ -39,18 +39,14 @@ Before starting, ensure you have: - **Traefik** as your reverse proxy (see [Why Traefik is required](#why-traefik-is-required) above) - **Latest NetBird images** - pull the latest version to ensure the management server and CLI support the reverse proxy feature and token creation -- **A domain for the proxy** - e.g., `proxy.example.com`. Service subdomains will be created under this domain (e.g., `myapp.proxy.example.com`) -- **Wildcard DNS capability** - ability to create a `*.proxy.example.com` DNS record pointing to your server +- **A domain for the proxy** - e.g., `proxy.example.com` or `netbird.example.com` (it can be the same domain as the NetBird server itself). Service subdomains will be created under this domain (e.g., `myapp.netbird.example.com`) +- **Wildcard DNS capability** - ability to create a `*.netbird.example.com` DNS record pointing to your server - **Port 443 accessible** - the proxy needs this for ACME TLS-ALPN-01 challenges (certificate provisioning) This guide covers both the **combined container** setup (`netbirdio/netbird-server`, the default for new deployments) and the **multi-container** setup (separate `management`, `signal`, and `relay` images). Where commands or configuration differ between the two setups, both variants are shown. - -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. - - ## Migration steps ### Step 1: Backup current configuration @@ -190,14 +186,13 @@ The `HostSNI(*)` rule acts as a catch-all for any domain not matched by the exis ### Step 4: Set up DNS records -Create two DNS records pointing to the server running your NetBird stack - one for the base proxy domain and one wildcard for service subdomains: +Create one DNS record pointing to the server running your NetBird stack - one for the base proxy domain and one wildcard for service subdomains: | Type | Name | Content | |------|------|---------| -| `CNAME` | `proxy.example.com` | `netbird.example.com` | -| `CNAME` | `*.proxy.example.com` | `netbird.example.com` | +| `CNAME` | `*.netbird.example.com` | `netbird.example.com` | -The base domain record is required because a wildcard DNS record does not cover the bare domain itself. The wildcard record ensures that all service subdomains (e.g., `myapp.proxy.example.com`, `dashboard.proxy.example.com`) resolve to your server where Traefik forwards them to the proxy container. +The base domain record is required because a wildcard DNS record does not cover the bare domain itself. The wildcard record ensures that all service subdomains (e.g., `myapp.netbird.example.com`, `dashboard.netbird.example.com`) resolve to your server where Traefik forwards them to the proxy container. ### Step 5: Apply changes @@ -404,7 +399,7 @@ If your self-hosted deployment currently uses Nginx, Caddy, or another reverse p | Variable | Required | Description | Default | |----------|----------|-------------|---------| | `NB_PROXY_TOKEN` | Yes | Access token generated via `netbird-server token create` (combined) or `netbird-mgmt token create` (multi-container). The proxy refuses to start without it. | - | -| `NB_PROXY_DOMAIN` | Yes | Base domain for this proxy instance (e.g., `proxy.example.com`). Determines the domain available for services. | - | +| `NB_PROXY_DOMAIN` | Yes | Base domain for this proxy instance (e.g., `proxy.example.com`or `netbird.example.com`). Determines the domain available for services. | - | | `NB_PROXY_MANAGEMENT_ADDRESS` | No | URL of your NetBird management server. The proxy connects via gRPC to register itself. | `https://api.netbird.io:443` | | `NB_PROXY_ADDRESS` | No | Address the proxy listens on. | `:8443` (Docker), `:443` (binary) | | `NB_PROXY_ACME_CERTIFICATES` | No | Set to `true` to enable automatic TLS certificate provisioning via Let's Encrypt. | `false` | @@ -482,4 +477,4 @@ docker exec -it netbird-management /go/bin/netbird-mgmt token revoke - [Reverse Proxy feature documentation](/manage/reverse-proxy) - full overview of services, targets, domains, and authentication - [Custom Domains](/manage/reverse-proxy/custom-domains) - use your own domain names for reverse proxy services - [Reverse Proxy configuration reference](/selfhosted/configuration-files#reverse-proxy-configuration) - all proxy environment variables and options -- [Self-Hosting Quickstart](/selfhosted/selfhosted-quickstart) - getting started with self-hosted NetBird \ No newline at end of file +- [Self-Hosting Quickstart](/selfhosted/selfhosted-quickstart) - getting started with self-hosted NetBird diff --git a/src/pages/selfhosted/selfhosted-quickstart.mdx b/src/pages/selfhosted/selfhosted-quickstart.mdx index 5c7b4d0b..4e4333d5 100644 --- a/src/pages/selfhosted/selfhosted-quickstart.mdx +++ b/src/pages/selfhosted/selfhosted-quickstart.mdx @@ -14,7 +14,6 @@ This is the quickest way to try self-hosted NetBird. It should take around 5 min - 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 (e.g. `netbird.example.com`). -- *(Optional, for Proxy feature)* A **separate domain** for the proxy with a **wildcard DNS record** pointing to the same server IP. For example, if your management domain is `netbird.example.com`, add a CNAME wildcard record for `*.proxy.example.com` pointed to the same `netbird.example.com` you configured. ## Software requirements @@ -67,23 +66,7 @@ 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 two CNAME records with one wildcard for the proxy domain, -e.g. proxy.example.com and *.proxy.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): -``` - - -The proxy domain **must be different** from your NetBird management domain to avoid TLS certificate conflicts. - - -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. +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. `*.netbird.example.com`) to your server's IP address so that service subdomains resolve correctly. ### CNAME Record for Proxy Domain @@ -92,8 +75,7 @@ For certificates to work properly, ensure you have the proper records set with y | Type | Name | Content | Proxy status (Cloudflare) | |------|------|---------|--------------| | A | `netbird` | `YOUR.SERVER.IP.ADDRESS` | DNS only | -| CNAME | `proxy` | `netbird.example.com` | DNS only | -| CNAME | `*.proxy` | `netbird.example.com` | DNS only | +| CNAME | `*.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).