Instalación
De cero a un nodo en marcha con un solo comando
Docker Compose es la vía recomendada: un comando inicia el plano de control, el agente integrado y PostgreSQL. La instalación por script sigue disponible para hosts con systemd.
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bashGenerador de comandos
Compón tu comando de instalación
Docker Compose está preseleccionado: un comando, base de datos incluida. Los campos ya traen los valores por defecto; cambia solo lo necesario. El script sigue en la segunda pestaña.
Docker Compose
Despliega con Docker Compose
Docker Compose es la vía recomendada: un comando inicia el plano de control, su agente integrado y PostgreSQL, con datos y certificados en volúmenes. Actualizar solo cambia la etiqueta de la imagen.
- Docker Engine 24+ con el plugin Compose v2 (docker compose, no el binario antiguo docker-compose).
- Puertos 80, 443, 9080 y 9090 libres en el host — o cámbialos en los campos de abajo.
- No hace falta una base de datos externa: el archivo compose incluye su propio contenedor PostgreSQL 16 con volúmenes con nombre.
- El panel sirve HTTPS con un certificado autofirmado en el primer arranque. Sube uno real en Ajustes → Control plane HTTPS, o pon TLS_ENABLED=false para HTTP plano.
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash
Ejecútalo en un directorio vacío: el instalador descarga docker-compose.yml, escribe un .env privado, descarga la imagen e inicia el stack. Un .env existente nunca se sobrescribe: vuelve a ejecutar el mismo comando para actualizar.
- 1
Ejecuta el comando
Ejecuta el comando anterior en un directorio vacío. El instalador crea ./pingwaf, descarga el compose y escribe un .env privado.
- 2
Espera al stack
Compose descarga la imagen, inicia PostgreSQL, espera su health check y arranca PingWAF. El primer arranque tarda uno o dos minutos.
- 3
Inicia sesión
Abre https://<host>:9080 y usa ADMIN_EMAIL / ADMIN_PASSWORD (la contraseña por defecto debe cambiarse al entrar). Después añade un sitio.
¿Necesitas personalizar? Genera un comando con opciones
Cambia solo lo necesario; el comando añade únicamente las opciones que difieren de los valores por defecto. La contraseña del administrador nunca se escribe en el comando.
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash
Primer inicio de sesión: https://<tu-host>:9080 con el ADMIN_EMAIL / ADMIN_PASSWORD de arriba (acepta el aviso del certificado autofirmado hasta que subas uno real). Los agentes alcanzan el plano de control en :9090.
Actualización
Descarga la imagen de la etiqueta de tu .env y recrea el contenedor con los mismos volúmenes — configuración, datos y certificados sobreviven al reinicio. Fija la etiqueta cuando quieras actualizaciones controladas.
docker compose pull && docker compose up -d
Prefillado con los valores por defecto del instalador — solo los valores que cambies se añaden al comando.
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash
La clave API aparece en texto plano en el comando y puede acabar en el historial del shell. Prefiere exportar PINGWAF_API_KEY, o ejecuta el instalador de forma interactiva y pega la clave cuando la pida.
Solo los valores distintos de los predeterminados se añaden como flags, por lo que el generador intacto produce la línea más corta. Los argumentos llegan al script canalizado mediante bash -s --.
Instalación interactiva
O deja que el instalador pregunte
Ejecuta el script en una terminal sin flags y te guiará por el modo, las credenciales, la base de datos y los nombres de certificado; al final imprime el plan resuelto para confirmar.
-
Elige el modo de despliegue
1 all-in-one, 2 server o 3 agent — pulsa Enter para aceptar el valor por defecto entre corchetes.
-
Rellena los parámetros
Los agentes preguntan por la URL del plano de control y la clave de alta; los modos server preguntan por la cuenta de administrador, la URL de PostgreSQL y los nombres de certificado. Los secretos no se muestran al escribirlos.
-
Confirma el resumen
Antes de escribir nada, el instalador imprime el plan resuelto — modo, versión, plataforma, rutas, estado de systemd y la URL de base de datos enmascarada.
-
Termina y verifica
Los modos server imprimen el comando de arranque; los agentes se habilitan y arrancan automáticamente. Confirma el nodo en Nodes del panel.
Referencia de flags
Los flags del instalador de un vistazo
Todos los flags que acepta install.sh. Cada uno tiene su equivalente en la variable de entorno PINGWAF_*.
--mode Modo de operación: all-in-one, server o agent. Por defecto all-in-one.
--version Instala una versión concreta (se elimina la v inicial). Vacío o 'latest' resuelve la última publicación de GitHub.
--db-url Cadena de conexión de PostgreSQL para server/all-in-one. Por defecto postgres://pingwaf:pingwaf@localhost:5432/pingwaf.
--server-url URL gRPC del plano de control para el modo agent. Usa https:// — gRPC se sirve con TLS por defecto.
--api-key Token de alta del agente. También puede pasarse como PINGWAF_API_KEY para no dejarlo en la línea de comandos.
--admin-email Correo del administrador sembrado (server/all-in-one). Por defecto admin@pingwaf.local.
--admin-password Contraseña del administrador sembrado (server/all-in-one). Vacío conserva pingwaf123, que el panel obliga a cambiar en el primer inicio de sesión.
--tls-sans Nombres de host separados por comas que debe cubrir el certificado generado del panel.
--no-systemd No crear la unidad de systemd — para contenedores, actualizaciones o gestores de procesos propios.
--interactive / --non-interactive Fuerza las preguntas aunque se hayan pasado flags, o nunca pregunta y usa los valores dados más los por defecto. Canalizarlo sin flags sigue siendo no interactivo.
--dry-run Imprime el plan resuelto — modo, versión, plataforma, rutas — y sale sin instalar.
Solución de problemas
Cuando la instalación no termina limpia
Los cinco fallos más frecuentes en soporte y el comando que identifica cada uno.
El instalador no puede conectar con PostgreSQL
Los modos all-in-one y server necesitan PostgreSQL 14+ antes del primer arranque. El script avisa cuando psql no puede conectar — instala el servidor, crea el usuario y la base de datos pingwaf (createuser / createdb), vuelve a ejecutar el instalador o edita /etc/pingwaf/pingwaf.toml y ejecuta systemctl restart pingwaf.
bind() failed en 0.0.0.0:80 o :443
El plano de datos enlaza 80/443 como el usuario sin privilegios pingwaf, lo que solo funciona porque la unidad otorga CAP_NET_BIND_SERVICE. Si el enlace sigue fallando, comprueba systemctl show pingwaf -p AmbientCapabilities y añade la capacidad con un drop-in: sudo systemctl edit pingwaf → [Service] AmbientCapabilities=CAP_NET_BIND_SERVICE. Las unidades escritas antes de otorgar la capacidad siguen fallando hasta añadir el drop-in.
El binario falla con un error de símbolo glibc con versión
Los artefactos de publicación se compilan en Ubuntu 24.04 y necesitan glibc 2.39 o superior. En distribuciones más antiguas (Debian 11, Ubuntu 20.04, CentOS/RHEL, Alpine, …) la prueba de humo del instalador se detiene con un mensaje claro — compila desde el código fuente en su lugar.
El servicio de systemd no arranca
Inspecciona el registro de la unidad con journalctl -u pingwaf -e y revisa /etc/pingwaf/pingwaf.toml. No hay recarga: aplica cualquier cambio con systemctl restart pingwaf y comprueba después con systemctl status pingwaf.
El contenedor no arranca con "bind() failed on 0.0.0.0:443" / Permission denied
La imagen ya otorga CAP_NET_BIND_SERVICE al binario en tiempo de compilación, por lo que el usuario sin privilegios pingwaf puede enlazar 80/443 en modo puente con un simple docker run o docker compose up -d. Si sigue fallando, el runtime eliminó las capacidades de archivo — añade --cap-add=NET_BIND_SERVICE (el archivo compose incluido ya define cap_add) o cambia a red host network_mode: host (en ese caso comenta ports: y networks:; 9080/9090 escucharán directamente en el host). Verifica con docker exec pingwaf getcap /usr/local/bin/pingwaf (debe mostrar cap_net_bind_service=ep) y docker exec pingwaf id -u (distinto de cero). Detalles completos: https://github.com/shuaiZend/PingWAF/blob/main/docs/deployment.md#binding-ports-80443-in-containers
¿Instalado? Ahora añade tu primer sitio.
La documentación cubre el modelo de sitios, las topologías distribuidas, la precedencia de configuración y la referencia completa de variables de entorno.