Pangolin on VPS: expose a service behind NAT without open ports

The problem: exposing a service behind NAT

What Pangolin brings over the alternatives

• Fully self-hosted — your traffic only transits through your VPS, no third party sees your application traffic.
• No inbound port required — the connection is initiated from the origin machine to the VPS (outbound), NAT is never an obstacle.
• Automatic HTTPS via Let's Encrypt — Pangolin manages certificates for each exposed subdomain, no manual intervention.
• Built-in web interface — add tunnels, manage resources and users from a web panel, no config files to edit.
• End-to-end WireGuard encryption — the tunnel between the origin machine and the VPS is encrypted at the transport layer, independently of application HTTPS.
• Multi-site — a single Pangolin instance on the VPS can relay dozens of services from different machines, under distinct subdomains.

Architecture: VPS relay, Gerbil and Newt

[Origin machine]                   [ServOrbit VPS]              [Internet]
  service:8080                      Pangolin (orchestration)
  newt (client)  ←─WireGuard UDP─→  Gerbil  (WG tunnel)    ←─HTTPS──→  visitor
                                    Traefik (reverse proxy)

Prerequisites

Deploying Pangolin and Gerbil on the VPS

1. 01

   Prepare the VPS and open the WireGuard port

   Connect as root to the VPS and install Docker if not already present:

   apt update && apt install -y docker.io docker-compose-plugin ufw

   Open the UDP port for WireGuard (default 51820) and ensure HTTP/HTTPS ports are accessible:

   ufw allow 80/tcp
   ufw allow 443/tcp
   ufw allow 51820/udp
   ufw enable

   To restrict access to the admin panel (default port 3000), limit it to your IP:

   ufw allow from YOUR_IP to any port 3000

2. 02

   Create the docker-compose.yml file

   Create a working directory and the configuration file:

   mkdir -p /opt/pangolin && cd /opt/pangolin

   Create docker-compose.yml with the following content:

   cat > docker-compose.yml <<'EOF'
   services:
     pangolin:
       image: fosrl/pangolin:1.23.0
       container_name: pangolin
       restart: unless-stopped
       volumes:
         - ./config:/app/config
         - ./data:/app/data
       ports:
         - "3000:3000"
       networks:
         - pangolin_net
   
     gerbil:
       image: fosrl/gerbil:latest
       container_name: gerbil
       restart: unless-stopped
       cap_add:
         - NET_ADMIN
       volumes:
         - ./data:/var/lib/gerbil
       ports:
         - "51820:51820/udp"
       networks:
         - pangolin_net
       depends_on:
         - pangolin
   
   networks:
     pangolin_net:
       driver: bridge
   EOF

   Adjust the pangolin image version number to the latest release available on GitHub.

3. 03

   Configure Pangolin and start the stack

   Create the configuration directory and a minimal config.yml:

   mkdir -p /opt/pangolin/config
   cat > /opt/pangolin/config/config.yml <<'EOF'
   app:
     base_domain: yourdomain.com
     admin_email: [email protected]
     port: 3000
   
   wireguard:
     port: 51820
     subnet: 10.0.0.0/24
   
   acme:
     enabled: true
     staging: false
   EOF

   Replace yourdomain.com with your actual domain. Start the stack:

   cd /opt/pangolin && docker compose up -d
   docker compose logs -f pangolin

   Pangolin generates an admin password on first start — note it from the logs. The web interface is available at http://VPS_IP:3000.

4. 04

   Configure the wildcard DNS record

   In your DNS zone, create a wildcard A record pointing to the VPS IP:

   *.yourdomain.com  →  A  →  VPS_IP

   On Cloudflare, create this record with the proxy disabled (DNS-only, grey cloud) so that Let's Encrypt certificates can be issued correctly via the HTTP-01 challenge used by Pangolin.

5. 05

   Create a systemd unit for automatic restart

   Docker with restart: unless-stopped is generally sufficient, but if you prefer a dedicated systemd unit:

   cat > /etc/systemd/system/pangolin.service <<'EOF'
   [Unit]
   Description=Pangolin reverse tunnel stack
   After=docker.service
   Requires=docker.service
   
   [Service]
   Type=oneshot
   RemainAfterExit=yes
   WorkingDirectory=/opt/pangolin
   ExecStart=/usr/bin/docker compose up -d
   ExecStop=/usr/bin/docker compose down
   
   [Install]
   WantedBy=multi-user.target
   EOF
   
   systemctl daemon-reload
   systemctl enable pangolin

Adding a tunnel with Newt on the origin machine

1. 06

   Create a tunnel in the Pangolin interface

   Log into the Pangolin web interface at http://VPS_IP:3000 with your admin credentials. Go to Sites → Add site, give it a name (e.g. homelab) and note the generated site token. Then under Resources → Add resource, choose the site, enter the desired subdomain (nextcloud.yourdomain.com) and the local port of the origin machine (e.g. 8080).

2. 07

   Install Newt on the origin machine

   On the machine hosting your service, download the Newt binary for your architecture:

   # Linux x86_64
   curl -Lo /usr/local/bin/newt \
     https://github.com/fosrl/newt/releases/latest/download/newt-linux-amd64
   chmod +x /usr/local/bin/newt

   For a Raspberry Pi (ARM64):

   curl -Lo /usr/local/bin/newt \
     https://github.com/fosrl/newt/releases/latest/download/newt-linux-arm64
   chmod +x /usr/local/bin/newt

3. 08

   Configure and start Newt

   Launch Newt with the site token retrieved in the previous step:

   newt \
     --server https://yourdomain.com:3000 \
     --token YOUR_SITE_TOKEN \
     --target localhost:8080

   For automatic startup, create a systemd unit:

   cat > /etc/systemd/system/newt.service <<'EOF'
   [Unit]
   Description=Newt WireGuard tunnel client
   After=network.target
   
   [Service]
   ExecStart=/usr/local/bin/newt \
     --server https://yourdomain.com:3000 \
     --token YOUR_SITE_TOKEN \
     --target localhost:8080
   Restart=always
   RestartSec=5
   
   [Install]
   WantedBy=multi-user.target
   EOF
   
   systemctl daemon-reload
   systemctl enable --now newt

4. 09

   Verify end-to-end connectivity

   On the VPS, verify that the WireGuard tunnel is established:

   docker exec gerbil wg show

   You should see a peer with a recent latest handshake. From any browser or command line:

   curl -I https://nextcloud.yourdomain.com

   Expected response: HTTP/2 200 (or your service's login page). The Let's Encrypt certificate is issued automatically on first access.

Exposing a service: Nextcloud behind NAT example

1. 10

   Configure Nextcloud to accept the proxy domain

   Nextcloud blocks requests from undeclared domains. Add the public domain to config.php:

   # From the origin machine, in the Nextcloud directory
   nano config/config.php

   Add to the trusted_domains array:

   'trusted_domains' =>
     array (
       0 => 'localhost',
       1 => 'nextcloud.yourdomain.com',
     ),
   'overwritehost' => 'nextcloud.yourdomain.com',
   'overwriteprotocol' => 'https',

2. 11

   Verify public access and certificate

   Wait 30 to 60 seconds after first access for Let's Encrypt to issue the certificate, then:

   curl -v https://nextcloud.yourdomain.com 2>&1 | grep -E 'subject|issuer|HTTP'

   The certificate is signed by Let's Encrypt and the public URL is now accessible from any network, with no open ports on the local network side.

Troubleshooting

Pangolin vs Cloudflare Tunnel vs Tailscale/Headscale

Scroll the table

Going further