Primeros pasos

Guía de despliegue

De cero a un panel de administración de WireGuard VPN funcionando en menos de cinco minutos.

Requisitos previos

Un servidor Linux accesible desde donde vayas a administrarlo
Docker y Docker Compose instalados
Un nombre de dominio apuntando a la IP de tu servidor
Los puertos 80 y 443 abiertos para Caddy, y el puerto UDP de WireGuard abierto (por defecto 51820)

Caddy necesita un nombre DNS válido, interno o público, apuntando a tu servidor para poder obtener y renovar automáticamente los certificados SSL.

Despliegue

mkdir wireguard_webadmin && cd wireguard_webadmin

wget -O docker-compose.yml \
  https://raw.githubusercontent.com/eduardogsilva/wireguard_webadmin/main/docker-compose-caddy.yml

Crea un archivo .env en el mismo directorio. Define SERVER_ADDRESS con tu dominio:

SERVER_ADDRESS=vpn.example.com
DEBUG_MODE=False
TIMEZONE=America/Sao_Paulo

Consulta la referencia de .env más abajo para ver todas las variables disponibles.

docker compose up -d

Accede al panel en https://vpn.example.com. Caddy obtiene y renueva automáticamente los certificados SSL.

Referencia de .env

Variable	Obligatoria	Descripción
SERVER_ADDRESS	Sí	Nombre DNS o IP de tu servidor. Debe coincidir exactamente con lo que escribes en el navegador; si no, aparecerán errores de CSRF.
DEBUG_MODE	No	Define `True` para activar el modo debug de Django. Nunca lo uses en producción. Valor por defecto: `False`.
TIMEZONE	No	Zona horaria de la aplicación. Usa un valor de la base de datos tz. Valor por defecto: `America/Sao_Paulo`.
EXTRA_ALLOWED_HOSTS	No	Nombres de host adicionales que Django debe aceptar, separados por comas. `SERVER_ADDRESS` siempre se incluye. Ejemplo: `app1.example.com,app2.example.com:8443`.
WIREGUARD_STATUS_CACHE_ENABLED	No	Almacena en caché el estado de WireGuard para reducir las llamadas a `wg`. Valor por defecto: `True`.
WIREGUARD_STATUS_CACHE_REFRESH_INTERVAL	No	Frecuencia de actualización de la caché, en segundos. Valores permitidos: `30`, `60`, `150`, `300`. Valor por defecto: `60`.
WIREGUARD_STATUS_CACHE_WEB_LOAD_PREVIOUS_COUNT	No	Cuántas instantáneas en caché precargar al abrir la página (0-9). Los valores altos rellenan antes los gráficos de tráfico. Redúcelo si la lista de peers se siente lenta. Valor por defecto: `9`.

Actualización

Los datos se conservan en volúmenes de Docker. Actualizar no afecta a tus peers, reglas de firewall, entradas DNS ni ninguna otra configuración.

Ir al directorio del proyecto

cd wireguard_webadmin

Detener los servicios y descargar las imágenes más recientes

docker compose down
docker compose pull

Hacer una copia de seguridad de tus datos

tar cvfz wireguard-webadmin-backup-$(date +%Y-%m-%d-%H%M%S).tar.gz \
  /var/lib/docker/volumes/wireguard_webadmin_wireguard/_data/ \
  /var/lib/docker/volumes/wireguard_webadmin_rrd_data/_data/

Actualizar el archivo compose

wget -O docker-compose.yml \
  https://raw.githubusercontent.com/eduardogsilva/wireguard_webadmin/main/docker-compose-caddy.yml

Levantar el stack actualizado

docker compose up -d

Revisar los logs por si hay errores inesperados

docker compose logs wireguard_webadmin

Solución de problemas

Caddy no obtiene un certificado

Confirma que el registro A de tu dominio apunta a la IP pública del servidor
Verifica que los puertos 80 y 443 estén abiertos y no bloqueados aguas arriba
Revisa los logs de Caddy: docker compose logs caddy

El panel no carga

Comprueba que todos los contenedores estén en ejecución: docker compose ps
Busca errores: docker compose logs wireguard_webadmin
Verifica que SERVER_ADDRESS en .env coincida exactamente con lo que escribes en el navegador

Errores CSRF al iniciar sesión

SERVER_ADDRESS está mal configurado. Debe coincidir con el nombre de host, y con el puerto si no es estándar, usado para acceder al panel. Actualiza .env y reinicia con docker compose up -d.

Los peers de WireGuard no pueden conectarse

Confirma que el puerto UDP de WireGuard esté abierto en el firewall del host. El valor por defecto es 51820, pero si ejecutas varias instancias cada una necesita su propio puerto.
Asegúrate de que el rango de puertos UDP declarado en docker-compose.yml coincida con lo configurado en cada instancia de WireGuard dentro del panel. Si no coincide, el contenedor no expondrá el puerto correcto en el host.
Verifica que el reenvío de IP esté habilitado en el host: sysctl net.ipv4.ip_forward

Qué está en ejecución

Servicio	Rol
wireguard-webadmin	Aplicación Django: interfaz web y API
caddy	Proxy inverso y TLS automático
auth-gateway	Capa de autorización Zero Trust: aplica verificaciones de identidad antes de enviar la solicitud al upstream
cron	Tareas programadas: activación/desactivación de peers y actualización de caché
rrdtool	Historial de tráfico: recolección de datos RRD y generación de gráficos
dns	Resolvedor basado en dnsmasq con soporte para listas de bloqueo por categorías