From 2904fa44f6b682642f84153981f18e9c84899dff Mon Sep 17 00:00:00 2001 From: Owen Date: Fri, 11 Sep 2026 12:14:53 -0400 Subject: [PATCH] Include the dashboard domain pointing to the lb --- self-host/advanced/clustering/deploy-a-cluster.mdx | 8 ++++++++ self-host/advanced/clustering/requirements.mdx | 10 ++++++++++ 2 files changed, 18 insertions(+) diff --git a/self-host/advanced/clustering/deploy-a-cluster.mdx b/self-host/advanced/clustering/deploy-a-cluster.mdx index 34facbd..52f39f8 100644 --- a/self-host/advanced/clustering/deploy-a-cluster.mdx +++ b/self-host/advanced/clustering/deploy-a-cluster.mdx @@ -29,6 +29,11 @@ Throughout this guide, replace the following placeholders with your own values: | `CONTACT_EMAIL` | Email address used for Let's Encrypt ACME registration | | `SECRET` | Shared server secret - identical on every node | | `LOAD_BALANCER_IP` | IP address of the load balancer in front of the cluster | +| `pangolin.example.com` | Your dashboard domain - DNS points at the load balancer, not at either node | + + +You need a domain for the Pangolin UI and API (`pangolin.example.com` in this guide), pointed at your load balancer. **The load balancer is responsible for TLS on this domain** - terminate HTTPS there and forward plain HTTP to the nodes' dashboard port. The nodes' built-in ACME client only issues certificates for resource domains under the delegated nameserver zone, not for the dashboard domain itself. See [Requirements](/self-host/advanced/clustering/requirements#dashboard-domain). + @@ -232,6 +237,8 @@ If Pangolin can't reach the local Gerbil at the address in `--reachableAt` (a lo `config.yml` holds the settings that legitimately differ per node - `gerbil.base_endpoint` and `gerbil.exit_node_name` - alongside the shared PostgreSQL connection and site-type restrictions. In clustered deployments, only Newt sites are supported, so local and basic WireGuard sites are disabled. +Set `app.dashboard_url` and `server.cors.origins` to your dashboard domain (the one pointed at your load balancer, not at either node) - both must match on every node. + ```yaml Node 1 # To see all available options, please visit the docs: @@ -501,6 +508,7 @@ Configure your load balancer - a cloud load balancer or a self-hosted one such a - Route TCP `3000` to both nodes for your Pangolin domain. For example `pangolin.example.com` should resolve to the load balancer, which routes to either node's `:3000` port. - Route UDP `53` to both nodes for DNS. For example `ns.example.com` should resolve to the load balancer, which routes to either node's `:53/udp` port. - Health-check the `:80/ping` endpoint on each node, and stop routing to a node that fails it. `:3000/api/v1/` can also be monitored for the Pangolin UI and API +- **Terminate TLS for the dashboard domain** (`pangolin.example.com`) at the load balancer, then forward plain HTTP to `:3000` on the nodes. Obtain and renew that certificate through the load balancer itself (a cloud provider's managed certificate, its own ACME client, etc.) - the nodes' built-in ACME client only covers resource domains, not the dashboard domain This is what makes the cluster appear as a single, consistent domain to users, and what drives failover when a node goes down. diff --git a/self-host/advanced/clustering/requirements.mdx b/self-host/advanced/clustering/requirements.mdx index a4a1fc2..a27f8e7 100644 --- a/self-host/advanced/clustering/requirements.mdx +++ b/self-host/advanced/clustering/requirements.mdx @@ -31,6 +31,16 @@ For sizing information, see [Choosing a VPS](/self-host/choosing-a-vps) - the sa - **Node 1 and Node 2 need to be able to address each other** over an internal network - **You must provide your own HA load balancer** in front of both nodes. It needs to route to both nodes and health-check the `/ping` endpoint on each, removing any node that fails the check +### Dashboard Domain + +You also need a domain for the Pangolin UI and API itself (e.g. `pangolin.example.com`) - this is separate from the nameserver domain above, which is the nameserver to resolve resource DNS. + + +Point this domain's DNS record at your **load balancer**, not at either node directly. The load balancer is also responsible for obtaining and serving the TLS certificate for this domain - the nodes' built-in ACME client only issues certificates for resource domains under the delegated nameserver zone, not for the dashboard domain. Terminate TLS at the load balancer and forward plain HTTP to the nodes. + +You must also set this domain as `app.dashboard_url` and add it to `server.cors.origins` in every node's `config.yml`. See [Deploy a Cluster](/self-host/advanced/clustering/deploy-a-cluster). + + ### Required Ports Configure the following firewall rules on each Pangolin node.