Skip to main content
Clustering is only available in Enterprise Edition.
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.

​
Hosts

You need a minimum of three hosts:
  • 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.)
The database host doesn’t need to be a dedicated instance. You can run PostgreSQL and Redis however you like - a managed cloud database, an existing cluster, etc. - as long as both nodes can reach them. The only hard requirement is that the Redis-compatible server supports pub/sub.
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 - 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 terminate HTTPS for the Pangolin UI and accept UDP port 53 for DNS and route to both nodes

​
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.

​
Required Ports

Configure the following firewall rules on each Pangolin node. Inbound Outbound

​
DNS Delegation

Pangolin’s built-in DNS server needs to be delegated authority for a nameserver subdomain. Point an NS record at your load balancer, then optionally delegate additional subdomains through it.
1

Create the nameserver record

Create an A record pointing your chosen nameserver hostname at your load balancer’s IP. The examples in this guide use ns.example.com - substitute your own domain or subdomain.
2

Delegate CNAME-based domains (optional)

If you want to support CNAME delegation for resource domains, delegate a subdomain to your nameserver.
3

Delegate site-to-cloud resolution (optional)

If you want to support site-to-cloud networking - resolving a site’s tunnel address by DNS from within a cloud environment - delegate another subdomain the same way.
These three hostnames map directly to the dns section of privateConfig.yml, covered in Deploy a Cluster:

​
Other Requirements

  • Contact email for Let’s Encrypt ACME registration
  • 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 and Enable ASN Lookup
  • Site type support - in clustered deployments, only Newt sites are supported. Local sites and basic WireGuard sites are not supported

Deploy a Cluster

Once these requirements are met, follow the full deployment walkthrough.