Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt

Use this file to discover all available pages before exploring further.

Try free on Pangolin Cloud

Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
The Pangolin Helm chart is currently alpha (0.1.0-alpha.0). Test installs and upgrades in a non-production environment before using the chart for production traffic.

​
What Pangolin deploys

The Pangolin Helm chart deploys the Pangolin control plane and related Kubernetes components. Depending on the selected values, the chart can deploy:
  • Pangolin application: dashboard, API, authentication, configuration, and application state.
  • pangolin-kube-controller: Kubernetes controller used in controller mode.
  • Gerbil: WireGuard tunnel manager used by the Pangolin tunnel stack.
  • Traefik integration: Traefik CRD-based routing in controller mode, bundled Traefik controller when enabled, or standalone Traefik mode.
  • Database backend: CloudNativePG, external PostgreSQL, embedded PostgreSQL, or SQLite.
See Version Matrix for chart and default app version references.

​
Gerbil setup in the Pangolin chart

This chart deploys Gerbil when gerbil.enabled=true. This is the default when using deployment.type=controller and recommended.
If Gerbil is exposed through a reverse proxy or UDP gateway, keep proxy protocol settings aligned end-to-end. Do not enable proxy protocol on the upstream hop unless Gerbil is configured to accept it.

​
Prerequisites

Before installing Pangolin, you need:
  • Kubernetes 1.30.14 or newer.
  • Helm 3.x.
  • kubectl access to the target cluster.
  • A namespace prepared for the install.
  • A StorageClass if you use chart-managed persistent storage.
  • DNS records for the Pangolin dashboard and tunnel endpoint.
  • Traefik CRDs and a Traefik controller when using deployment.type=controller.
  • A database plan: CloudNativePG, external PostgreSQL, embedded PostgreSQL, or SQLite.
See Prerequisites for detailed cluster, namespace, storage, networking, and security requirements. This quick install uses:
  • deployment.type=controller
  • deployment.mode=multi
  • database.mode=cloudnativepg
  • chart-managed CloudNativePG operator and cluster
  • chart-managed dashboard IngressRoute
  • Traefik cert resolver for TLS
This example assumes a Traefik controller is available and can process the chart-managed IngressRoute. If you want the chart to install the bundled Traefik controller, set deployment.installTraefikController=true.

​
Step 1: Create the namespace

Create the namespace before installing the chart: 
kubectl create namespace pangolin
Gerbil requires NET_ADMIN for WireGuard interface management. If your cluster enforces Pod Security Admission, label the namespace accordingly: 
kubectl label namespace pangolin \
  pod-security.kubernetes.io/enforce=privileged \
  pod-security.kubernetes.io/warn=baseline \
  pod-security.kubernetes.io/audit=restricted \
  --overwrite
Do not use a restricted Pod Security profile for a namespace running Gerbil unless you have validated the selected chart mode. Gerbil requires NET_ADMIN for WireGuard.

​
Step 2: Create a Pangolin app secret

Create a Secret for SERVER_SECRET: 
kubectl create secret generic pangolin-app-secret \
  --namespace pangolin \
  --from-literal=SERVER_SECRET='<strong-random-secret>'
Use a long random value. Do not commit this secret to Git.

​
Step 3: Create a values file

Create values-pangolin.yaml: 
deployment:
  type: controller
  mode: multi
  installTraefikController: false

database:
  mode: cloudnativepg
  cloudnativepg:
    cluster:
      name: pangolin-db

cnpg-operator:
  enabled: true

cnpg-cluster:
  enabled: true
  fullnameOverride: pangolin-db
  cluster:
    instances: 1
    storage:
      size: 8Gi

pangolin:
  secret:
    existingSecretName: pangolin-app-secret
    existingSecretKey: SERVER_SECRET

  config:
    app:
      dashboard_url: https://pangolin.example.com
    domains:
      domain1:
        base_domain: example.com
        cert_resolver: letsencrypt
    gerbil:
      base_endpoint: vpn.example.com
      start_port: 51820
      clients_start_port: 21820
    traefik:
      enabled: true
      http_entrypoint: web
      https_entrypoint: websecure
      cert_resolver: letsencrypt

  ingressRoute:
    dashboard:
      enabled: true
      host: pangolin.example.com
      entryPoints:
        - websecure
      tls:
        enabled: true
        certResolver: letsencrypt
        secretName: ""

gerbil:
  enabled: true
  startupMode: delayed
  persistence:
    enabled: true
    size: 1Gi
Important points:
  • Replace pangolin.example.com, example.com, and vpn.example.com.
  • Keep pangolin.config.gerbil.start_port aligned with gerbil.ports.wg1.
  • Keep pangolin.config.gerbil.clients_start_port aligned with gerbil.ports.wg2.
  • Use gerbil.startupMode=delayed for the first install if Gerbil should not start before the initial Pangolin setup is complete.
The chart defaults to deployment.type=controller, deployment.mode=multi, database.mode=cloudnativepg, and NetworkPolicy rendering enabled. Gerbil startupMode supports normal, delayed, and disabledUntilSetup. ([GitHub][1])

​
Step 4: Install Pangolin

Add the Helm repository: 
helm repo add fossorial https://charts.fossorial.io
helm repo update fossorial
Install Pangolin: 
helm upgrade --install pangolin fossorial/pangolin \
  --namespace pangolin \
  --values values-pangolin.yaml
Do not use --create-namespace here. The namespace was created and labeled before installation.

​
Step 5: Verify the deployment

Check Helm release status: 
helm status pangolin --namespace pangolin
helm history pangolin --namespace pangolin
Check workloads: 
kubectl get pods --namespace pangolin
kubectl get deploy,statefulset --namespace pangolin
Check Services: 
kubectl get svc --namespace pangolin
Check Traefik IngressRoute resources: 
kubectl get ingressroute --namespace pangolin
If Traefik CRDs are not installed, this command will fail. In that case, install Traefik CRDs or enable/install the Traefik controller path required by your selected deployment mode. Wait for the Pangolin pod to become ready: 
kubectl wait --for=condition=ready pod \
  -l app.kubernetes.io/name=pangolin \
  --namespace pangolin \
  --timeout=300s

​
Accessing the dashboard

After DNS and Traefik routing are configured, access Pangolin through the dashboard URL: 
https://pangolin.example.com
The API route is exposed under: 
https://pangolin.example.com/api/v1
For a temporary local check, port-forward the dashboard/UI port:
kubectl port-forward --namespace pangolin svc/pangolin 8080:3002
Then open:
http://localhost:8080
The chart routes /api/v1 to the Pangolin external/API port and the dashboard route to the Next/UI port. The default service ports are 3000 for external/API and 3002 for the dashboard/UI. ([GitHub][1])

​
Switch Gerbil to normal startup

If you installed with gerbil.startupMode=delayed, switch Gerbil to normal mode after the initial setup is complete: 
helm upgrade pangolin fossorial/pangolin \
  --namespace pangolin \
  --reuse-values \
  --set gerbil.startupMode=normal
Check Gerbil resources: 
kubectl get pods,svc,pvc --namespace pangolin \
  -l app.kubernetes.io/name=gerbil

​
Upgrade

Update the Helm repository: 
helm repo update fossorial
Upgrade the release: 
helm upgrade pangolin fossorial/pangolin \
  --namespace pangolin \
  --values values-pangolin.yaml
Check upgrade status: 
helm status pangolin --namespace pangolin
helm history pangolin --namespace pangolin
Rollback if needed: 
helm rollback pangolin <revision> --namespace pangolin

​
OCI install

The Pangolin chart is also published as an OCI chart in GHCR. Pull the chart: 
helm pull oci://ghcr.io/fosrl/helm-charts/pangolin \
  --version 0.1.0-alpha.0
Install from OCI: 
helm upgrade --install pangolin oci://ghcr.io/fosrl/helm-charts/pangolin \
  --version 0.1.0-alpha.0 \
  --namespace pangolin \
  --values values-pangolin.yaml
OCI changes where Helm pulls the chart from. It does not change the values file or the release behavior.

​
Architecture overview

Recommended deployment mode: 
deployment:
  type: controller
  mode: multi
In this topology:
ComponentRole
PangolinMain application, dashboard, API, authentication, and configuration.
pangolin-kube-controllerReconciles dynamic Kubernetes and Traefik CRD configuration.
GerbilWireGuard tunnel manager for Pangolin sites.
TraefikRoutes dashboard, API, and site traffic.
CloudNativePG / PostgreSQLStores Pangolin application state.
Database modes:
ModeUse case
cloudnativepgRecommended Kubernetes production path.
externalProduction path with externally managed PostgreSQL.
embeddedLab or test setups.
sqliteDevelopment or CI only.
The chart supports cloudnativepg, external, embedded, and sqlite database modes. The chart comments mark cloudnativepg as the preferred production mode and SQLite as development/test only. ([GitHub][1])

​
Chart signing

The chart metadata includes Artifact Hub signing information: 
Fingerprint: 48E7F670FCC13645FC48B08D587294B228C2EC2C
Public key: https://charts.fossorial.io/pgp_keys.asc
Use this metadata when verifying signed chart releases. The signing key and fingerprint are published in the chart annotations. ([GitHub][2])

​
References

Chart README

values.yaml

values.schema.json

Examples

Issues

​
Next steps

Full Configuration

Review Pangolin chart options.

Troubleshooting

Debug Pangolin deployment and routing issues.

Kustomize Install

Install Pangolin with rendered manifests and Kustomize overlays.

GitOps

Deploy Pangolin with Argo CD or Flux.