Pangolin en VPS: exponer un servicio detrás de NAT sin puertos

El problema: exponer un servicio detrás de NAT

Lo que Pangolin aporta frente a las alternativas

• Completamente self-hosted — tu tráfico solo transita por tu VPS, ningún tercero ve tu tráfico de aplicación.
• Sin puerto entrante necesario — la conexión se inicia desde la máquina origen hacia el VPS (saliente), el NAT nunca es un obstáculo.
• HTTPS automático via Let's Encrypt — Pangolin gestiona certificados para cada subdominio expuesto, sin intervención manual.
• Interfaz web integrada — añade túneles y gestiona recursos y usuarios desde un panel web, sin editar archivos de configuración.
• Cifrado WireGuard de extremo a extremo — el túnel entre la máquina origen y el VPS está cifrado a nivel de transporte, independientemente del HTTPS de aplicación.
• Multi-sitio — una única instancia de Pangolin en el VPS puede relayar decenas de servicios desde máquinas distintas, bajo subdominios independientes.

Arquitectura: VPS relay, Gerbil y Newt

[Máquina origen]                   [VPS ServOrbit]               [Internet]
  service:8080                      Pangolin (orquestación)
  newt (cliente) ←─WireGuard UDP─→  Gerbil  (túnel WG)    ←─HTTPS──→  visitante
                                    Traefik (reverse proxy)

Requisitos previos

Despliegue de Pangolin y Gerbil en el VPS

1. 01

   Preparar el VPS y abrir el puerto WireGuard

   Conéctate como root al VPS e instala Docker si no está presente:

   apt update && apt install -y docker.io docker-compose-plugin ufw

   Abre el puerto UDP para WireGuard (51820 por defecto) y asegura que los puertos HTTP/HTTPS son accesibles:

   ufw allow 80/tcp
   ufw allow 443/tcp
   ufw allow 51820/udp
   ufw enable

   Para restringir el acceso al panel de administración (puerto 3000 por defecto), limítalo a tu IP:

   ufw allow from TU_IP to any port 3000

2. 02

   Crear el archivo docker-compose.yml

   Crea un directorio de trabajo y el archivo de configuración:

   mkdir -p /opt/pangolin && cd /opt/pangolin

   Crea docker-compose.yml con el siguiente contenido:

   cat > docker-compose.yml <<'EOF'
   services:
     pangolin:
       image: fosrl/pangolin:1.23.0
       container_name: pangolin
       restart: unless-stopped
       volumes:
         - ./config:/app/config
         - ./data:/app/data
       ports:
         - "3000:3000"
       networks:
         - pangolin_net
   
     gerbil:
       image: fosrl/gerbil:latest
       container_name: gerbil
       restart: unless-stopped
       cap_add:
         - NET_ADMIN
       volumes:
         - ./data:/var/lib/gerbil
       ports:
         - "51820:51820/udp"
       networks:
         - pangolin_net
       depends_on:
         - pangolin
   
   networks:
     pangolin_net:
       driver: bridge
   EOF

   Adapta el número de versión de la imagen pangolin al último release disponible en GitHub.

3. 03

   Configurar Pangolin e iniciar el stack

   Crea el directorio de configuración y un config.yml mínimo:

   mkdir -p /opt/pangolin/config
   cat > /opt/pangolin/config/config.yml <<'EOF'
   app:
     base_domain: yourdomain.com
     admin_email: [email protected]
     port: 3000
   
   wireguard:
     port: 51820
     subnet: 10.0.0.0/24
   
   acme:
     enabled: true
     staging: false
   EOF

   Reemplaza yourdomain.com por tu dominio real. Inicia el stack:

   cd /opt/pangolin && docker compose up -d
   docker compose logs -f pangolin

   Pangolin genera una contraseña de administrador en el primer arranque — anótala desde los logs. La interfaz web está disponible en http://IP_VPS:3000.

4. 04

   Configurar el registro DNS wildcard

   En tu zona DNS, crea un registro A wildcard apuntando a la IP del VPS:

   *.yourdomain.com  →  A  →  IP_VPS

   En Cloudflare, crea este registro con el proxy desactivado (DNS-only, nube gris) para que los certificados Let's Encrypt puedan emitirse correctamente mediante el desafío HTTP-01 que usa Pangolin.

5. 05

   Crear una unidad systemd para reinicio automático

   Docker con restart: unless-stopped suele ser suficiente, pero si prefieres una unidad systemd dedicada:

   cat > /etc/systemd/system/pangolin.service <<'EOF'
   [Unit]
   Description=Pangolin reverse tunnel stack
   After=docker.service
   Requires=docker.service
   
   [Service]
   Type=oneshot
   RemainAfterExit=yes
   WorkingDirectory=/opt/pangolin
   ExecStart=/usr/bin/docker compose up -d
   ExecStop=/usr/bin/docker compose down
   
   [Install]
   WantedBy=multi-user.target
   EOF
   
   systemctl daemon-reload
   systemctl enable pangolin

Añadir un túnel con Newt en la máquina origen

1. 06

   Crear un túnel en la interfaz Pangolin

   Inicia sesión en la interfaz web de Pangolin en http://IP_VPS:3000 con las credenciales de administrador. Ve a Sites → Add site, dale un nombre (p. ej. homelab) y anota el site token generado. Luego en Resources → Add resource, elige el sitio, escribe el subdominio deseado (nextcloud.yourdomain.com) y el puerto local de la máquina origen (p. ej. 8080).

2. 07

   Instalar Newt en la máquina origen

   En la máquina que aloja tu servicio, descarga el binario Newt para tu arquitectura:

   # Linux x86_64
   curl -Lo /usr/local/bin/newt \
     https://github.com/fosrl/newt/releases/latest/download/newt-linux-amd64
   chmod +x /usr/local/bin/newt

   Para Raspberry Pi (ARM64):

   curl -Lo /usr/local/bin/newt \
     https://github.com/fosrl/newt/releases/latest/download/newt-linux-arm64
   chmod +x /usr/local/bin/newt

3. 08

   Configurar e iniciar Newt

   Lanza Newt con el site token obtenido en el paso anterior:

   newt \
     --server https://yourdomain.com:3000 \
     --token TU_SITE_TOKEN \
     --target localhost:8080

   Para arranque automático, crea una unidad systemd:

   cat > /etc/systemd/system/newt.service <<'EOF'
   [Unit]
   Description=Newt WireGuard tunnel client
   After=network.target
   
   [Service]
   ExecStart=/usr/local/bin/newt \
     --server https://yourdomain.com:3000 \
     --token TU_SITE_TOKEN \
     --target localhost:8080
   Restart=always
   RestartSec=5
   
   [Install]
   WantedBy=multi-user.target
   EOF
   
   systemctl daemon-reload
   systemctl enable --now newt

4. 09

   Verificar la conectividad de extremo a extremo

   En el VPS, verifica que el túnel WireGuard está establecido:

   docker exec gerbil wg show

   Deberías ver un peer con un latest handshake reciente. Desde cualquier navegador o línea de comandos:

   curl -I https://nextcloud.yourdomain.com

   Respuesta esperada: HTTP/2 200 (o la página de login de tu servicio). El certificado Let's Encrypt se emite automáticamente en el primer acceso.

Exposición de un servicio: ejemplo Nextcloud detrás de NAT

1. 10

   Configurar Nextcloud para aceptar el dominio proxy

   Nextcloud bloquea peticiones de dominios no declarados. Añade el dominio público a config.php:

   # Desde la máquina origen, en el directorio de Nextcloud
   nano config/config.php

   Añade en el array trusted_domains:

   'trusted_domains' =>
     array (
       0 => 'localhost',
       1 => 'nextcloud.yourdomain.com',
     ),
   'overwritehost' => 'nextcloud.yourdomain.com',
   'overwriteprotocol' => 'https',

2. 11

   Verificar el acceso público y el certificado

   Espera 30-60 segundos tras el primer acceso para que Let's Encrypt emita el certificado, luego:

   curl -v https://nextcloud.yourdomain.com 2>&1 | grep -E 'subject|issuer|HTTP'

   El certificado está firmado por Let's Encrypt y la URL pública es ahora accesible desde cualquier red, sin ningún puerto abierto en el lado de la red local.

Solución de problemas

Pangolin vs Cloudflare Tunnel vs Tailscale/Headscale

Desplace la tabla

Ir más allá