Helm

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.

Recommended quick install

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:

Component	Role
Pangolin	Main application, dashboard, API, authentication, and configuration.
pangolin-kube-controller	Reconciles dynamic Kubernetes and Traefik CRD configuration.
Gerbil	WireGuard tunnel manager for Pangolin sites.
Traefik	Routes dashboard, API, and site traffic.
CloudNativePG / PostgreSQL	Stores Pangolin application state.

Database modes:

Mode	Use case
`cloudnativepg`	Recommended Kubernetes production path.
`external`	Production path with externally managed PostgreSQL.
`embedded`	Lab or test setups.
`sqlite`	Development 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])

About

Manage Pangolin

Self-host Pangolin

Development

What Pangolin deploys

Gerbil setup in the Pangolin chart

Prerequisites

Recommended quick install

Step 1: Create the namespace

Step 2: Create a Pangolin app secret

Step 3: Create a values file

Step 4: Install Pangolin

Step 5: Verify the deployment

Accessing the dashboard

Switch Gerbil to normal startup

Upgrade

OCI install

Architecture overview

Chart signing

References

Chart README

values.yaml

values.schema.json

Examples

Issues

Next steps

Full Configuration

Troubleshooting

Kustomize Install

GitOps

​What Pangolin deploys

​Gerbil setup in the Pangolin chart

​Prerequisites

​Recommended quick install

​Step 1: Create the namespace

​Step 2: Create a Pangolin app secret

​Step 3: Create a values file

​Step 4: Install Pangolin

​Step 5: Verify the deployment

​Accessing the dashboard

​Switch Gerbil to normal startup

​Upgrade

​OCI install

​Architecture overview

​Chart signing

​References

Chart README

values.yaml

values.schema.json

Examples

Issues

​Next steps

Full Configuration

Troubleshooting

Kustomize Install

GitOps

What Pangolin deploys

Gerbil setup in the Pangolin chart

Prerequisites

Recommended quick install

Step 1: Create the namespace

Step 2: Create a Pangolin app secret

Step 3: Create a values file

Step 4: Install Pangolin

Step 5: Verify the deployment

Accessing the dashboard

Switch Gerbil to normal startup

Upgrade

OCI install

Architecture overview

Chart signing

References

Next steps