Configuración del agente

El agente se configura exclusivamente mediante variables de entorno. No necesitas ficheros de configuración adicionales: las rutas y los parámetros del túnel los obtiene automáticamente del panel de Nubulus.

Variables de entorno

Variable	Obligatoria	Por defecto	Descripción
TUNNEL_TOKEN	Sí	—	Token de autenticación del túnel. Lo obtienes en el panel de Nubulus.
LOG_LEVEL	No	info	Nivel de log: debug, info, warn, error.
POLL_INTERVAL	No	30	Segundos entre comprobaciones de cambios en las rutas.
HEALTH_CHECK_INTERVAL	No	60	Segundos entre comprobaciones del estado del túnel.
API_URL	No	URL de producción	Solo para entornos de prueba o instalaciones on-premise.

Ejemplos de docker-compose

Mínimo

El setup más simple posible:

services:
  nubulus-tunnel:
    image: ghcr.io/nubulusnetwork/tunnel-agent:latest
    container_name: nubulus-tunnel
    environment:
      TUNNEL_TOKEN: "tun_xxxxxxxxxxxxxxxxxxxxxxxxx"
    restart: unless-stopped
    networks:
      - tunnel-network

networks:
  tunnel-network:
    driver: bridge

---

Con un servicio web

Nginx sirviendo contenido estático en el mismo compose:

services:
  web:
    image: nginx:alpine
    networks:
      - tunnel-network

  nubulus-tunnel:
    image: ghcr.io/nubulusnetwork/tunnel-agent:latest
    container_name: nubulus-tunnel
    environment:
      TUNNEL_TOKEN: "tun_xxxxxxxxxxxxxxxxxxxxxxxxx"
    restart: unless-stopped
    networks:
      - tunnel-network
    depends_on:
      - web

networks:
  tunnel-network:
    driver: bridge

Ruta a configurar en el panel:

Tipo	Hostname	Path	Upstream host	Upstream port
host	mi-dominio.com	/	web	80

---

Frontend + API (Node.js + Express)

services:
  frontend:
    image: mi-frontend:latest
    networks:
      - tunnel-network

  api:
    image: mi-api:latest
    networks:
      - tunnel-network

  nubulus-tunnel:
    image: ghcr.io/nubulusnetwork/tunnel-agent:latest
    container_name: nubulus-tunnel
    environment:
      TUNNEL_TOKEN: "tun_xxxxxxxxxxxxxxxxxxxxxxxxx"
    restart: unless-stopped
    networks:
      - tunnel-network
    depends_on:
      - frontend
      - api

networks:
  tunnel-network:
    driver: bridge

Rutas a configurar en el panel:

Tipo	Hostname	Path	Upstream host	Upstream port	Strip prefix
path	mi-dominio.com	/api	api	3000	Sí
host	mi-dominio.com	/	frontend	80	No

---

Servicio existente (red externa)

Si tu servicio ya corre en otra red de Docker Compose, conéctala al túnel:

services:
  nubulus-tunnel:
    image: ghcr.io/nubulusnetwork/tunnel-agent:latest
    container_name: nubulus-tunnel
    environment:
      TUNNEL_TOKEN: "tun_xxxxxxxxxxxxxxxxxxxxxxxxx"
    restart: unless-stopped
    networks:
      - tunnel-network
      - mi-red-existente   # red donde ya corre tu servicio

networks:
  tunnel-network:
    driver: bridge
  mi-red-existente:
    external: true

Ruta en el panel apuntando al nombre del contenedor de tu servicio existente.

---

Con logs en modo debug

Útil para diagnosticar problemas de conexión o de routing:

services:
  nubulus-tunnel:
    image: ghcr.io/nubulusnetwork/tunnel-agent:latest
    container_name: nubulus-tunnel
    environment:
      TUNNEL_TOKEN: "tun_xxxxxxxxxxxxxxxxxxxxxxxxx"
      LOG_LEVEL: "debug"
    restart: unless-stopped
    networks:
      - tunnel-network

networks:
  tunnel-network:
    driver: bridge

Notas importantes

El token es secreto. No lo subas a un repositorio público. Usa un fichero .env o los secretos de tu plataforma de despliegue:

.env

TUNNEL_TOKEN=tun_xxxxxxxxxxxxxxxxxxxxxxxxx

docker-compose.yml

environment:
  TUNNEL_TOKEN: "${TUNNEL_TOKEN}"

El agente no necesita privilegios. No añadas privileged: true ni cap_add. Funcionará sin ellos.

El servicio y el agente deben compartir red Docker. Es la única forma de que el agente pueda alcanzar tu servicio por nombre de contenedor.