How to Deploy Pangolin on a VPS

#Install Pangolin

Pangolin ships an interactive one-command installer (curl -fsSL https://static.pangolin.net/get-installer.sh | bash then sudo ./installer) that walks you through the setup with prompts. This guide uses Pangolin's other officially documented install path instead — manual Docker Compose — because every value is supplied up front in config files, which makes the whole install scriptable and reproducible rather than answered by hand.

First generate a random secret Pangolin uses to sign sessions — treat it like a password:

copyexport PANGOLIN_SECRET=$(openssl rand -hex 32)
echo "$PANGOLIN_SECRET" > ~/pangolin/.pangolin-secret
chmod 600 ~/pangolin/.pangolin-secret

Create the Compose file:

copycat > docker-compose.yml <<'EOF'
name: pangolin
services:
  pangolin:
    image: docker.io/fosrl/pangolin:latest
    container_name: pangolin
    restart: unless-stopped
    volumes:
      - ./config:/app/config
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3001/api/v1/"]
      interval: "10s"
      timeout: "10s"
      retries: 15

  gerbil:
    image: docker.io/fosrl/gerbil:latest
    container_name: gerbil
    restart: unless-stopped
    depends_on:
      pangolin:
        condition: service_healthy
    command:
      - --reachableAt=http://gerbil:3004
      - --generateAndSaveKeyTo=/var/config/key
      - --remoteConfig=http://pangolin:3001/api/v1/
    volumes:
      - ./config/:/var/config
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    ports:
      - 51820:51820/udp
      - 21820:21820/udp
      - 443:443
      - 80:80

  traefik:
    image: docker.io/traefik:v3.6
    container_name: traefik
    restart: unless-stopped
    network_mode: service:gerbil
    depends_on:
      pangolin:
        condition: service_healthy
    command:
      - --configFile=/etc/traefik/traefik_config.yml
    volumes:
      - ./config/traefik:/etc/traefik:ro
      - ./config/letsencrypt:/letsencrypt
      - ./config/traefik/logs:/var/log/traefik

networks:
  default:
    driver: bridge
    name: pangolin
EOF

Traefik's static config — this is where the Let's Encrypt email lives:

copycat > config/traefik/traefik_config.yml <<'EOF'
api:
  insecure: true
  dashboard: true

providers:
  http:
    endpoint: "http://pangolin:3001/api/v1/traefik-config"
    pollInterval: "5s"
  file:
    filename: "/etc/traefik/dynamic_config.yml"

experimental:
  plugins:
    badger:
      moduleName: "github.com/fosrl/badger"
      version: "v1.4.0"

log:
  level: "INFO"
  format: "common"
  maxSize: 100
  maxBackups: 3
  maxAge: 3
  compress: true

certificatesResolvers:
  letsencrypt:
    acme:
      httpChallenge:
        entryPoint: web
      email: "admin@example.com"
      storage: "/letsencrypt/acme.json"
      caServer: "https://acme-v02.api.letsencrypt.org/directory"

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
    transport:
      respondingTimeouts:
        readTimeout: "30m"
    http:
      tls:
        certResolver: "letsencrypt"
      encodedCharacters:
        allowEncodedSlash: true
        allowEncodedQuestionMark: true

serversTransport:
  insecureSkipVerify: true

ping:
  entryPoint: "web"
EOF

Traefik's dynamic config — the routers that get the dashboard itself online (every other route, for resources you publish later, Pangolin pushes to Traefik live via the http provider above):

copycat > config/traefik/dynamic_config.yml <<'EOF'
http:
  middlewares:
    badger:
      plugin:
        badger:
          disableForwardAuth: true
    redirect-to-https:
      redirectScheme:
        scheme: https

  routers:
    main-app-router-redirect:
      rule: "Host(`pangolin.example.com`)"
      service: next-service
      entryPoints:
        - web
      middlewares:
        - redirect-to-https
        - badger

    next-router:
      rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)"
      service: next-service
      entryPoints:
        - websecure
      middlewares:
        - badger
      tls:
        certResolver: letsencrypt

    api-router:
      rule: "Host(`pangolin.example.com`) && PathPrefix(`/api/v1`)"
      service: api-service
      entryPoints:
        - websecure
      middlewares:
        - badger
      tls:
        certResolver: letsencrypt

    ws-router:
      rule: "Host(`pangolin.example.com`)"
      service: api-service
      entryPoints:
        - websecure
      middlewares:
        - badger
      tls:
        certResolver: letsencrypt

  services:
    next-service:
      loadBalancer:
        servers:
          - url: "http://pangolin:3002"

    api-service:
      loadBalancer:
        servers:
          - url: "http://pangolin:3000"

tcp:
  serversTransports:
    pp-transport-v1:
      proxyProtocol:
        version: 1
    pp-transport-v2:
      proxyProtocol:
        version: 2
EOF

And Pangolin's own config — the base domain, dashboard hostname, and the secret you generated:

copycat > config/config.yml <<EOF
gerbil:
    start_port: 51820
    base_endpoint: "pangolin.example.com"

app:
    dashboard_url: "https://pangolin.example.com"
    log_level: "info"
    telemetry:
        anonymous_usage: true

domains:
    domain1:
        base_domain: "example.com"

server:
    secret: "${PANGOLIN_SECRET}"
    cors:
        origins: ["https://pangolin.example.com"]
        methods: ["GET", "POST", "PUT", "DELETE", "PATCH"]
        allowed_headers: ["X-CSRF-Token", "Content-Type"]
        credentials: false

flags:
    require_email_verification: false
    disable_signup_without_invite: true
    disable_user_create_org: false
    allow_raw_resources: true
EOF

Before starting, replace every example.com / pangolin.example.com / admin@example.com placeholder across the three config files with your real base domain, dashboard hostname, and email (see the wildcard DNS section below for what to use if you don't have a domain yet). Then bring the stack up:

copydocker compose up -d
docker compose logs --tail 60 pangolin traefik gerbil

Pangolin starts first, Gerbil waits for it to report healthy, and Traefik waits on Pangolin too since it needs the dashboard's live routing config. First boot takes a little longer while images are pulled and Gerbil generates its WireGuard keypair.

#Domain + wildcard DNS

Pangolin gives every resource you publish its own subdomain under your base domain — app1.example.com, app2.example.com, and so on — generated on demand as you create them in the dashboard. Rather than adding a DNS record per resource, point a single wildcard A record at your server once: Type A, Name *, Value <your-server-ip>. From then on, every new subdomain resolves automatically and Traefik's HTTP-01 challenge (configured above) issues it a certificate the first time it's requested — no DNS-provider API keys or DNS-01 setup needed.

No domain yet? Use <your-server-ip>.sslip.io as a throwaway wildcard. sslip.io resolves any subdomain of <ip>.sslip.io to that IP with zero setup — pangolin.203.0.113.10.sslip.io, app1.203.0.113.10.sslip.io, and anything else you make up all resolve correctly, which is exactly the wildcard behavior Pangolin needs. Set your base domain to <your-server-ip>.sslip.io and your dashboard hostname to pangolin.<your-server-ip>.sslip.io in the config files above, and everything else works unchanged. It's fine for testing and evaluation; for anything real, register an actual domain and add the wildcard A record — a sslip.io address is public and guessable, which isn't what you want for production auth-gated resources.

#First-run setup

On first boot Pangolin has no admin account yet. It prints a one-time setup token to its logs:

copydocker compose logs pangolin 2>&1 | grep -i "setup token" || true

Visit https://<your-dashboard-domain>/auth/initial-setup in a browser, paste the token, and set a strong password — this becomes the owner account with full access to every organization and resource. Like most self-hosted admin panels, that setup page is open to whoever gets there first, so do this immediately after the stack comes up.

Once you're in, create your first Site (a tunnel endpoint) and a test Resource pointing at a simple internal service to confirm routing works end to end — the dashboard walks you through installing the Newt client on the machine you're publishing from.

#Backups

Everything that matters lives under ~/pangolin/config: the SQLite database (config/db/db.sqlite), the Let's Encrypt certificates (config/letsencrypt/acme.json), Gerbil's WireGuard key (config/key), and the config files themselves — including the secret in config/config.yml, which signs every session token. Back up the whole directory:

copytar -czf ~/pangolin-backup-$(date +%F).tar.gz -C ~/pangolin config

Copy that archive off the box on a schedule — S3-compatible storage or another machine — and periodically restore it into a throwaway stack to confirm it actually works. A backup you haven't restored is a guess. If you're running more than a handful of resources, consider migrating the datastore to Postgres for better durability under load; that's a config change documented in Pangolin's docs, not something this guide's SQLite default handles for you.

#Upgrades

copydocker compose pull
docker compose up -d

Read the release notes before upgrading, more than with most self-hosted tools — Pangolin's config schema has changed across versions in ways that can break an unattended pull && up -d if you skip straight over a breaking release. Take the backup above first, then upgrade one version at a time rather than jumping several releases, and pin specific image tags (fosrl/pangolin:1.x.x instead of :latest) once you're past initial setup so an upgrade is always a deliberate, single-version step.

#Troubleshooting

Certificate never issues / dashboard shows a self-signed or invalid cert. Almost always DNS. Confirm your wildcard A record (or sslip.io hostname) actually resolves to the server's IP from outside (dig pangolin.example.com from your laptop), and that ports 80 and 443 are open both in ufw and any provider-level cloud firewall — the HTTP-01 challenge needs port 80 reachable from the internet at the exact moment the cert is requested.

502 / Bad Gateway from Traefik. Check docker compose ps — Traefik depends on Pangolin being healthy, and if Pangolin is still starting or crash-looping, Traefik has nowhere to send the request. Check docker compose logs pangolin for the actual error.

Tunnel clients (Newt) can't connect. WireGuard traffic on 51820/udp or 21820/udp is being dropped somewhere between the client and the server — check the provider's cloud firewall in addition to ufw, since many VPS panels ship with UDP blocked by default even when ufw allows it.

Setup page 404s or the dashboard is unreachable at your domain. The Host() rules in dynamic_config.yml and dashboard_url in config.yml must exactly match the hostname you're actually visiting — if you edited one placeholder and missed another, Traefik has no route for the request.

#Verification + next steps

You're done when all three containers show healthy in docker compose ps, the dashboard loads over HTTPS at your real domain with a valid certificate, you've created the owner account, and a test Resource routes traffic from a connected Newt client through to an internal service. From here, invite teammates as users on specific organizations, and layer in an identity provider if you want SSO rather than Pangolin-native logins. A 2 vCPU / 4 GB box comfortably runs Pangolin alongside whatever it's tunneling to; see Best VPS for self-hosting for the ranked picks.