How To Install Pangolin on Ubuntu 24.04 LTS

9 minutes read

Running self-hosted services is incredibly rewarding — until you hit the wall of exposing them safely to the internet. Opening ports on your home router, dealing with dynamic IPs, or trusting a third-party tunnel provider are all messy compromises. Pangolin eliminates every one of those headaches. It is a free, open-source, identity-aware tunneled reverse proxy that gives you complete control over how your services are accessed from anywhere in the world.

This step-by-step guide walks you through exactly how to install Pangolin on Ubuntu 24.04 LTS, from a fresh server all the way to a live, SSL-secured dashboard with a tunneled client device connected. Everything has been tested on a live Ubuntu 24.04 LTS VPS environment. Set aside about 20–30 minutes and you will have a production-ready setup by the end.

Table of Contents

What Is Pangolin?

Pangolin is an open-source tunneling reverse proxy developed and maintained by the fosrl team. At its core, it is a self-hosted alternative to services like Cloudflare Tunnel or Tailscale Funnel — but it lives entirely on infrastructure you own. The stack runs on Docker and is composed of three tightly integrated components:

Pangolin — the central control plane, dashboard, and identity/access management layer
Gerbil — the WireGuard-based tunnel daemon that manages encrypted VPN connections between your server and client nodes
Traefik — the reverse proxy responsible for HTTP/HTTPS routing and automatic TLS certificate provisioning via Let’s Encrypt

Think of it like a private, encrypted highway. Your public-facing VPS acts as the entry point. Traffic arrives on your domain, passes through Traefik, travels down a WireGuard tunnel managed by Gerbil, and lands on the private service running on your home network or internal server — all without a single open port on your local firewall.

Why Choose Pangolin Over Cloudflare Tunnel?

Both tools solve the same core problem, but they take very different philosophical approaches. Cloudflare Tunnel is convenient, but all your traffic passes through Cloudflare’s infrastructure. Pangolin keeps every byte on your own servers.

Feature	Pangolin	Cloudflare Tunnel
Self-hosted	✅ Yes	❌ No
Works behind CGNAT	✅ Yes	✅ Yes
Built-in SSO / 2FA	✅ Yes (free)	✅ (Zero Trust, paid tier)
Data ownership	✅ Full	❌ Partial
Cost	Free, open-source	Free (with limits)

Pangolin also supports built-in access control features like PIN codes, SSO, temporary shareable links, and two-factor authentication — natively, at no cost. For homelabs, small businesses, or privacy-conscious users, the combination of data sovereignty and zero licensing fees makes it the stronger long-term choice.

Prerequisites Before You Begin

Before touching a single command, make sure you have these essentials ready:

A VPS with a public IP address running Ubuntu 24.04 LTS — providers like DigitalOcean, Hetzner, Vultr, or RamNode all work well
Root or sudo access on both the server and the client device you want to expose
A registered domain name with DNS A-records already pointing to your server’s public IP — a wildcard * A-record simplifies multi-service setups significantly
Four open firewall ports: TCP 80, TCP 443, UDP 51820, UDP 21820
A valid email address for Let’s Encrypt certificate generation and admin account creation
Minimum hardware: 1 vCPU and 1 GB RAM (2 GB recommended for comfortable performance)

One thing worth highlighting: you do not need to install Docker manually. The Pangolin installer handles the entire Docker and Docker Compose setup automatically.

Step 1: Update Your Ubuntu 24.04 LTS System

Always start with a clean, fully updated system. This prevents dependency conflicts and ensures your server has the latest security patches applied before any new software is introduced.

sudo apt update && sudo apt upgrade -y

If the upgrade includes kernel-level changes, reboot before continuing:

sudo reboot

Wait for the server to come back online, then reconnect via SSH before moving to the next step.

Step 2: Install Required Dependencies

Pangolin’s installer relies on four command-line utilities. Install them all in one go:

sudo apt install wget sed curl jq -y

Here is what each one does during the install process:

curl — fetches the installer script and queries the GitHub API
wget — downloads the versioned Pangolin binary from GitHub Releases
jq — parses JSON responses to auto-detect the latest available version
sed — processes CPU architecture strings to select the correct binary build

Step 3: Create the Installation Directory

Pangolin generates all its configuration files — including docker-compose.yml and the config/ folder — in whichever directory you run the installer from. The /opt/ path is the standard Linux convention for third-party software not managed by a package manager.

sudo mkdir -p /opt/pangolin
cd /opt/pangolin

Stay in this directory for the remainder of the installation.

Step 4: Download the Pangolin Installer

There are two ways to get the installer. The official quick-install script is the fastest option:

curl -fsSL https://static.pangolin.net/get-installer.sh | bash

If you prefer to avoid piping directly to bash — which is a reasonable security posture in production environments — use the manual method instead. It fetches the same binary but lets you inspect each step:

VERSION=$(curl -s "https://api.github.com/repos/fosrl/pangolin/tags" | jq -r '.[0].name')
CPU=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
wget -O installer "https://github.com/fosrl/pangolin/releases/download/$VERSION/installer_linux_$CPU"

The installer supports both AMD64 (standard x86 VPS hardware) and ARM64 (ARM-based servers like Ampere instances).

Step 5: Grant Permissions and Run the Installer

Make the downloaded binary executable, then launch it with elevated privileges:

sudo chmod +x ./installer
sudo ./installer

The installer immediately launches an interactive setup wizard. It also installs Docker and Docker Compose on your system automatically if they are not already present.

Step 6: Navigate the Installation Wizard

This is the most important phase. The wizard asks a series of questions that configure your entire Pangolin environment. Work through each prompt carefully.

6a — Choose Your Edition

Select Community Edition when prompted. It is completely free and contains every feature needed for personal use, homelabs, and small teams.

6b — Set Your Base Domain and Dashboard Subdomain

Enter your root domain exactly as registered (e.g., example.com). Next, either accept the default dashboard subdomain (pangolin.example.com) or type a custom one. Press Enter to confirm.

6c — Provide Your Let’s Encrypt Email

Enter a real, reachable email address. Let’s Encrypt uses it to send certificate expiry warnings and renewal notices.

6d — Enable Gerbil Tunneling

Accept the default yes. Gerbil is what powers the WireGuard tunnel. Without it, Pangolin functions only as a traditional HTTP reverse proxy and loses its ability to route traffic through secure tunnels.

6e — Create the Admin User

Set your admin email and a strong password. The password must satisfy complexity requirements: at least one uppercase letter, one lowercase letter, one number, and one special character. Weak passwords are rejected by the installer.

6f — Security Flags

When prompted to disable open signup, answer yes. This prevents unauthorized users from registering accounts on your Pangolin instance. Optionally disable user-level organization creation if this is a single-admin deployment.

6g — SMTP Email Setup

Skip this with no unless you have a working SMTP server available. Email-based features like user invitations can be configured later from inside the dashboard.

6h — Docker, Container Start, and CrowdSec

Confirm the Docker installation prompt with yes. Confirm starting the containers with yes. When asked about CrowdSec — an intrusion detection and bot-blocking layer — choose based on your needs. Most new users can safely leave it as no and add it later.

The wizard completes, pulls all Docker images, and starts the containers. The whole process typically takes two to four minutes depending on your server’s internet speed.

Step 7: Open Required Firewall Ports

If UFW is active on your Ubuntu server, open all four required ports before attempting to access the dashboard:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 51820/udp
sudo ufw allow 21820/udp
sudo ufw reload

Port purposes at a glance:

80/443 TCP — Standard HTTP/HTTPS for the dashboard and all proxied services
51820 UDP — WireGuard VPN tunnel managed by Gerbil
21820 UDP — Newt client tunnel connection port

Important: If your VPS runs behind a cloud provider’s network firewall (such as AWS Security Groups, DigitalOcean Firewall, or Hetzner Firewall), you must also open these ports in the provider’s web console. UFW alone is not enough in those environments.

Verify UFW is configured correctly with:

sudo ufw status

Step 8: Access Your Pangolin Web Dashboard

Once the installer exits successfully, your terminal will display a completion message with a URL similar to:

Installation complete!
Visit: https://pangolin.yourdomain.com/auth/initial-setup

Open that URL in a browser. Traefik automatically provisions a Let’s Encrypt TLS certificate on first access, so allow up to three minutes for the padlock icon to appear. Log in using the admin email and password you set during the wizard.

Troubleshooting tip: If the page does not load, run dig pangolin.yourdomain.com to verify DNS propagation and double-check that all four firewall ports are open. SSL issues are almost always caused by DNS not yet resolving correctly.

Step 9: Create Your Organization and First Site

On first login, the dashboard walks you through creating an Organization — a top-level namespace that groups together all your tunneled locations. Give it a meaningful name (e.g., Home Lab or Main Office) and a URL-safe slug identifier.

Next, create a Site. A site represents a physical or virtual location where the Newt tunnel client will be deployed:

Click Sites → Add Site
Enter a descriptive site name
Select Newt as the tunnel type
Copy and save the three generated values securely:
- Newt Endpoint — your dashboard URL with port
- Newt ID — a unique identifier for this site
- Newt Secret Key — the authentication credential for the tunnel
Click Create Site

The site will initially display as Offline. That changes once Newt connects from your client device.

Step 10: Connect Client Devices Using Newt

Newt is the lightweight tunnel client that runs on the machine hosting your private services. Deploy it using Docker Compose on the client device — this is the cleanest approach for most setups:

Create a compose.yaml file:

services:
  newt:
    image: fosrl/newt
    container_name: newt
    restart: unless-stopped
    environment:
      - PANGOLIN_ENDPOINT=<YOUR_NEWT_ENDPOINT>
      - NEWT_ID=<YOUR_NEWT_ID>
      - NEWT_SECRET=<YOUR_NEWT_SECRET>

Start it with:

docker compose up -d

Prefer a native binary instead? Download the Newt binary, make it executable, and register it as a systemd service for automatic startup on reboot:

sudo systemctl enable newt
sudo systemctl start newt

After Newt connects, return to your Pangolin dashboard — the site status flips from Offline to ✅ Online within seconds.

Step 11: Expose a Service as a Pangolin Resource

With the tunnel live, you can now expose any service running on your private network to the internet via a secure, authenticated subdomain.

Navigate to Resources → Add Resource and fill in the following:

Name — a recognizable label (e.g., Home Assistant, Jellyfin, Nextcloud)
Site — select the connected Newt site created in the previous step
Resource Type — choose HTTPS Resource for web applications or Raw TCP/UDP Resource for non-HTTP services like game servers or databases
Subdomain — the prefix for your domain (e.g., homeassistant results in homeassistant.yourdomain.com)
Target — specify the protocol (http or https), the local IP address or hostname, and the service port (e.g., port 8123 for Home Assistant)

Toggle Platform SSO to control whether users must authenticate through Pangolin before reaching the service. Save the resource and open the subdomain in a browser to confirm it is live and HTTPS-secured.

Troubleshooting Common Pangolin Issues

Even a clean installation occasionally throws a curve. Here are the most frequent problems and their fixes:

Issue	Cause	Fix
Dashboard unreachable	DNS not propagated or ports closed	Run `dig` to verify DNS; check UFW and cloud firewall
SSL certificate error	DNS lag or Let’s Encrypt rate limit	Wait 5–10 minutes; check Traefik logs
Site shows “Offline”	Newt not running or wrong credentials	Verify Newt logs with `docker compose logs newt`
Installer fails midway	Permission issue or Docker conflict	Re-run as `sudo`; allow Docker install when prompted
Password rejected	Does not meet complexity requirements	Include uppercase, lowercase, digit, and special character

For real-time debugging, run docker compose logs -f from inside /opt/pangolin. This streams live output from all three containers — Pangolin, Gerbil, and Traefik — simultaneously.

How to Update Pangolin on Ubuntu 24.04

Keeping Pangolin current is straightforward since updates are applied through Docker image tags.

Navigate to the install directory: cd /opt/pangolin
Back up your config: sudo cp -r config/ config_backup/
Fetch the latest version numbers for Pangolin, Gerbil, and Traefik from their respective GitHub repositories
Open docker-compose.yaml and update the three image version tags: sudo nano docker-compose.yaml
Pull the updated images: docker compose pull
Restart all containers: docker compose up -d

Always back up the config/ directory before any update. That folder contains your entire Pangolin configuration and is the only thing you need to restore a fully working instance from scratch.

Congratulations! You have successfully installed Pangolin. Thanks for using this tutorial for installing the Pangolin on the Ubuntu 24.04 LTS system. For additional help or useful information, we recommend you check the official Pangolin website.

VPS Manage Service Offer

If you don’t have time to do all of this stuff, or if this is not your area of expertise, we offer a service to do “VPS Manage Service Offer”, starting from $10 (Paypal payment). Please contact us to get the best deal!