Desplegar sus aplicaciones con Coolify en un VPS

Un PaaS gestionado como Heroku o Render resulta perfecto para un prototipo o un proyecto de tamaño modesto. En cuanto aloja varias aplicaciones, o el tráfico crece, la factura sube en proporción — a veces por encima del coste de un VPS dedicado. Coolify se dirige a tres perfiles concretos. Las agencias web que gestionan decenas de proyectos de clientes: un solo VPS con Coolify sustituye a otras tantas cuentas de Heroku. Los profesionales independientes que desean controlar sus costes de infraestructura sin sacrificar la comodidad del despliegue automático. Los equipos que no pueden confiar sus datos a un tercero — RGPD, clientes del sector público, datos médicos o financieros. En los tres casos, Coolify reproduce el flujo de trabajo PaaS (git push → despliegue) sobre una infraestructura que usted controla por completo.

Coolify en sí consume pocos recursos, pero orquesta Docker y puede alojar sus aplicaciones y bases de datos en el mismo servidor. Prevea como mínimo 2 vCPU y 2 GB de RAM para Coolify solo. En cuanto ejecute varios servicios simultáneamente, 4 GB de RAM pasa a ser el mínimo recomendado. El espacio en disco depende de sus aplicaciones: cuente 20 GB para el sistema y Coolify, más el espacio de sus imágenes Docker y de sus datos.

Sistema operativo: Ubuntu 22.04 LTS o Debian 12 en un servidor recién aprovisionado. No instale Docker manualmente de antemano — el script de instalación de Coolify se encarga de esta etapa y una versión de Docker preinstalada puede crear conflictos.

Puertos que abrir en su cortafuegos: 22 (SSH), 80 (HTTP), 443 (HTTPS) y 8000 (interfaz de instalación inicial de Coolify). Puede cerrar el puerto 8000 después de configurar un dominio y pasar a HTTPS. Se necesita un nombre de dominio o un subdominio para la interfaz de Coolify y para cada aplicación que despliegue.

Una vez desplegada la primera aplicación, varios ajustes mejoran la fiabilidad del día a día.

Webhooks Git automáticos. La integración GitHub App o GitLab OAuth crea los webhooks en cada repositorio en el momento en que configura el recurso. Si utiliza una clave de despliegue SSH manual, cree el webhook del lado de Git apuntando a https://coolify.votre-domaine.com/api/v1/deploy?uuid=<uuid-application>&secret=<secret>. El UUID y el secreto son visibles en la pestaña Webhooks de cada recurso.

Variables de entorno y secretos. Coolify distingue las variables visibles en la interfaz (variables de entorno clásicas) de los secretos ocultos (tokens, claves de API). Ambos se cifran en la base de datos. Puede definir variables a nivel de proyecto — las heredan todos los recursos — o por recurso individual.

Monitorización integrada. La pestaña Métricas de cada servidor muestra CPU, RAM y disco en tiempo real. Puede configurar notificaciones (correo electrónico, Telegram, Slack, Discord, ntfy) para los eventos de despliegue, los errores y las alertas de recursos.

Actualizaciones de Coolify. Las actualizaciones se lanzan desde la interfaz (Ajustes > Actualizar). Coolify descarga la nueva versión de sus imágenes Docker, recrea sus propios contenedores y se reinicia. La actualización no afecta a sus aplicaciones desplegadas.

La compilación falla con No build method detected. Nixpacks no ha reconocido el stack. Añada un archivo Dockerfile en la raíz del repositorio o seleccione manualmente el método de compilación en los ajustes de la aplicación (Docker Compose si dispone de uno). También puede forzar el stack Nixpacks añadiendo un archivo nixpacks.toml en la raíz.

El dominio muestra 502 Bad Gateway después del despliegue. La aplicación no escucha en el puerto que espera Traefik. Compruebe el puerto de exposición en los ajustes del recurso: debe corresponder al puerto en el que su aplicación escucha dentro del contenedor. Para una aplicación Node.js que arranca en el puerto 3000, indique 3000 en el campo «Puerto».

El certificado SSL no se genera y el acceso sigue en HTTP. Compruebe que el registro DNS A apunta correctamente a la IP del VPS (la propagación a veces es lenta). Compruebe que el puerto 80 está abierto en UFW — Let's Encrypt en modo HTTP Challenge debe poder alcanzar el servidor en ese puerto. Si está detrás de Cloudflare en modo proxy, pase a DNS Challenge.

La aplicación se reinicia en bucle (Restarting). El comando de arranque falla. Consulte los registros del contenedor en la pestaña Logs del recurso. El error suele ser una variable de entorno que falta, una conexión imposible a la base de datos (compruebe la cadena de conexión) o un puerto ya ocupado en el servidor.

Recursos insuficientes: la compilación muere (Killed). La memoria del VPS es insuficiente durante la compilación. Dos opciones: añadir memoria swap temporalmente (fallocate -l 2G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile) o migrar a un VPS con más RAM. Para las aplicaciones Node.js voluminosas, añada NODE_OPTIONS=--max-old-space-size=4096 en las variables de entorno de compilación.

Las bases de datos se respaldan desde la pestaña Backups del recurso: se elige una frecuencia (expresión cron) y una retención. Según la documentación de Coolify, cada copia se escribe primero en el servidor que aloja la base, en /data/coolify/backups. Después se puede enviar una copia a un almacenamiento compatible con S3, una vez añadido y validado en Coolify; la retención local y la retención en S3 se configuran por separado. La documentación enumera, entre otros, Amazon S3, Cloudflare R2, MinIO, Backblaze B2, Scaleway, Hetzner, Wasabi y DigitalOcean Spaces, e indica que otros proveedores compatibles con S3 pueden funcionar.

Una copia solo local no es una copia de seguridad. Un archivo en el disco del VPS desaparece con el VPS: sin un destino S3 (o sin una copia que usted mueva por su cuenta) solo tiene un punto de restauración frente a un error de manejo, no frente a la pérdida del servidor.

El destino es S3 y nada más. La petición de un gestor de copias más completo (SFTP, WebDAV, cifrado de las copias enviadas, carpeta y subcarpeta en el bucket, borrado remoto, descarga) se sigue en la issue n.º 2389 de coollabsio/coolify. En el momento de redactar este artículo, esa issue está abierta y asignada a un miembro del equipo, sin entrega anunciada: no base su plan de recuperación en esas funciones. Si necesita SFTP o cifrado, prevea un segundo mecanismo fuera de Coolify, por ejemplo rsync o una herramienta de copias cifradas que lea /data/coolify/backups y lo envíe al exterior.

La página de documentación de las copias de bases de datos no trata la copia de la propia instancia de Coolify. Por eso el paso 10 anterior sigue siendo útil: copie /data/coolify fuera del VPS.

Pruebe la restauración. Coolify lo dice por sí mismo: una copia correcta solo demuestra que se creó un archivo. Restáurela en una base desechable y compruebe los datos antes de fiarse de ella.

Síntoma: detrás de Traefik o Caddy (el proxy de Coolify), su aplicación recibe a veces, en X-Forwarded-For, una dirección interna de Docker (del tipo 172.18.0.1) en lugar de la IP del visitante. Consecuencias concretas: limitación de tasa y bloqueos por IP que apuntan al propio proxy, registros inutilizables, geolocalización errónea.

Lo que dice la fuente primaria (issue n.º 3436 de coollabsio/coolify, «Randomly receiving proxy IP as X-Forwarded-For header using Traefik or Caddy»): en el momento de redactar este artículo, la issue está abierta, etiquetada «Possible Bug», y no se confirma en ella ninguna corrección fusionada. Varios usuarios describen el mismo comportamiento, y quien la abrió precisa que el problema no está resuelto a nivel de Coolify. La solución alternativa que se repite en el hilo: los visitantes en IPv6 aparecen con una dirección interna de Docker cuando la red Docker coolify (la del proxy) no tiene IPv6 activado. Activar IPv6 en esa red, recrearla y volver a desplegar las aplicaciones resolvió el caso a varios participantes; cambiar solo daemon.json y reiniciar no bastó a uno de ellos. Un participante también observó que esa red se crea solo en IPv4 en los servidores gestionados de forma remota.

Cómo proceder sin fiarse de una anécdota:

- Compruebe el estado de la red: docker network inspect coolify --format '{{.EnableIPv6}}'. Un false es la pista descrita en el hilo.
- Reproduzca antes de modificar: llame a la aplicación por IPv4 y luego por IPv6 (curl -4 y curl -6) y compare lo que registra la aplicación.
- Recrear la red corta el tráfico durante el nuevo despliegue: hágalo fuera de las horas punta, con una copia de /data/coolify.
- Detrás de Cloudflare en modo proxy, lea la cabecera CF-Connecting-IP en lugar de deducir la IP de X-Forwarded-For, y confíe en estas cabeceras solo si proceden de rangos que usted controla.

Esta guía se ofrece tal cual, sin soporte de Coolify en sí: el estado de esa issue puede haber cambiado desde entonces, vuelva a leerla antes de actuar.

Coolify no es el único PaaS autoalojado disponible. CapRover, Dokploy y Dokku cubren necesidades similares, con filosofías diferentes. Coolify destaca por su interfaz moderna, la compatibilidad nativa con el multiservidor y la monitorización integrada — es adecuado para los equipos que gestionan un parque de servidores desde un único punto de control. CapRover es más ligero y adecuado para un uso monoservidor con un solo administrador. Dokploy es más reciente, orientado a Docker Compose y Kubernetes con una interfaz depurada. Para una comparativa detallada de las tres plataformas según los criterios que importan (recursos, compilación, bases de datos, acceso colaborativo), consulte nuestro artículo comparativo.