Instalación y Configuración de CapRover PaaS

CapRover es una plataforma PaaS de código abierto que convierte tu servidor Linux en un entorno de despliegue con interfaz web, CLI y más de 100 aplicaciones de un clic, todo construido sobre Docker Swarm. Permite desplegar aplicaciones desde Dockerfile, imágenes Docker o código fuente con buildpacks, gestionando automáticamente el proxy inverso, SSL y el balanceo de carga. Esta guía cubre la instalación completa y configuración de CapRover en producción.

Requisitos Previos

  • Ubuntu 20.04/22.04 o Debian 11/12 (servidor limpio, sin Docker previo)
  • Mínimo 1 vCPU y 1 GB RAM (recomendado 2+ GB)
  • 20 GB de espacio en disco
  • Acceso root
  • Dominio wildcard: *.tudominio.com apuntando al servidor (necesario para subdominios por app)
  • Puertos abiertos: 80, 443, 3000, 996, 7946, 4789, 2377

Instalación de CapRover

# Actualizar el sistema
apt-get update && apt-get upgrade -y

# Instalar Docker (CapRover lo requiere)
curl -fsSL https://get.docker.com | sh

# Instalar CapRover como contenedor Docker
docker run -p 80:80 -p 443:443 -p 3000:3000 \
    -e ACCEPTED_TERMS=true \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /captain:/captain \
    caprover/caprover

# El proceso tarda 1-2 minutos. Cuando veas "CapRover is ready" en los logs, está listo

Instalar la CLI de CapRover

# Instalar la CLI de CapRover con npm
npm install -g caprover

# Verificar la instalación
caprover --version

# Alternativa: instalar con npx sin instalar globalmente
npx caprover <comando>

Configuración Inicial

Accede a http://IP_DEL_SERVIDOR:3000 con tu navegador. La contraseña por defecto es captain42.

Configurar con la CLI

# Configurar el servidor CapRover (asistente interactivo)
caprover serversetup

# El asistente pedirá:
# - IP del servidor: IP_DEL_SERVIDOR
# - Puerto: 3000
# - Contraseña actual: captain42
# - Nueva contraseña: (elige una segura)
# - Dominio raíz: tudominio.com (debe tener *.tudominio.com apuntando al servidor)

Configuración del dominio wildcard en DNS

# En tu proveedor DNS, crea estos registros:
# Tipo A: captain.tudominio.com → IP_DEL_SERVIDOR
# Tipo A: *.tudominio.com → IP_DEL_SERVIDOR

# Verificar que el wildcard funciona
ping app-cualquiera.tudominio.com
# Debe resolver a la IP del servidor

Verificar la instalación

# Después de la configuración, el panel está en:
# https://captain.tudominio.com (con SSL automático)

# Verificar certificado SSL
curl -I https://captain.tudominio.com

Desplegar Aplicaciones

Aplicaciones de un clic

CapRover incluye más de 100 aplicaciones preconfiguradas:

  1. Ve al panel web > Apps > One-Click Apps
  2. Busca la aplicación (WordPress, Ghost, Nextcloud, GitLab, etc.)
  3. Configura las variables y haz clic en Deploy
# Equivalente con CLI - listar aplicaciones de un clic
caprover deploy --oneClickApp

# Las aplicaciones se crean automáticamente con:
# - Contenedor configurado
# - Variables de entorno
# - Volúmenes persistentes
# - Dominio asignado

Despliegue desde código fuente

# Inicializar CapRover en tu proyecto
caprover init

# Responder las preguntas del asistente:
# - Nombre de la aplicación en CapRover
# - Branch a desplegar

# Esto crea captain-definition y .caprover.yml en el proyecto

El archivo captain-definition:

{
  "schemaVersion": 2,
  "templateId": "node/18"
}
# Desplegar el proyecto actual al servidor CapRover
caprover deploy

# Desplegar directamente sin asistente
caprover deploy \
    --caproverUrl https://captain.tudominio.com \
    --caproverPassword tu-password \
    --appName mi-aplicacion \
    --branch main

Variables de entorno

# Desde la CLI
caprover config \
    --envVar "NODE_ENV=production" \
    --envVar "DATABASE_URL=postgresql://usuario:pass@db:5432/miapp"

# O desde el panel web: Apps > mi-aplicacion > App Configs > Environmental Variables

Despliegue con Dockerfile

CapRover puede usar el Dockerfile de tu proyecto:

# Dockerfile de ejemplo para una aplicación Node.js
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]
// captain-definition para usar Dockerfile
{
  "schemaVersion": 2,
  "dockerfileLines": null,
  "dockerFilePath": "./Dockerfile"
}

Despliegue desde imagen Docker

# En el panel web: Apps > mi-aplicacion > Deployment > Deploy via ImageName
# Ingresar la imagen: nginx:alpine o registry.empresa.com/mi-app:1.0.0

# Para registros privados, configurar primero las credenciales:
# Apps > mi-aplicacion > Deployment > Registry Credentials

Pipeline de CI/CD con webhook

# CapRover genera un URL de webhook por aplicación
# En el panel: Apps > mi-aplicacion > Deployment > Method > Via WebHook

# Usar en GitHub Actions:
# .github/workflows/deploy.yml
name: Deploy to CapRover

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy a CapRover
        uses: caprover/[email protected]
        with:
          server: "https://captain.tudominio.com"
          app: ${{ secrets.CAPROVER_APP }}
          token: ${{ secrets.CAPROVER_APP_TOKEN }}

Modo Cluster y Nodos Adicionales

CapRover usa Docker Swarm para soportar múltiples servidores:

# En el panel web: Cluster > Add New Worker Node

# En el servidor nuevo (nodo worker), ejecutar el comando que CapRover proporciona:
docker swarm join --token SWMTKN-1-xxxx IP_SERVIDOR_PRINCIPAL:2377

# Verificar que el nodo se unió al cluster
docker node ls  # Ejecutar en el nodo manager (servidor principal)

# Asignar una etiqueta al nodo worker
docker node update --label-add caprover.cap.le=true nombre-del-nodo
# Configurar afinidad de aplicación a nodo específico
# En el panel web: Apps > mi-aplicacion > App Configs > Node Placement
# Seleccionar el nodo preferido para esa aplicación

# Escalar horizontalmente una aplicación
# Apps > mi-aplicacion > App Configs > Instance Count: 3

Gestión de SSL

CapRover gestiona SSL automáticamente con Let's Encrypt para todos los subdominios:

# SSL se activa automáticamente al configurar el dominio
# En el panel web: Apps > mi-aplicacion > HTTP Settings

# Para dominio personalizado con SSL:
# 1. Apuntar el DNS del dominio al servidor
# 2. En HTTP Settings, agregar el dominio personalizado
# 3. Activar "Enable HTTPS" - CapRover solicita el certificado automáticamente

# Verificar el certificado
curl -I https://mi-app.tudominio.com
openssl s_client -connect mi-app.tudominio.com:443 -brief

Redireccionamiento HTTP a HTTPS

# Activar en el panel web:
# Apps > mi-aplicacion > HTTP Settings > Force HTTPS
# Esto redirige todas las peticiones HTTP a HTTPS automáticamente

Certificados para dominios personalizados

# Si tienes un dominio personalizado (ej: app.miempresa.com):
# 1. Crear registro DNS: app.miempresa.com → IP_DEL_SERVIDOR
# 2. En CapRover: Apps > mi-app > HTTP Settings
# 3. Agregar dominio personalizado: app.miempresa.com
# 4. Activar HTTPS - Let's Encrypt se encarga del resto

Solución de Problemas

El despliegue falla sin mensaje claro

# Ver los logs del build en el panel: Apps > mi-app > Deployment Logs
# O desde CLI:
caprover log --appName mi-aplicacion

# Ver logs del contenedor en ejecución
# En el panel: Apps > mi-app > App Logs

La aplicación no responde en el dominio

# Verificar que la app está corriendo
docker service ls | grep srv-captain--mi-aplicacion

# Verificar los logs del contenedor
docker service logs srv-captain--mi-aplicacion --tail=50

# Verificar la configuración del proxy (Nginx)
cat /captain/data/config/nginx.conf | grep mi-aplicacion

Error de certificado SSL

# Verificar que el DNS wildcard está configurado
dig +short app.tudominio.com

# Forzar renovación del certificado
# En el panel: Captain > Enable HTTPS (desactivar y volver a activar)

# Ver los logs de Let's Encrypt
docker service logs srv-captain--captain --tail=100 | grep -i "cert\|acme"

No se puede conectar al panel en el puerto 3000

# Verificar que Docker está corriendo
systemctl status docker

# Verificar el contenedor principal de CapRover
docker ps | grep caprover

# Revisar firewall
ufw status
ufw allow 3000/tcp

Conclusión

CapRover proporciona una experiencia PaaS completa sobre tu propio hardware, con la ventaja de ser completamente gratuito y sin límites artificiales de uso. Su sistema de aplicaciones de un clic, el soporte para Docker Swarm y la gestión automática de SSL lo hacen especialmente valioso para equipos que necesitan desplegar múltiples aplicaciones con facilidad. Para entornos de producción, combínalo con un pipeline CI/CD usando los webhooks de despliegue para automatizar completamente el flujo de código a producción.