Deploy on AWS or DigitalOcean
Launch a self-hosted Pangolin server in minutes from a prebuilt AWS or DigitalOcean image
Prebuilt images are the fastest way to self-host Pangolin. They come with Docker, a firewall setup and a guided installer. Every image installs the latest Pangolin release when you set it up, so you never start on an old version.
Before you start
Whichever provider you choose, you need:
-
A domain whose DNS you control. Pangolin uses a base domain (for example
example.com) for the resources you expose, and a dashboard domain (defaultpangolin.example.com) for the admin UI. -
An email address for Let's Encrypt certificates.
-
DNS records pointing at the server's public IP. You can create them as soon as you know the IP:
A pangolin.example.com -> <server public IP> A *.example.com -> <server public IP> -
Open ports: TCP 80 and 443, and UDP 51820 (sites) and 21820 (clients). Both images open these for you.
See DNS & Networking for more detail, and Choosing a VPS for sizing.
Amazon Web Services
Pangolin publishes one Ubuntu 24.04 AMI per architecture:
| Architecture | AMI name | Example instance |
|---|---|---|
| x86_64 | pangolin-ubuntu-24.04-amd64-* | t3.small |
| arm64 / Graviton | pangolin-ubuntu-24.04-arm64-* | t4g.small |
The same AMI installs either the Community Edition (the default) or the Enterprise Edition. You choose the edition when you configure the instance: set PANGOLIN_EDITION in user-data, use the Edition parameter in CloudFormation, or answer the wizard's prompt. The Enterprise Edition is free for personal use and for businesses under $100K USD gross annual revenue. See Enterprise Edition.
The AMIs are available in all default-enabled AWS regions: US East and West, Canada, São Paulo, Ireland, London, Paris, Frankfurt, Stockholm, Mumbai, Tokyo, Seoul, Osaka, Singapore and Sydney.
Graviton (t4g) instances are the most cost-effective choice. t4g.small (2 vCPU, 2 GB) suits most deployments.
Find the AMI
Search for Pangolin in AWS Marketplace and subscribe. The listing shows the AMI ID for each region and offers a one-click CloudFormation launch.
Launch and configure
Pick one way to give the instance your edition, domain and email. With CloudFormation or user-data, the instance sets itself up: it waits until the dashboard domain resolves to it, then installs Pangolin.
Choose the CloudFormation launch option on the Marketplace listing and fill in the parameters:
- Edition:
community(default) orenterprise - BaseDomain and LetsEncryptEmail (required)
- DashboardDomain (optional, default
pangolin.<BaseDomain>) - HostedZoneId (optional). If you give a Route 53 hosted zone, the DNS records are created for you.
- VpcId, SubnetId (a public subnet), SSHLocation (your IP, e.g.
203.0.113.10/32) and optionally a KeyName
The stack creates the security group, the instance and an Elastic IP. Its outputs include the public IP, the dashboard URL, and a command that prints the setup token.
All user-data settings
| Setting | Default | Description |
|---|---|---|
PANGOLIN_EDITION | community | community or enterprise |
PANGOLIN_BASE_DOMAIN | required | Base domain for resources, e.g. example.com |
PANGOLIN_DASHBOARD_DOMAIN | pangolin.<base domain> | Domain for the Pangolin dashboard |
PANGOLIN_EMAIL | required | Let's Encrypt email |
PANGOLIN_INSTALL_GERBIL | true | Enable WireGuard tunneling. Set false to run Pangolin without tunneling |
PANGOLIN_ENABLE_IPV6 | auto | IPv6 on the Docker network. Defaults to on if the instance has an IPv6 address |
PANGOLIN_ENABLE_MAXMIND | true | Download the GeoLite2 databases for geolocation |
PANGOLIN_SMTP_HOST, PANGOLIN_SMTP_PORT, PANGOLIN_SMTP_USER, PANGOLIN_SMTP_PASS, PANGOLIN_SMTP_NO_REPLY | off | Email (SMTP). Enabled when PANGOLIN_SMTP_HOST is set |
PANGOLIN_WAIT_FOR_DNS | true | Wait for the dashboard domain to resolve to the instance before installing |
PANGOLIN_DNS_TIMEOUT | 1800 | Seconds to wait for DNS before installing anyway |
If you give only PANGOLIN_DASHBOARD_DOMAIN, the base domain is that domain with its first label removed (pangolin.example.com → example.com).
Any process on the instance can read user-data. Consider adding SMTP credentials later in /opt/pangolin/config/config.yml instead.
Get the setup token
Once installation finishes (usually a few minutes after DNS resolves), you can read the setup token without SSH:
aws ec2 get-console-output --instance-id i-... --latest --output text | grep 'Setup token'Or over SSH:
pangolin-setup status # waiting-dns | installing | complete | ...
sudo pangolin-setup tokenThen continue with Finish setup.
DigitalOcean
The Pangolin (CE) 1-Click App runs on Ubuntu 24.04 with Docker CE. It installs the latest Pangolin release during setup. The listing is named for the Community Edition, but setup also lets you choose the Enterprise Edition.
Create the droplet
Choose a region close to your users and a plan with at least 1 GB RAM (2 GB recommended). Add your SSH key so you can log in as root.
Open Pangolin (CE) on the DigitalOcean Marketplace and click Create Pangolin (CE) Droplet.
Point DNS at the droplet
Copy the droplet's public IP and create the A records for your dashboard domain and *.<base domain>, as described in Before you start.
SSH in and run the setup
ssh root@<droplet-ip>The setup script starts automatically on first login and downloads the latest installer. Answer the prompts as in the Quick Install Guide: edition, base domain, dashboard domain, Let's Encrypt email, tunneling and optional SMTP.
Copy the setup token
The installer prints the setup token when it finishes. To see it again:
cd /opt/pangolin && docker compose logs pangolin | grep -A2 'SETUP TOKEN'The droplet comes with UFW enabled. Only ports 22, 80, 443 and UDP 51820, 21820 are allowed. For extra protection, restrict SSH to your IP with ufw allow from <your-ip> to any port 22 or a DigitalOcean Cloud Firewall.
Finish setup
Open the dashboard
Go to https://<dashboard domain>/auth/initial-setup.
Certificates can take a few minutes to issue after DNS resolves. A brief browser certificate warning at first is normal.
Create the admin account
Paste the setup token, then enter your admin email and a strong password. The token stops working once the first admin account exists.
Activate Enterprise (if applicable)
On an Enterprise Edition server, open Server Admin → License (/admin/license) and enter your license key. See Activate a License.
You're ready to add a site and expose your first resource.
Updating
Both images install Pangolin with Docker Compose in /opt/pangolin. To update to newer releases, follow How to Update. You don't need a new image.
Troubleshooting
AWS instance is stuck waiting for DNS
Check that the dashboard domain resolves to the instance's public IP:
dig +short pangolin.example.com @1.1.1.1The instance keeps checking and installs anyway after PANGOLIN_DNS_TIMEOUT (30 minutes by default). If the server sits behind a load balancer, set PANGOLIN_WAIT_FOR_DNS=false. Follow progress with sudo tail -f /var/log/pangolin-setup.log.
Browser shows a certificate error
Let's Encrypt can only issue certificates once DNS points at the server and port 80 is reachable. After fixing DNS or the firewall, restart Traefik:
cd /opt/pangolin && sudo docker compose restart traefikAWS setup failed
Run pangolin-setup status and read /var/log/pangolin-setup.log. After fixing the cause, run sudo pangolin-setup to try again.
Sites can't connect
Make sure UDP 51820 (and UDP 21820 for clients) is open in the AWS security group, or in the DigitalOcean firewall if you added one.
Was this page helpful?