<li>Un servidor Linux accesible desde donde vayas a administrarlo</li>
<li><ahref="https://docs.docker.com/engine/install/">Docker</a> y <ahref="https://docs.docker.com/compose/install/">Docker Compose</a> instalados</li>
<li>Un nombre de dominio apuntando a la IP de tu servidor</li>
<li>Los puertos <strong>80</strong> y <strong>443</strong> abiertos para Caddy, y el puerto UDP de WireGuard abierto (por defecto <strong>51820</strong>)</li>
</ul>
<divclass="callout">
<p><strong>Caddy necesita un nombre DNS válido</strong>, interno o público, apuntando a tu servidor para poder obtener y renovar automáticamente los certificados SSL.</p>
<p>Consulta la <ahref="#env-reference">referencia de .env</a> más abajo para ver todas las variables disponibles.</p>
</div>
<divclass="tab-panel"id="dep-step-4">
<pre><code>docker compose up -d</code></pre>
<p>Accede al panel en <code>https://vpn.example.com</code>. Caddy obtiene y renueva automáticamente los certificados SSL.</p>
</div>
</div>
</div>
<hr>
<h2id="env-reference">Referencia de .env</h2>
<tableclass="env-table">
<thead>
<tr>
<th>Variable</th>
<th>Obligatoria</th>
<th>Descripción</th>
</tr>
</thead>
<tbody>
<tr>
<td>SERVER_ADDRESS</td>
<td>Sí</td>
<td>Nombre DNS o IP de tu servidor. Debe coincidir exactamente con lo que escribes en el navegador; si no, aparecerán errores de CSRF.</td>
</tr>
<tr>
<td>DEBUG_MODE</td>
<td>No</td>
<td>Define <code>True</code> para activar el modo debug de Django. Nunca lo uses en producción. Valor por defecto: <code>False</code>.</td>
</tr>
<tr>
<td>TIMEZONE</td>
<td>No</td>
<td>Zona horaria de la aplicación. Usa un valor de la <ahref="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"target="_blank"rel="noopener">base de datos tz</a>. Valor por defecto: <code>America/Sao_Paulo</code>.</td>
</tr>
<tr>
<td>EXTRA_ALLOWED_HOSTS</td>
<td>No</td>
<td>Nombres de host adicionales que Django debe aceptar, separados por comas. <code>SERVER_ADDRESS</code> siempre se incluye. Ejemplo: <code>app1.example.com,app2.example.com:8443</code>.</td>
</tr>
<tr>
<td>WIREGUARD_STATUS_CACHE_ENABLED</td>
<td>No</td>
<td>Almacena en caché el estado de WireGuard para reducir las llamadas a <code>wg</code>. Valor por defecto: <code>True</code>.</td>
</tr>
<tr>
<td>WIREGUARD_STATUS_CACHE_REFRESH_INTERVAL</td>
<td>No</td>
<td>Frecuencia de actualización de la caché, en segundos. Valores permitidos: <code>30</code>, <code>60</code>, <code>150</code>, <code>300</code>. Valor por defecto: <code>60</code>.</td>
<td>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: <code>9</code>.</td>
</tr>
<tr>
<td>DISABLE_AUTO_APPLY</td>
<td>No</td>
<td>Desactiva la aplicación automática de los cambios de configuración de WireGuard y DNS. Por defecto, los cambios en peers y DNS se aplican de inmediato. Define como <code>true</code> para aplicar los cambios manualmente. Valor por defecto: <code>false</code>.</td>
</tr>
<tr>
<td>WIREGUARD_MTU</td>
<td>No</td>
<td>MTU personalizado para las interfaces WireGuard (servidor y clientes). Cámbialo solo si sabes lo que estás haciendo. Debe ser un entero entre <code>1280</code> y <code>9000</code>. Tras cambiarlo, vuelve a exportar y distribuir todos los archivos de configuración de clientes: una MTU diferente entre servidor y clientes puede causar problemas de conectividad. Valor por defecto: <code>1420</code>.</td>
</tr>
<tr>
<td>VPN_CLIENTS_CAN_ACCESS_DJANGO</td>
<td>No</td>
<td>Permite que los clientes VPN accedan a la interfaz web directamente a través de la interfaz interna en <code>http://ip_o_hostname:8000</code>. Cuando está habilitado, la dirección interna incluido el puerto <code>:8000</code> debe añadirse a <code>EXTRA_ALLOWED_HOSTS</code>, de lo contrario Django bloqueará la solicitud. Valor por defecto: <code>False</code>.</td>
</tr>
</tbody>
</table>
<hr>
<h2id="actualización">Actualización</h2>
<divclass="callout green">
<p><strong>Los datos se conservan en volúmenes de Docker.</strong> Actualizar no afecta a tus peers, reglas de firewall, entradas DNS ni ninguna otra configuración.</p>
</div>
<divclass="deploy-steps">
<divclass="deploy-step-card">
<divclass="deploy-step-num">01</div>
<divclass="deploy-step-body">
<divclass="deploy-step-label">Ir al directorio del proyecto</div>
<pre><code>cd wireguard_webadmin</code></pre>
</div>
</div>
<divclass="deploy-step-card">
<divclass="deploy-step-num">02</div>
<divclass="deploy-step-body">
<divclass="deploy-step-label">Detener los servicios y descargar las imágenes más recientes</div>
<pre><code>docker compose down
docker compose pull</code></pre>
</div>
</div>
<divclass="deploy-step-card">
<divclass="deploy-step-num">03</div>
<divclass="deploy-step-body">
<divclass="deploy-step-label">Hacer una copia de seguridad de tus datos</div>
<li>Verifica que <code>SERVER_ADDRESS</code> en <code>.env</code> coincida exactamente con lo que escribes en el navegador</li>
</ul>
<h3id="errores-csrf-al-iniciar-sesión">Errores CSRF al iniciar sesión</h3>
<p><code>SERVER_ADDRESS</code> 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 <code>.env</code> y reinicia con <code>docker compose up -d</code>.</p>
<h3id="los-peers-de-wireguard-no-pueden-conectarse">Los peers de WireGuard no pueden conectarse</h3>
<ul>
<li>Confirma que el puerto UDP de WireGuard esté abierto en el firewall del host. El valor por defecto es <strong>51820</strong>, pero si ejecutas varias instancias cada una necesita su propio puerto.</li>
<li>Asegúrate de que el rango de puertos UDP declarado en <code>docker-compose.yml</code> 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.</li>
<li>Verifica que el reenvío de IP esté habilitado en el host: <code>sysctl net.ipv4.ip_forward</code></li>
</ul>
<hr>
<h2id="qué-está-en-ejecución">Qué está en ejecución</h2>
<tableclass="env-table">
<thead>
<tr><th>Servicio</th><th>Rol</th></tr>
</thead>
<tbody>
<tr><td>wireguard-webadmin</td><td>Aplicación Django: interfaz web y API</td></tr>
<tr><td>caddy</td><td>Proxy inverso y TLS automático</td></tr>
<tr><td>auth-gateway</td><td>Capa de autorización Zero Trust: aplica verificaciones de identidad antes de enviar la solicitud al upstream</td></tr>
<tr><td>cron</td><td>Tareas programadas: activación/desactivación de peers y actualización de caché</td></tr>
<tr><td>rrdtool</td><td>Historial de tráfico: recolección de datos RRD y generación de gráficos</td></tr>
<tr><td>dns</td><td>Resolvedor basado en dnsmasq con soporte para listas de bloqueo por categorías</td></tr>
