Skip to main content

​
Prerequisites

Before you begin, ensure you have:
  • Linux server with root access and public IP address
  • Domain name pointing to your server’s IP address for the dashboard
  • Email address for Let’s Encrypt SSL certificates and admin log in
  • Open ports on firewall for 80 (TCP), 443 (TCP), 51820 (UDP), and 21820 (UDP for clients)
Recommended: Ubuntu 20.04+ or Debian 11+ for best compatibility and performance.

​
Choose Your Server

Need help choosing? See our complete VPS guide for suggestions.

​
DNS & Networking

Before installing Pangolin, ensure you’ve set up DNS for your domain(s) and opened the required port on your firewall. See our guide on DNS & networking for more information.

​
Installation Process

1

Download the installer

Connect to your server via SSH and download the installer:
curl -fsSL https://pangolin.net/get-installer.sh | bash
The installer supports both AMD64 (x86_64) and ARM64 architectures.
2

Run the installer

Execute the installer with root privileges:
sudo ./installer
The installer places all files in the current directory. Move the installer to your desired installation directory before running it.
3

Configure basic settings

The installer will prompt you for essential configuration:
  • Base Domain: Enter your root domain without subdomains (e.g., example.com)
  • Dashboard Domain: Press Enter to accept the default pangolin.example.com or enter a custom domain
  • Let’s Encrypt Email: Provide an email for SSL certificates and admin login
  • Tunneling: Choose whether to install Gerbil for tunneled connections (default: yes). You can run Pangolin without tunneling. It will function as a standard reverse proxy.
4

Configure email (optional)

Email functionality is optional and can be added later.
Choose whether to enable SMTP email functionality:
  • Default: No (recommended for initial setup)
  • If enabled: You’ll need SMTP server details (host, port, username, password)
5

Start installation

Confirm that you want to install and start the containers:
  • The installer will pull Docker images (pangolin, gerbil, traefik)
  • Containers will be started automatically
  • This process takes 2-3 minutes depending on your internet connection
You’ll see progress indicators as each container is pulled and started.
6

Install CrowdSec (optional)

The installer will ask if you want to install CrowdSec for additional security:
  • Default: No (recommended for initial setup)
  • If enabled: You’ll need to confirm you’re willing to manage CrowdSec configuration
CrowdSec adds complexity and requires manual configuration for optimal security. Only enable if you’re comfortable managing it.
CrowdSec can be installed later if needed. The basic installation provides sufficient security for most use cases.

​
Post-Installation Setup

Once installation completes successfully, you’ll see: 
Installation complete!

To complete the initial setup, please visit:
https://pangolin.example.com/auth/initial-setup
1

Access the dashboard

Navigate to the URL shown in the installer output:
https://<your-dashboard-domain>/auth/initial-setup
The dashboard should load with SSL certificate automatically configured. It might take a few minutes for the first cert to validate, so don’t worry if the browser throws an insecure warning.
2

Create admin account

Complete the initial admin user setup:
  • Enter your admin email address
  • Set a strong password
  • Verify your email (if email is configured)
Use a strong, unique password for your admin account. This account has full system access.
3

Create your first organization

After logging in:
  1. Click “Create Organization”
  2. Enter organization name and description
You’re now ready to start adding applications and configuring your reverse proxy!