Deploying Pangolin on AlmaLinux in AWS/Or any General Cloud

Networking
,
1

Comprehensive Guide: Deploying Pangolin on AlmaLinux in AWS

image
image1174×399 42.6 KB

asciicast

https://asciinema.org/a/EXTNqMyTMpxMJRyPxQcvwTv78

This guide will walk you through deploying Pangolin, a self-hosted tunneled reverse proxy management server, on an AlmaLinux EC2 instance in AWS.

1. Prerequisites

  • An AWS account
  • A domain name with access to DNS settings
  • Basic knowledge of AWS services and Linux command line

2. AWS Setup

Creating an EC2 Instance

  1. Log in to the AWS Management Console and navigate to EC2
  2. Click “Launch Instance”
  3. Provide a name (e.g., “pangolin-server”)
  4. Select “AlmaLinux 9” from the AMI catalog (search in AWS Marketplace)
  5. Choose an instance type:
    • Recommended: t3.micro (1 vCPU, 1GB RAM) for testing
    • Production: t3.small (2 vCPU, 2GB RAM) or better
  6. Create or select a key pair for SSH access
  7. Configure network settings:
    • Create a new security group with the following rules:
      • SSH (TCP port 22) from your IP
      • HTTP (TCP port 80) from anywhere
      • HTTPS (TCP port 443) from anywhere
      • WireGuard (UDP port 51820) from anywhere
  8. Configure storage (8GB minimum, 20GB recommended)
  9. Launch the instance

Allocate an Elastic IP

  1. Navigate to “Elastic IPs” in the EC2 dashboard
  2. Click “Allocate Elastic IP address”
  3. Select “Amazon’s pool of IPv4 addresses”
  4. Click “Allocate”
  5. Select the newly allocated IP and click “Associate Elastic IP address”
  6. Select your EC2 instance and click “Associate”

3. DNS Configuration

  1. In your domain registrar’s DNS settings, create the following records:
    • An A record for your root domain (e.g., example.com) pointing to your Elastic IP
    • An A record for a subdomain (e.g., proxy.example.com) pointing to your Elastic IP
    • A wildcard A record (e.g., *.example.com) pointing to your Elastic IP

4. Server Preparation

Connect to Your Instance

ssh -i your-key.pem ec2-user@your-elastic-ip

Update the System

sudo dnf update -y
sudo dnf install -y curl wget git vim

Install Docker and Docker Compose

# Install Docker
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to the docker group (optional but recommended)
sudo usermod -aG docker $USER
# Log out and back in for this to take effect

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

Create the Pangolin Directory

mkdir -p ~/pangolin
cd ~/pangolin

5. Install Pangolin

Download and Run the Installer

# Download the installer (AMD64 architecture)
wget -O installer "https://github.com/fosrl/pangolin/releases/download/1.0.0-beta.14/installer_linux_amd64" && chmod +x ./installer
chmod +x ./installer

# Run the installer as root
sudo ./installer

When prompted, provide the following information:

  1. Base Domain Name: Your domain (e.g., example.com)
  2. Dashboard Domain Name: Your preferred dashboard domain (e.g., proxy.example.com)
  3. Let’s Encrypt Email: Your email for SSL certificate registration
  4. Tunneling: Choose “Yes” to install Gerbil for tunneling support
  5. Admin Email: Email for the admin account (e.g., admin@example.com)
  6. Admin Password: Create a strong password meeting the requirements
  7. Security Settings:
    • Disable signup without invite (recommended)
    • Allow/disallow users to create organizations based on your needs
  8. Email Configuration (optional but recommended):
    • SMTP host
    • SMTP port
    • SMTP username
    • SMTP password
    • No-reply email address

The installer will:

  • Create necessary directories
  • Generate configuration files
  • Pull Docker images
  • Start the containers

6. Verify Installation

Check Container Status

cd ~/pangolin
docker compose ps

You should see the following containers running:

  • pangolin
  • gerbil
  • traefik
  • crowdsec (optional)

Check Logs

# Check logs for all containers
docker compose logs

# Or check logs for a specific container
docker compose logs pangolin

Access the Dashboard

Open your browser and navigate to your dashboard domain (e.g., https://proxy.example.com).
You should see the Pangolin login page.

7. Initial Configuration

First Login

  1. Log in with the admin email and password you provided during installation
  2. Follow the setup wizard:
    • Create your first organization
    • Create your first site

Create a Site

  1. Go to the “Sites” tab and click “Add Site”
  2. Give your site a name (e.g., “Home Lab”)
  3. Choose your connection method:
    • Newt (recommended for most users)
    • WireGuard (advanced)
  4. Copy the connection command/configuration
  5. Click “Create Site”

Connect a Client

Using Newt:

On your client machine (the one you want to expose services from):

# Download Newt (change architecture if needed)
wget -O newt "https://github.com/fosrl/newt/releases/latest/download/newt_linux_amd64"
chmod +x ./newt

# Run Newt with the credentials copied from the Pangolin UI
./newt \
--id YOUR_ID \
--secret YOUR_SECRET \
--endpoint https://your-domain.com

Create a Resource

  1. Go to the “Resources” tab and click “Add Resource”
  2. Give your resource a name
  3. Choose a subdomain for this resource
  4. Select the site you created earlier
  5. Click “Create Resource”

Configure Resource

  1. On the “Connectivity” page:

    • Keep “Enable SSL” enabled for HTTPS
    • Add a target (e.g., http://192.168.1.100:8080)
    • Click “Add Target” and “Save Changes”

  2. On the “Authentication” page:

    • Choose your preferred authentication method
    • Configure accordingly
    • Save changes

8. Advanced Configuration (Optional)

Edit Configuration File

cd ~/pangolin
sudo vim config/config.yml

Refer to the Configuration documentation for all available options.

Set Up Wildcard Certificates

For better performance with multiple subdomains, consider setting up wildcard certificates:

  1. Edit the Traefik configuration:
sudo vim config/traefik/traefik_config.yml

  1. Update the certificatesResolvers section to use DNS challenge instead of HTTP challenge

  2. Set prefer_wildcard_cert: true in your Pangolin configuration

9. Troubleshooting

Container Issues

If containers aren’t starting:

# Check logs
docker compose logs

# Restart containers
docker compose down
docker compose up -d

Certificate Issues

If Let’s Encrypt certificates aren’t being generated:

  1. Check that ports 80 and 443 are open in your AWS security group
  2. Verify your DNS settings are pointing to your Elastic IP
  3. Check Traefik logs:
docker compose logs traefik

Connection Issues

If clients can’t connect to your Pangolin server:

  1. Verify port 51820 (UDP) is open in your AWS security group
  2. Check Gerbil logs:
docker compose logs gerbil

10. Maintenance

Backing Up Data

# Stop containers
cd ~/pangolin
docker compose down

# Backup config directory
sudo tar -czvf pangolin-backup-$(date +%Y%m%d).tar.gz config/

# Restart containers
docker compose up -d

Updating Pangolin

cd ~/pangolin
# Stop the stack
docker compose down

# Update the docker-compose.yml file with new version numbers
# Edit versions in docker-compose.yml:
# - pangolin:VERSION
# - gerbil:VERSION

# Pull the latest images
docker compose pull

# Start the stack
docker compose up -d

Conclusion

You now have a fully functional Pangolin deployment on AlmaLinux in AWS!

For more information and advanced features, refer to the official Pangolin documentation.