Cómo instalar Coolify en un VPS

Requisitos oficiales

Usa un servidor fresco de 64 bits con acceso SSH. La documentación recomienda al menos 2 núcleos, 2 GB de RAM y espacio libre; suma los recursos de las aplicaciones y de las compilaciones. Ubuntu LTS permite la instalación rápida.

Preparar el VPS

Actualiza el sistema, configura SSH y revisa puertos. Coolify necesita 80 y 443 para aplicaciones; el acceso inicial usa 8000 y algunas funciones 6001/6002. Docker puede eludir reglas simples de UFW, así que prefiere también el firewall del proveedor.

Ejecutar el instalador oficial

Revisa siempre la URL en la documentación de Coolify. El comando vigente es:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

Un script canalizado a bash obtiene privilegios elevados: úsalo solo desde el dominio oficial y, si tu política lo exige, descárgalo e inspecciónalo antes.

Al terminar abre http://IP_DEL_VPS:8000 y crea inmediatamente la primera cuenta administrativa. Si dejas el registro inicial expuesto, otra persona podría reclamar la instancia.

Configurar dominio y DNS

Crea un registro A para un subdominio administrativo y registros para las aplicaciones. Configura HTTPS desde Coolify y, cuando el dominio funcione, restringe los puertos de acceso directo según la documentación.

Desplegar una aplicación

Conecta el repositorio, elige método de construcción, define variables y dominio, y despliega. No copies secretos en campos públicos. Revisa logs, healthcheck y persistencia antes de promover a producción.

Operación segura

Configura backups externos para bases de datos y recursos críticos, actualiza Coolify con un procedimiento probado y vigila disco: imágenes, caché de builds y logs crecen. Para cargas serias, separar el servidor de builds evita que una compilación agote el host de producción.

La guía de Docker Compose ayuda a entender lo que Coolify automatiza. Consulta cuánta RAM necesita un VPS para sumar plataforma y aplicaciones. Terranode ofrece VPS KVM NVMe aptos para Docker.

Cuándo Coolify encaja y cuándo añade complejidad

Coolify resulta útil cuando quieres una experiencia parecida a una plataforma como servicio sin entregar el control del servidor. Centraliza repositorios, construcciones, variables, dominios, certificados y logs sobre Docker. Esa comodidad tiene un coste: la propia plataforma consume recursos y se convierte en una pieza crítica que también debes respaldar y actualizar.

Encaja bien en estos escenarios:

• Varias aplicaciones web pequeñas administradas por el mismo equipo.
• Despliegues frecuentes desde Git sin mantener scripts propios para cada proyecto.
• Proyectos que necesitan bases de datos, dominios y certificados desde una interfaz común.
• Equipos que entienden el VPS pero prefieren no editar manualmente cada proxy y archivo Compose.

Una aplicación única y estable puede ser más sencilla con Docker Compose y Nginx. Un sistema que exige alta disponibilidad entre nodos tampoco la obtiene solo por instalar un panel en un VPS: si el host falla, plataforma y aplicaciones fallan juntas.

Dimensionar el VPS para ejecución y construcción

La capacidad debe cubrir dos cargas diferentes: ejecutar servicios y construir nuevas versiones. Una aplicación puede usar poca memoria en reposo y multiplicar el consumo durante la instalación de dependencias o la compilación. Si la base de datos comparte host, también compite por caché, CPU y disco.

Antes de instalar, revisa el servidor:

nproc
free -h
df -h /
lsblk
ip -br address

Deja espacio para imágenes anteriores y cachés de construcción. Un disco que llega al 100 % puede impedir que Docker cree capas, que la base escriba o que los logs registren la causa. Después de los primeros despliegues, observa el uso real con docker stats y docker system df; no elijas capacidad solo por el número de aplicaciones.

Para proyectos con compilaciones pesadas, utiliza un servidor de construcción separado si la edición de Coolify y tu arquitectura lo permiten. La ventaja no es únicamente velocidad: evita que un build defectuoso prive de memoria a la base de producción.

Preparar DNS y acceso administrativo

Define el subdominio del panel antes de depender de él y conserva una vía de acceso SSH al VPS. Por ejemplo, panel.ejemplo.com puede apuntar mediante un registro A a la IP del servidor. Los dominios de aplicaciones tendrán sus propios registros o un comodín si la política DNS lo permite.

Comprueba la resolución desde fuera:

dig +short panel.ejemplo.com A
dig +short app.ejemplo.com A

La primera cuenta administrativa debe crearse inmediatamente después del instalador. Hasta que la instancia tenga dueño, dejar la pantalla inicial abierta permite que otra persona llegue primero. No compartas la contraseña del panel entre técnicos; crea accesos individuales si la versión y el plan lo permiten, y revócalos al terminar su relación con el proyecto.

Una VPN como WireGuard o una regla por IP reduce la exposición administrativa. Si tu IP cambia, mantén preparada la consola web del proveedor para no bloquearte. No cierres SSH solo porque existe el panel: Coolify no sustituye la recuperación fuera de banda.

Revisar el instalador antes de conceder root

El comando rápido descarga código y lo ejecuta con privilegios elevados, por lo que debes validar origen y contenido en operaciones sensibles. En lugar de canalizar directamente, puedes descargar primero desde la URL oficial que muestra la documentación:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o /tmp/coolify-install.sh
less /tmp/coolify-install.sh
sudo bash /tmp/coolify-install.sh

No uses una copia encontrada en un foro ni una URL acortada. Guarda la salida del instalador y anota la fecha, porque ayudará a reconstruir qué ocurrió si hay un fallo. Al terminar, revisa contenedores y puertos antes de abrir el navegador:

docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
sudo ss -ltnp
docker system df

Si el puerto inicial no responde, no repitas el instalador sin mirar los logs. Una segunda ejecución sobre un estado parcial puede ocultar la primera causa o duplicar recursos.

Completar la configuración inicial sin dejar puertas abiertas

Configura primero la identidad administrativa, después el dominio y finalmente reduce la exposición temporal. Usa una contraseña única, guarda los códigos o mecanismos de recuperación y activa el segundo factor si está disponible en la instalación.

Asocia el dominio del panel y solicita el certificado desde la interfaz. Luego verifica desde otra red:

curl -I https://panel.ejemplo.com
openssl s_client -connect panel.ejemplo.com:443 -servername panel.ejemplo.com </dev/null

El certificado solo demuestra que el navegador cifra la conexión con ese nombre; no protege una contraseña débil ni limita quién puede intentar autenticarse. Mantén el firewall, registra intentos y evita reutilizar el panel como una aplicación pública para clientes.

Revisa también la hora del sistema. Certificados, webhooks y firmas pueden fallar con un reloj incorrecto:

timedatectl status
systemctl status systemd-timesyncd --no-pager

Conectar Git con el mínimo acceso posible

La integración debe poder leer solo los repositorios que va a desplegar y recibir los eventos necesarios. Una aplicación de Git suele ser preferible a un token personal amplio porque sus permisos y repositorios autorizados quedan delimitados.

Antes del primer despliegue decide:

• Qué rama representa producción.
• Si cada push despliega automáticamente o necesita aprobación.
• Qué usuario puede cambiar variables y dominios.
• Cómo volver al commit anterior.
• Qué migraciones de base se ejecutan y en qué momento.

No habilites despliegue automático sobre una rama donde se mezclan pruebas sin revisión. Un webhook funcional puede convertir un error pequeño en un cambio de producción en segundos. Para aplicaciones críticas, usa una rama protegida y una prueba previa que construya la misma imagen.

Si el repositorio es privado y la clonación falla, revisa el evento en el proveedor Git y el log de construcción en Coolify. Regenerar tokens a ciegas suele dejar credenciales antiguas activas; revoca explícitamente lo que ya no uses.

Elegir el método de construcción

El repositorio debe declarar cómo convertirse en una imagen reproducible. Si contiene un Dockerfile, controlas versiones, paquetes del sistema, usuario y comando. Los buildpacks o mecanismos automáticos reducen configuración, pero debes revisar qué runtime detectan y cómo fijar su versión.

Un Dockerfile sencillo para una aplicación Node puede construir en una etapa y ejecutar en otra:

FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

Añade .dockerignore para no enviar dependencias locales, historial Git ni secretos al constructor:

.git
node_modules
.env
*.log
backups

La aplicación debe escuchar en 0.0.0.0 dentro del contenedor, no únicamente en 127.0.0.1, porque el proxy llega por la red Docker. Esto no la expone automáticamente a internet; la publicación y el proxy deciden esa parte.

Variables, secretos y diferencias entre entornos

Las variables de producción deben existir en Coolify, no dentro del repositorio. Separa valores disponibles durante la construcción de los que solo necesita el proceso al ejecutar. Un secreto usado como argumento de build puede quedar registrado en capas o logs si el Dockerfile no está preparado para secretos de BuildKit.

Agrupa variables por propósito y documenta cuáles son obligatorias. Después de cambiarlas, confirma si la plataforma recreó el contenedor: editar un valor en la interfaz no modifica un proceso ya iniciado hasta que se despliega o reinicia de forma controlada.

Evita imprimir el entorno completo para depurar. En su lugar, comprueba solo que una variable existe sin mostrar el valor:

docker exec NOMBRE_CONTENEDOR sh -c 'test -n "$DATABASE_URL" && echo DATABASE_URL_definida'

Las credenciales necesitan una copia recuperable fuera de Coolify. Si pierdes el servidor y el único lugar donde existía una clave era la interfaz del servidor perdido, un respaldo de datos puede resultar inutilizable.

Dominios, proxy y certificados por aplicación

Cada aplicación debe declarar el puerto interno en el que escucha y el dominio que enviará tráfico hacia ella. No publiques manualmente el mismo puerto 80 o 443 desde el contenedor: esos puertos pertenecen al proxy de la plataforma.

Cuando aparece un 502, separa tres pruebas:

1. 1 El DNS resuelve a la IP correcta.
2. 2 El proxy alcanza el contenedor por su red y puerto interno.
3. 3 La aplicación responde con el encabezado Host esperado.

Desde el VPS identifica el contenedor y prueba su salud sin saltarte la arquitectura:

docker ps --format '{{.Names}} {{.Networks}} {{.Ports}}'
docker logs --tail=200 NOMBRE_CONTENEDOR
docker inspect NOMBRE_CONTENEDOR --format '{{json .State.Health}}'

Un certificado pendiente puede deberse a DNS todavía propagándose, puertos bloqueados o un proxy externo que intercepta la validación. No emitas solicitudes repetidas sin corregir la causa: las autoridades de certificados aplican límites.

Bases de datos y almacenamiento persistente

Una base creada desde el panel sigue siendo una base real con datos que deben sobrevivir al contenedor y salir del servidor en forma de copia. Verifica el volumen asociado y evita publicar el puerto a internet solo para usar un cliente gráfico.

Para acceso administrativo temporal, un túnel SSH es más seguro:

ssh -L 15432:IP_INTERNA_DB:5432 usuario@IP_DEL_VPS

El destino exacto depende de la red creada por la plataforma; no codifiques una IP de contenedor que cambiará al recrearlo. Usa la opción de acceso definida por Coolify o un nombre estable cuando el diseño lo admita.

Los archivos subidos por usuarios también requieren persistencia. Si la aplicación guarda /app/uploads y esa ruta no tiene volumen ni almacenamiento de objetos, una nueva imagen puede dejar los archivos atrás. Prueba un despliegue después de subir un archivo de prueba y confirma que sigue disponible.

Diseñar backups que permitan reconstruir Coolify

Necesitas recuperar dos capas: la plataforma y cada carga que administra. La copia de Coolify conserva su configuración según el mecanismo soportado, pero no debes asumir que incluye automáticamente todas las bases, repositorios externos y volúmenes.

Construye un inventario con:

• Dominios y registros DNS.
• Repositorios, ramas y método de construcción.
• Variables y secretos recuperables.
• Bases de datos, formato y frecuencia de volcado.
• Volúmenes con archivos de usuario.
• Credenciales del proveedor y del almacenamiento de backups.

Guarda los volcados fuera del VPS y practica en un servidor distinto. La prueba correcta no consiste en descargar un archivo, sino en levantar una aplicación, importar sus datos y completar una acción funcional.

Actualizar la plataforma sin convertir producción en una prueba

Lee las notas de la versión, crea una copia y confirma espacio antes de actualizar. Las imágenes nuevas y las capas temporales necesitan disco adicional. Registra el estado de los servicios y no limpies las imágenes anteriores hasta que el panel y varias aplicaciones funcionen.

df -h /
docker system df
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

Después de actualizar, prueba el inicio de sesión, el acceso a una aplicación existente, la lectura de logs y un despliegue controlado de pruebas. Que el panel abra no demuestra que los webhooks, el constructor y el proxy estén operativos.

Si algo falla, conserva SSH y la consola del proveedor. Revisa los logs de los contenedores de plataforma antes de reiniciar todo el servidor; un problema de disco, migración o red requiere una corrección distinta.

Problemas frecuentes al instalar Coolify

Mantener una ruta de salida

Una plataforma self-hosted debe facilitar el despliegue, no encerrar la aplicación. Conserva Dockerfile, configuración declarativa, volcados en formatos estándar y documentación de variables. Así puedes migrar a Compose, otro VPS o un servicio administrado si las necesidades cambian.

Prueba esa portabilidad al menos con una aplicación no crítica: construye la imagen fuera de Coolify, inicia una base vacía, restaura el volcado y verifica el dominio en un entorno alternativo. Esa práctica también demuestra que tus backups sirven y que el conocimiento no vive solo en la interfaz.

Crear un entorno de prueba que se parezca a producción

La mejor forma de validar un cambio de Coolify es desplegar una segunda aplicación con dominio, variables y datos aislados. No apuntes staging al volumen o base de producción solo para ahorrar espacio. Usa un subdominio propio, credenciales distintas y una muestra de datos sin información sensible.

Prueba en ese entorno el flujo completo: webhook, construcción, healthcheck, certificado, persistencia y rollback. Una compilación exitosa no demuestra que el contenedor escuche en el puerto indicado ni que sobrevivan los archivos tras desplegar de nuevo.

Antes de promover, registra el commit y la imagen seleccionada. Después del despliegue de producción verifica una transacción de lectura y otra de escritura inocua. Si el cambio incluye migración, comprueba que una versión anterior puede convivir con el esquema durante el tiempo de rollback.

Ensayar la pérdida total del VPS

Una recuperación real comienza en un servidor vacío, no en el mismo panel que creó la copia. Prepara un VPS temporal, instala una versión compatible, recupera la configuración soportada e importa una aplicación representativa. Repite DNS mediante una entrada local o un subdominio de prueba para no mover producción.

Cronometra desde el inicio hasta que un usuario completa una función. El ensayo suele descubrir dependencias olvidadas: token del repositorio, clave del almacenamiento, variable cifrada, archivo subido o registro DNS. Añade cada hallazgo al inventario y repite hasta que otra persona pueda seguirlo.

Cuando termines, elimina las credenciales temporales y destruye el entorno de ensayo de forma controlada. La prueba no debe dejar una segunda copia pública con datos y contraseñas vigentes.

Criterios para dar por terminado el primer despliegue

El proyecto está listo cuando puede desplegarse dos veces sin perder datos y puede revertirse, no cuando aparece una pantalla verde. Comprueba dominio y HTTPS, reinicia la aplicación, crea un dato de prueba y vuelve a desplegar. Ese dato debe permanecer y los logs no deben contener secretos.

Simula además un commit fallido en staging: Coolify debe conservar o permitir recuperar la versión sana. Registra qué persona recibe la alerta y dónde revisa el build. Esta prueba pequeña descubre antes de producción variables ausentes, puertos equivocados y volúmenes mal montados.

Vigilar builds, despliegues y aplicaciones por separado

Una sola alarma de “Coolify responde” no cubre las tres funciones que presta. El panel puede abrir mientras el constructor no descarga repositorios, o el build puede terminar mientras el proxy no enruta el dominio. Define comprobaciones independientes.

Para cada aplicación observa una URL funcional y el estado del contenedor. Para la plataforma revisa reinicios, uso de disco y errores de los servicios internos. Para el pipeline registra duración y resultado de builds; un crecimiento sostenido puede advertir caché ineficiente o recursos insuficientes.

docker ps --format 'table {{.Names}}\t{{.Status}}'
docker stats --no-stream
docker system df
curl -fsS -o /dev/null -w '%{http_code} %{time_total}\n' https://app.ejemplo.com/health

No hagas pública una ruta que exponga versión, variables o estado de la base. Una respuesta mínima es suficiente para disponibilidad; las pruebas profundas pueden ejecutarse desde monitoreo autenticado.

Configura avisos hacia un canal que alguien atienda y prueba el aviso. Una integración guardada pero nunca ensayada suele fallar por token, DNS o firewall justo cuando se necesita. Documenta quién decide rollback y cuánto tiempo esperará antes de intervenir.

Coordinar migraciones de base con el despliegue

Coolify puede automatizar la entrega del contenedor, pero no decide si una migración es reversible. Diseña cambios aditivos: crear columna o tabla primero, desplegar código compatible y retirar estructuras antiguas después de la ventana de rollback.

Antes del cambio genera un volcado consistente y registra cuánto tarda restaurarlo. No ejecutes dos réplicas que compitan por una migración sin un mecanismo de bloqueo. Separa la migración del healthcheck: una ruta de salud no debe alterar el esquema.

Si una entrega falla después de modificar datos, volver al commit anterior puede empeorar el incidente si ese código espera el esquema viejo. Define por versión qué combinaciones de aplicación y base son válidas y prueba el camino de regreso en staging.