mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-09-17 03:19:08 +02:00
Clean up and fix links to clustering
This commit is contained in:
Owen
@@ -38,7 +38,7 @@ Public TCP/UDP listeners that bind a port on the Pangolin host are a self-hosted
|
||||
| **Traffic path** | Cloud nodes, or your [remote nodes](/manage/remote-node/understanding-nodes) | Your server |
|
||||
| **DNS and certificates** | Managed | You configure DNS and Let's Encrypt |
|
||||
| **Updates and backups** | Included | You operate them |
|
||||
| **High availability** | Included | You design it ([clustering](/self-host/advanced/clustering/understanding-clustering) on Enterprise) |
|
||||
| **High availability** | Included | You design it ([clustering](/self-host/clustering/understanding-clustering) on Enterprise) |
|
||||
| **Identity and logs** | Cloud plans | Community core; extra IdPs, streaming, and AI session logs on [Enterprise Edition](/self-host/enterprise-edition) |
|
||||
| **Data residency** | Cloud regions, or traffic on your remote nodes | Entirely on your infrastructure |
|
||||
| **Best for** | Fast start and less ops | Air-gapped networks, full control, compliance that requires self-hosting |
|
||||
|
||||
@@ -34,7 +34,7 @@ You can run the control plane yourself ([self-hosted](/self-host/quick-install))
|
||||
|
||||
A **node** is the networking edge of your Pangolin deployment. It terminates inbound traffic from the public internet, manages WireGuard tunnels, and relays client traffic when a direct peer path is unavailable.
|
||||
|
||||
On a self-hosted deployment, your Pangolin server runs as a single node by default. [Enterprise clustering](/self-host/advanced/clustering/understanding-clustering) spreads multiple nodes behind a load balancer with shared database state. On [Pangolin Cloud](/manage/remote-node/understanding-nodes), you can add **remote nodes**: infrastructure you operate that still receives configuration from the cloud control plane.
|
||||
On a self-hosted deployment, your Pangolin server runs as a single node by default. [Enterprise clustering](/self-host/clustering/understanding-clustering) spreads multiple nodes behind a load balancer with shared database state. On [Pangolin Cloud](/manage/remote-node/understanding-nodes), you can add **remote nodes**: infrastructure you operate that still receives configuration from the cloud control plane.
|
||||
|
||||
Each node runs several cooperating processes:
|
||||
|
||||
@@ -51,7 +51,7 @@ The control plane writes certificates, Traefik router definitions, and WireGuard
|
||||
Required listener ports, firewall rules, and DNS records for a node.
|
||||
</Card>
|
||||
|
||||
<Card title="Clustering for high availability" icon="server" href="/self-host/advanced/clustering/understanding-clustering">
|
||||
<Card title="Clustering for high availability" icon="server" href="/self-host/clustering/understanding-clustering">
|
||||
Multi-node Enterprise deployments with shared state and failover.
|
||||
</Card>
|
||||
|
||||
|
||||
@@ -512,8 +512,8 @@
|
||||
},
|
||||
"redirects": [
|
||||
{
|
||||
"source": "/self-host/advanced/clustering",
|
||||
"destination": "/self-host/advanced/clustering/understanding-clustering"
|
||||
"source": "/self-host/clustering",
|
||||
"destination": "/self-host/clustering/understanding-clustering"
|
||||
},
|
||||
{
|
||||
"source": "/self-host/advanced/enable-geoblocking",
|
||||
|
||||
@@ -11,9 +11,6 @@ To get started, create a basic configuration file with the essential settings:
|
||||
Minimal Pangolin configuration:
|
||||
|
||||
```yaml title="config.yml"
|
||||
# To see all available options, please visit the docs:
|
||||
# https://docs.pangolin.net/
|
||||
|
||||
gerbil:
|
||||
start_port: 51820
|
||||
base_endpoint: "pangolin.example.com" # REPLACE WITH YOUR DOMAIN
|
||||
@@ -1190,5 +1187,6 @@ Some configuration values can be set using environment variables for enhanced se
|
||||
| PostgreSQL Connection String | `POSTGRES_CONNECTION_STRING` | `postgres.connection_string` |
|
||||
| PostgreSQL Replica Connection Strings | `POSTGRES_REPLICA_CONNECTION_STRINGS` | `postgres.replicas` (comma-separated list of connection strings) |
|
||||
| PostgreSQL Logs Connection String | `POSTGRES_LOGS_CONNECTION_STRING` | `postgres_logs.connection_string` |
|
||||
| PostgreSQL Logs Replica Connection Strings | `POSTGRES_LOGS_REPLICA_CONNECTION_STRINGS` | `postgres_logs.replicas` (comma-separated list of connection strings) |
|
||||
| Enable SQLite WAL Mode | `ENABLE_SQLITE_WAL_MODE` | *(SQLite only)* Set to `true` to enable [WAL mode](https://www.sqlite.org/wal.html) for improved SQLite concurrency |
|
||||
| Enable AI Gateway Client IP Header | `ENABLE_AI_GATEWAY_CLIENT_IP_HEADER` | `server.enable_ai_gateway_client_ip_header` |
|
||||
@@ -7,7 +7,7 @@ description: "Step-by-step walkthrough for deploying a two-node highly available
|
||||
Clustering is only available in [Enterprise Edition](/self-host/enterprise-edition).
|
||||
</Note>
|
||||
|
||||
This guide walks through deploying a minimal two-node Pangolin cluster: two Pangolin nodes behind a load balancer, sharing a PostgreSQL database and a Valkey (Redis) server. Read [Understanding Clustering](/self-host/advanced/clustering/understanding-clustering) for the architecture and [Requirements](/self-host/advanced/clustering/requirements) for the hosts, ports, and DNS records you need before starting.
|
||||
This guide walks through deploying a minimal two-node Pangolin cluster: two Pangolin nodes behind a load balancer, sharing a PostgreSQL database and a Valkey (Redis) server. Read [Understanding Clustering](/self-host/clustering/understanding-clustering) for the architecture and [Requirements](/self-host/clustering/requirements) for the hosts, ports, and DNS records you need before starting.
|
||||
|
||||
<Card icon="github" arrow="true" cta="View reference configuration" href="https://github.com/fosrl/pangolin/tree/main/config/ha-reference">
|
||||
The complete, working set of files used in this guide lives in the Pangolin repository at [`config/ha-reference`](https://github.com/fosrl/pangolin/tree/main/config/ha-reference). Clone it as a starting point instead of assembling files by hand.
|
||||
@@ -31,7 +31,7 @@ Throughout this guide, replace the following placeholders with your own values:
|
||||
| `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).
|
||||
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/clustering/requirements#dashboard-domain).
|
||||
|
||||
<Steps>
|
||||
|
||||
@@ -239,9 +239,6 @@ Set `app.dashboard_url` and `server.cors.origins` to your dashboard domain (the
|
||||
|
||||
<CodeGroup>
|
||||
```yaml Node 1
|
||||
# To see all available options, please visit the docs:
|
||||
# https://docs.pangolin.net/
|
||||
|
||||
gerbil:
|
||||
start_port: 51820
|
||||
base_endpoint: "<NODE1_EXTERNAL_IP>"
|
||||
@@ -280,9 +277,6 @@ flags:
|
||||
```
|
||||
|
||||
```yaml Node 2
|
||||
# To see all available options, please visit the docs:
|
||||
# https://docs.pangolin.net/
|
||||
|
||||
gerbil:
|
||||
start_port: 51820
|
||||
base_endpoint: "<NODE2_EXTERNAL_IP>"
|
||||
|
||||
@@ -7,13 +7,13 @@ description: "Hosts, networking, and DNS delegation needed before deploying a Pa
|
||||
Clustering is only available in [Enterprise Edition](/self-host/enterprise-edition).
|
||||
</Note>
|
||||
|
||||
Review these requirements before you start deploying. They cover the hosts you need, the ports that must be open, and the DNS records you need to delegate ahead of time. For background on why each piece exists, see [Understanding Clustering](/self-host/advanced/clustering/understanding-clustering).
|
||||
Review these requirements before you start deploying. They cover the hosts you need, the ports that must be open, and the DNS records you need to delegate ahead of time. For background on why each piece exists, see [Understanding Clustering](/self-host/clustering/understanding-clustering).
|
||||
|
||||
## Hosts
|
||||
|
||||
You need a minimum of **three hosts**:
|
||||
|
||||
- **Node 1** -- runs Pangolin, Gerbil, and Traefik
|
||||
- **Node 1** - runs Pangolin, Gerbil, and Traefik
|
||||
- **Node 2** - runs Pangolin, Gerbil, and Traefik
|
||||
- **A database host** - runs PostgreSQL and a Redis-compatible server (Valkey, Redis, etc.)
|
||||
|
||||
@@ -23,13 +23,13 @@ The database host doesn't need to be a dedicated instance. You can run PostgreSQ
|
||||
|
||||
You can add more Pangolin nodes beyond two for additional capacity or regional distribution. The two-node topology in this guide is the minimum for high availability.
|
||||
|
||||
For sizing information, see [Choosing a VPS](/self-host/choosing-a-vps) - the same sizing from single pangolin node deployments applies to each node in a cluster.
|
||||
For sizing information, see [Choosing a VPS](/self-host/choosing-a-vps) - the same sizing from single Pangolin node deployments applies to each node in a cluster.
|
||||
|
||||
## Networking
|
||||
|
||||
- **Node 1 and Node 2 each need a public, static IP address**, reachable from the internet
|
||||
- **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
|
||||
- **You must provide your own HA load balancer** in front of both nodes. It needs to terminate HTTPS for the Pangolin UI and accept UDP port 53 for DNS and route to both nodes
|
||||
|
||||
### Dashboard Domain
|
||||
|
||||
@@ -37,7 +37,7 @@ You also need a domain for the Pangolin UI and API itself (e.g. `pangolin.exampl
|
||||
|
||||
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).
|
||||
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/clustering/deploy-a-cluster).
|
||||
|
||||
### Required Ports
|
||||
|
||||
@@ -89,7 +89,7 @@ Pangolin's built-in DNS server needs to be delegated authority for a nameserver
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
These three hostnames map directly to the `dns` section of `privateConfig.yml`, covered in [Deploy a Cluster](/self-host/advanced/clustering/deploy-a-cluster):
|
||||
These three hostnames map directly to the `dns` section of `privateConfig.yml`, covered in [Deploy a Cluster](/self-host/clustering/deploy-a-cluster):
|
||||
|
||||
```yaml
|
||||
dns:
|
||||
@@ -105,6 +105,6 @@ dns:
|
||||
- **GeoIP databases** - download and keep up to date the MaxMind `GeoLite2-Country.mmdb` and `GeoLite2-ASN.mmdb` databases, placed in each node's `config/` directory. See [Enable Geo-location](/self-host/advanced/enable-geolocation) and [Enable ASN Lookup](/self-host/advanced/enable-asn-lookup)
|
||||
- **Site type support** - in clustered deployments, only Newt sites are supported. Local sites and basic WireGuard sites are not supported
|
||||
|
||||
<Card title="Deploy a Cluster" href="/self-host/advanced/clustering/deploy-a-cluster" icon="server">
|
||||
<Card title="Deploy a Cluster" href="/self-host/clustering/deploy-a-cluster" icon="server">
|
||||
Once these requirements are met, follow the full deployment walkthrough.
|
||||
</Card>
|
||||
|
||||
@@ -130,10 +130,10 @@ The sites connected to the failed node will being detecting ping failures and wi
|
||||
Clustered deployments require careful planning around database replication, Valkey configuration, network topology, DNS delegation, and monitoring. For organizations interested in clustering for high availability or regional distribution, please [contact our enterprise team](https://pangolin.net/contact) to discuss your requirements and receive implementation guidance support. A support contract is not required for deployment.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Requirements" href="/self-host/advanced/clustering/requirements" icon="list-check">
|
||||
<Card title="Requirements" href="/self-host/clustering/requirements" icon="list-check">
|
||||
Review the hosts, network, and DNS delegation a cluster needs before you deploy.
|
||||
</Card>
|
||||
<Card title="Deploy a Cluster" href="/self-host/advanced/clustering/deploy-a-cluster" icon="server">
|
||||
<Card title="Deploy a Cluster" href="/self-host/clustering/deploy-a-cluster" icon="server">
|
||||
Follow a complete walkthrough for standing up a two-node cluster.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -276,9 +276,6 @@ tcp:
|
||||
This file contains Pangolin's application settings, dashboard domain, base domain, CORS origin, and server secret.
|
||||
|
||||
```yaml title="config/config.yml"
|
||||
# To see all available options, please visit the docs:
|
||||
# https://docs.pangolin.net/
|
||||
|
||||
gerbil:
|
||||
start_port: 51820
|
||||
base_endpoint: "pangolin.example.com" # REPLACE WITH YOUR DASHBOARD DOMAIN
|
||||
|
||||
@@ -329,9 +329,6 @@ tcp:
|
||||
This file contains Pangolin's application settings, dashboard domain, base domain, CORS origin, and server secret.
|
||||
|
||||
```yaml title="config/config.yml"
|
||||
# To see all available options, please visit the docs:
|
||||
# https://docs.pangolin.net/
|
||||
|
||||
gerbil:
|
||||
start_port: 51820
|
||||
base_endpoint: "pangolin.example.com" # REPLACE WITH YOUR DASHBOARD DOMAIN
|
||||
|
||||
Reference in New Issue
Block a user