Pangolin Deployment and Usage Guide

1. Prerequisites

System Requirements

Node.js: Version 18 or higher
npm or yarn: Package manager
Docker: For containerized deployment (optional but recommended)
SQLite: Built-in database (no external DB required)
WireGuard: Kernel module must be available on the host system

Network Requirements

Open ports: 443 (HTTPS), 51820 (WireGuard UDP)
Domain name for SSL certificates (or use provided .pangolin.net subdomain)
Outbound internet access for fetching dependencies and certificates

Accounts

Pangolin Cloud Account: Optional for managed services at app.pangolin.net
Domain Registrar: For custom domain configuration
DigitalOcean Account: For marketplace deployment (optional)

2. Installation

Quick Install (Recommended)

# Using Docker (simplest method)
docker run -d \
  --name pangolin \
  --restart unless-stopped \
  --cap-add=NET_ADMIN \
  -p 443:443 \
  -p 51820:51820/udp \
  -v pangolin_data:/data \
  -e PANGOLIN_HOSTNAME=your-domain.com \
  fosrl/pangolin:latest

Manual Installation

# Clone the repository
git clone https://github.com/fosrl/pangolin.git
cd pangolin

# Install dependencies
npm install

# Build the project
npm run build

# Initialize database
npm run db:migrate

DigitalOcean Marketplace

For a pre-configured one-click installer:

Visit DigitalOcean Marketplace
Click "Create Pangolin CE Droplet"
Choose your plan and region
Deploy with one click

3. Configuration

Environment Variables

Create a .env file in the project root:

# Required
NODE_ENV=production
PANGOLIN_HOSTNAME=your-domain.com
DATABASE_URL=file:/data/pangolin.db

# Optional
ADMIN_EMAIL=admin@example.com
SESSION_SECRET=your-secure-random-string
WIREGUARD_PRIVATE_KEY=auto-generated-if-empty
TRAEFIK_MONITOR_INTERVAL=300000
LOG_LEVEL=info

Domain Configuration

Pangolin supports multiple domain types:

NS Records: Full domain delegation
CNAME Records: Subdomain delegation
Wildcard Certificates: For multiple subdomains

Configure domains via the admin interface or API:

# Example API call to add a domain
curl -X POST https://your-pangolin-instance/api/domains \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "baseDomain": "your-domain.com",
    "type": "wildcard",
    "certResolver": "letsencrypt"
  }'

SSL/TLS Configuration

Pangolin automatically manages SSL certificates via:

Let's Encrypt for production
Self-signed certificates for development
Custom certificates via Traefik config

4. Build & Run

Development Mode

# Install dependencies
npm install

# Start development server with hot reload
npm run dev

# Run database migrations
npm run db:migrate

# Access the admin interface at http://localhost:3000

Production Build

# Build TypeScript code
npm run build

# Generate production assets
npm run build:client

# Start production server
npm start

# Or use PM2 for process management
npm install -g pm2
pm2 start dist/server.js --name pangolin

Docker Compose (Production)

Create docker-compose.yml:

version: '3.8'
services:
  pangolin:
    image: fosrl/pangolin:latest
    container_name: pangolin
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    ports:
      - "443:443"
      - "51820:51820/udp"
    volumes:
      - pangolin_data:/data
      - ./certs:/certs:ro
    environment:
      - NODE_ENV=production
      - PANGOLIN_HOSTNAME=your-domain.com
      - DATABASE_URL=file:/data/pangolin.db
      - SESSION_SECRET=${SESSION_SECRET}
    networks:
      - pangolin-network

volumes:
  pangolin_data:

networks:
  pangolin-network:
    driver: bridge

Start with:

docker-compose up -d

5. Deployment

Self-Hosted Options

Community Edition (AGPL-3)

Free and open source
All core features included
Self-managed infrastructure

Enterprise Edition

Fossorial Commercial License
Free for: Personal use, hobbyists, businesses earning < $100K USD/year
Additional enterprise features

Deployment Platforms

Virtual Private Server (VPS)

# Ubuntu/Debian example
ssh user@your-server

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Run Pangolin
docker run -d [options as above]

Kubernetes

# Sample deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pangolin
spec:
  replicas: 1
  selector:
    matchLabels:
      app: pangolin
  template:
    metadata:
      labels:
        app: pangolin
    spec:
      containers:
      - name: pangolin
        image: fosrl/pangolin:latest
        ports:
        - containerPort: 443
        - containerPort: 51820
          protocol: UDP
        securityContext:
          capabilities:
            add: ["NET_ADMIN"]
        volumeMounts:
        - name: data
          mountPath: /data
        env:
        - name: NODE_ENV
          value: "production"
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: pangolin-pvc

Pangolin Cloud (Managed)

Sign up at app.pangolin.net
Add payment method for pay-as-you-go pricing
Deploy remote nodes to your infrastructure
Connect to the managed control plane

Reverse Proxy Setup

Pangolin uses Traefik for reverse proxying. Configuration is automatic, but you can customize:

# Custom Traefik config (traefik.yml)
entryPoints:
  web:
    address: ":443"
    http:
      tls:
        certResolver: letsencrypt

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@example.com
      storage: /data/acme.json
      httpChallenge:
        entryPoint: web

6. Troubleshooting

Common Issues

WireGuard Interface Fails to Start

# Check kernel module
lsmod | grep wireguard

# Load module if missing
sudo modprobe wireguard

# For Docker, ensure NET_ADMIN capability
docker run --cap-add=NET_ADMIN ...

SSL Certificate Issues

# Check certificate status
docker exec pangolin cat /data/acme.json | jq .

# Force certificate renewal
docker exec pangolin rm /data/acme.json
docker restart pangolin

# Check domain verification
curl https://your-domain.com/.well-known/acme-challenge/test

Database Migration Errors

# Backup current database
cp /data/pangolin.db /data/pangolin.db.backup

# Run migrations manually
docker exec pangolin npm run db:migrate

# Check database schema
sqlite3 /data/pangolin.db ".schema"

Connection Issues

# Check server logs
docker logs pangolin --tail 100

# Verify ports are open
sudo netstat -tulpn | grep -E '(443|51820)'

# Test WireGuard connectivity
wg show

# Check client associations
curl -H "Authorization: Bearer ADMIN_TOKEN" \
  https://your-domain.com/api/clients

Performance Issues

# Monitor resource usage
docker stats pangolin

# Check Traefik configuration
docker exec pangolin cat /etc/traefik/traefik.yml

# Increase logging for debugging
export LOG_LEVEL=debug
docker restart pangolin

Getting Help

Documentation: docs.pangolin.net
Discord: Join Community
Slack: pangolin.net/slack
GitHub Issues: fosrl/pangolin/issues
Email: contact@pangolin.net

Logs and Monitoring

# View real-time logs
docker logs -f pangolin

# Access audit logs via API
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-domain.com/api/audit-logs

# Check health endpoint
curl https://your-domain.com/health

Remember to regularly backup your /data volume and keep your Pangolin instance updated for security patches and new features.

How to Deploy & Use pangolin