Instalación de Coolify PaaS Self-Hosted

Coolify es una plataforma PaaS de código abierto que convierte tu servidor en una alternativa a Heroku, Netlify y Vercel, permitiendo desplegar aplicaciones, bases de datos y servicios con un solo clic. Con soporte para Git push automático, gestión de SSL, dominios personalizados y colaboración en equipo, Coolify simplifica el despliegue de aplicaciones sin depender de plataformas cloud costosas. Esta guía cubre la instalación y configuración completa en tu propio servidor Linux.

Requisitos Previos

  • Servidor Linux con Ubuntu 20.04/22.04 o Debian 11/12
  • Mínimo 2 vCPU y 2 GB RAM (recomendado 4 GB)
  • 30 GB de espacio en disco
  • Acceso root o sudo
  • Dominio o subdominio apuntando al servidor (para SSL)
  • Puerto 80, 443 y 8000 abiertos en el firewall

Instalación de Coolify

Coolify se instala con un único script que configura Docker y todos los servicios necesarios:

# Instalar Coolify con el script oficial
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

# El script instala automáticamente:
# - Docker y Docker Compose
# - Coolify y sus servicios (proxy, base de datos, etc.)
# - Configuración del sistema

El proceso tarda entre 2 y 5 minutos. Al finalizar, el panel de administración estará disponible en http://TU_IP:8000.

# Verificar que los servicios están corriendo
docker ps | grep coolify

# Ver los logs durante el arranque inicial
docker logs coolify -f

# Verificar el estado del proxy Traefik
docker ps | grep proxy

Instalación con Docker Compose (alternativa)

Si prefieres más control sobre la instalación:

# Crear directorio de configuración
mkdir -p /data/coolify/{ssh,applications,databases,backups,services,proxy,webhooks-during-maintenance}

# Descargar la configuración oficial
curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.yml -o /data/coolify/docker-compose.yml
curl -fsSL https://cdn.coollabs.io/coolify/.env.production -o /data/coolify/.env

# Editar variables de entorno
nano /data/coolify/.env

# Iniciar los servicios
cd /data/coolify
docker compose up -d

# Ver los logs
docker compose logs -f

Configuración Inicial

Accede a http://TU_IP:8000 o http://tu-dominio:8000 con tu navegador:

  1. Crear cuenta de administrador: La primera cuenta creada tiene permisos completos
  2. Configurar el dominio de Coolify: Ve a Configuración > General y establece el dominio completo (ej: coolify.tuempresa.com)
# Configurar el dominio de Coolify en el .env si es necesario
# Esto habilita el acceso por HTTPS al panel
echo "APP_URL=https://coolify.tuempresa.com" >> /data/coolify/.env

# Reiniciar para aplicar cambios
cd /data/coolify
docker compose restart

Agregar servidores adicionales

Coolify puede gestionar múltiples servidores desde un panel centralizado:

# Generar clave SSH para que Coolify se conecte a servidores remotos
# Coolify genera su propia clave durante la instalación
cat /data/coolify/ssh/keys/[email protected]

# Copiar la clave pública al servidor remoto
ssh-copy-id -i /data/coolify/ssh/keys/[email protected] usuario@servidor-remoto

# En la interfaz web: Servers > Add Server > ingresar IP y verificar conexión

Conectar Repositorios Git

Integración con GitHub

  1. Ve a Sources en el panel lateral
  2. Selecciona GitHub App
  3. Sigue el flujo OAuth para autorizar Coolify en tu cuenta de GitHub
# Coolify también acepta repositorios con clave SSH
# Agregar la clave pública de Coolify a tu proveedor Git
cat /data/coolify/ssh/keys/[email protected]
# Agregar esta clave en GitHub > Settings > Deploy Keys

Repositorios privados con token

Para repositorios privados sin GitHub App:

  • Ve a Sources > GitHub/GitLab
  • Usa un Personal Access Token con permisos de lectura de repositorios

Desplegar Aplicaciones

Despliegue desde Git

  1. Ve a Projects > New Project
  2. Selecciona el equipo y nombre del proyecto
  3. Add Resource > Application
  4. Selecciona el servidor y la fuente Git
# Coolify detecta automáticamente el tipo de aplicación usando Nixpacks
# Soporta: Node.js, Python, PHP, Ruby, Go, Rust, Java, y más

# Para aplicaciones con Dockerfile propio:
# Coolify lo detecta automáticamente si existe Dockerfile en la raíz

Variables de entorno

En la pantalla de la aplicación, sección Environment Variables:

# Variables de entorno típicas para una app Node.js
DATABASE_URL=postgresql://usuario:password@db:5432/miapp
REDIS_URL=redis://redis:6379
NODE_ENV=production
JWT_SECRET=mi-secreto-seguro
PORT=3000

Configurar el comando de build y start

# En la sección "Build & Deploy" de la aplicación:
# Build Command: npm run build
# Start Command: npm start
# Port: 3000 (puerto que expone la aplicación)

# Para aplicaciones estáticas (Vite, Create React App):
# Build Command: npm run build
# Publish Directory: dist

Webhooks para despliegue automático

Coolify crea automáticamente un webhook. En GitHub:

  1. Settings > Webhooks > Add webhook
  2. URL: https://coolify.tuempresa.com/webhooks/source/github/events/manual
  3. Content type: application/json
  4. Eventos: push al branch de producción

Gestión de Bases de Datos

Coolify puede desplegar bases de datos gestionadas con un clic:

  1. Ve a Projects > Tu Proyecto > Add Resource > Database
  2. Selecciona el motor: PostgreSQL, MySQL, MariaDB, MongoDB, Redis, KeyDB
# Las credenciales se generan automáticamente y están disponibles
# en la sección "Connection" de la base de datos en Coolify

# Acceder a PostgreSQL desde la línea de comandos (en el servidor)
docker exec -it nombre-contenedor-postgres psql -U usuario -d basedatos

# Acceder a MySQL
docker exec -it nombre-contenedor-mysql mysql -u usuario -ppassword basedatos

# Para acceso externo, Coolify puede exponer el puerto de la BD
# (no recomendado en producción sin firewall adecuado)

Backups automáticos de bases de datos

En la configuración de cada base de datos:

  • Backups > Schedule: Configurar frecuencia (diario, semanal)
  • Backups > S3: Configurar bucket S3 compatible para almacenamiento externo
# Variables para configurar S3 en Coolify
AWS_ACCESS_KEY_ID=tu-access-key
AWS_SECRET_ACCESS_KEY=tu-secret-key
AWS_DEFAULT_REGION=eu-west-1
AWS_BUCKET=mi-bucket-backups

Configuración de SSL y Dominios

Dominio personalizado con SSL automático

  1. Apunta el DNS de tu dominio a la IP del servidor
  2. En la aplicación de Coolify, sección Domains:
    • Agrega tu dominio: app.tuempresa.com
    • Activa SSL (Let's Encrypt automático)
# Coolify usa Traefik como proxy inverso
# Los certificados SSL se gestionan automáticamente

# Verificar que el certificado se generó correctamente
curl -I https://app.tuempresa.com
# Buscar "HTTP/2 200" en la respuesta

# Ver certificados gestionados por Traefik
docker exec coolify-proxy traefik version

Configuración del proxy

# Los archivos de configuración del proxy están en:
ls /data/coolify/proxy/

# Ver la configuración dinámica de Traefik
cat /data/coolify/proxy/dynamic/

Solución de Problemas

La aplicación no arranca después del despliegue

# Ver los logs de la aplicación en Coolify UI: Application > Logs
# O directamente en el servidor:
docker logs nombre-contenedor-aplicacion --tail=100

# Ver logs del proceso de build
docker logs coolify-build-nombre --tail=200

SSL no se genera

# Verificar que el dominio resuelve a la IP del servidor
dig +short app.tuempresa.com

# Verificar que los puertos 80 y 443 están abiertos
sudo ufw status
# Si está activo y bloqueado:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Ver logs de Traefik para errores de certificado
docker logs coolify-proxy --tail=50 | grep -i "cert\|acme\|error"

Coolify no arranca

# Verificar el estado de todos los contenedores de Coolify
cd /data/coolify
docker compose ps

# Reiniciar todos los servicios
docker compose restart

# Si hay un problema grave, reiniciar desde cero (sin perder datos)
docker compose down
docker compose up -d

Webhook de GitHub no dispara el despliegue

# Verificar los logs de webhooks en Coolify UI: Settings > Webhooks
# Verificar que el payload URL es correcto en GitHub
# Comprobar que el servidor es accesible desde internet en el puerto 8000 o 443

Conclusión

Coolify transforma cualquier servidor Linux en una plataforma de despliegue completa con la comodidad de los PaaS comerciales pero sin sus costes recurrentes. Su combinación de gestión automática de SSL, integración Git, bases de datos gestionadas y soporte para múltiples servidores lo convierte en una solución ideal para startups y equipos de desarrollo que quieren control total sobre su infraestructura sin sacrificar la productividad.