Clean Pangolin Setup Guide

Prerequisites

• Ubuntu VPS with Docker installed
• Domain with DNS pointing to VPS IP
• Ports open: 22, 80, 443, 51820/udp

Step 1: Install Pangolin

cd /opt/docker
mkdir pangolin && cd pangolin

# Download installer
wget https://github.com/fosrl/pangolin/releases/latest/download/installer_linux_amd64
chmod +x installer_linux_amd64

# Run installer
./installer_linux_amd64

Follow prompts:

• Enter your domain (e.g., example.com)
• Choose certificate resolver
• Wait for installation to complete

Step 2: Check Gerbil’s Subnet

cd /opt/docker/pangolin
docker compose logs gerbil | grep "Assigned IP"

Note the subnet (e.g., 100.89.128.1/24 means use 100.89.128.0/24)

Step 3: Initial Setup via Web UI

Visit https://pangolin.yourdomain.com

1. Create admin account
   • Email + password
   • Enable 2FA (TOTP)
   • Optional: Add YubiKey
2. Create organization
   • Name: homelab (or your choice)
   • Subnet: Use Gerbil’s subnet from Step 2 (e.g., 100.89.128.0/24)

Step 4: Open Firewall Port

# Open WireGuard port for Newt/site connections
sudo ufw allow 51820/udp
sudo ufw reload

Step 5: Connect Docker Networks (for VPS services)

If you have existing Docker containers on a custom network:

# Connect Gerbil to your network
docker network connect YOUR_NETWORK_NAME gerbil

# Example:
docker network connect web gerbil

Step 6: Create TrueNAS Site

In Pangolin Dashboard:

1. Sites → Add Site
2. Fill in:
   • Name: tnt-truenas
   • Connection Type: Newt tunnel
   • Address: 100.89.128.2 (next IP after .1)
3. Create Site
4. Copy Newt credentials (ID, Secret, Endpoint)

Step 7: Install Newt on TrueNAS

On TrueNAS (via Apps → Custom App):

services:
  newt:
    cap_add:
      - NET_ADMIN
    container_name: newt
    environment:
      - TZ=Europe/Brussels
      - PANGOLIN_ENDPOINT=https://pangolin.mydomain.com:443
      - NEWT_ID=[YOUR NEWT ID]                        # REPLACE THIS
      - NEWT_SECRET=[YOUR NEWT SECRET]                # REPLACE THIS
      - ROUTE=192.168.50.0/24
    extra_hosts:
      - pangolin.mydomain.com:46.224.78.189
      - pangolin:46.224.78.189
    image: fosrl/newt:latest
    network_mode: bridge
    restart: unless-stopped
    sysctls:
      - net.ipv4.ip_forward=1

Resources: 1 CPU, 256 MB RAM

Step 8: Configure Remote Subnets

In Pangolin Dashboard:

1. Sites → Click tnt-truenas
2. General tab
3. Remote Subnets: Add 192.168.0.0/24 (your homelab network)
4. Save

Verify site shows “Online” (green)

Step 9: Expose Homelab Services

For each service (Jellyfin, Romm, etc.):

1. Resources → Add Resource
2. Fill in:
   • Name: Jellyfin
   • Subdomain: jellyfin
   • Base Domain: yourdomain.com
3. Add Target:
   • Site: tnt-truenas
   • Protocol: http
   • IP: 192.168.50.203 (TrueNAS IP)
   • Port: 8096 (service port)
4. Authentication Tab:
   • Use Platform SSO: ON (for 2FA protection)
5. Create Resource

Access via: https://jellyfin.yourdomain.com