CapRover es una plataforma PaaS de código abierto que funciona sobre Docker Swarm: te da un panel web y una CLI para desplegar aplicaciones desde un Dockerfile o una imagen, y se encarga del proxy inverso con Nginx y de los certificados de Let's Encrypt. En este tutorial instalarás CapRover en Ubuntu 24.04, le asignarás un dominio wildcard con HTTPS y desplegarás una aplicación de prueba desde tu equipo con la CLI.

Requisitos previos

Para seguir esta guía necesitas:

  • Un servidor limpio con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 1 vCPU, 2 GB de RAM y 20 GB de disco. CapRover arranca con 1 GB, pero las compilaciones de imágenes se quedan cortas de memoria.
  • Un usuario no root con privilegios sudo.
  • Ningún servicio escuchando en los puertos 80 y 443 (ni Nginx ni Apache instalados en el sistema).
  • Un dominio en el que puedas crear registros DNS. En esta guía se usa apps.tudominio.com; sustituye tudominio.com por tu dominio y IP_DEL_SERVIDOR por la IP pública del servidor.
  • En tu equipo local, Node.js 18 o superior y Git, para usar la CLI de CapRover.

Paso 1: Crear los registros DNS

CapRover asigna a cada aplicación un subdominio de un dominio raíz, por lo que necesita un registro wildcard. Crea este registro en tu proveedor DNS:

TipoNombreValor
A*.apps.tudominio.comIP_DEL_SERVIDOR

El panel quedará en captain.apps.tudominio.com y cada aplicación en nombre-app.apps.tudominio.com. Comprueba que cualquier subdominio resuelve a tu servidor:

dig +short prueba123.apps.tudominio.com

203.0.113.10

Si no obtienes la IP, espera a que se propague el registro antes de seguir: sin DNS correcto, Let's Encrypt no podrá emitir los certificados en el paso 5.

Paso 2: Configurar el firewall

CapRover necesita los puertos 80 y 443 para las aplicaciones, el 3000 para el primer acceso al panel y el 996 para su registro interno de imágenes. Permite también SSH antes de activar UFW para no perder el acceso:

sudo ufw allow OpenSSH
sudo ufw allow 80,443,3000,996/tcp
sudo ufw enable

Comprueba las reglas:

sudo ufw status

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80,443,3000,996/tcp        ALLOW       Anywhere
...

Si más adelante añades nodos al clúster, abre también 2377/tcp, 7946/tcp, 7946/udp y 4789/udp entre los servidores.

Paso 3: Instalar Docker Engine

CapRover requiere Docker Engine desde el repositorio oficial de Docker (no la versión snap). Añade la clave y el repositorio:

sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
EOF

Instala Docker:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verifica que el servicio está activo:

sudo systemctl is-active docker

active

Paso 4: Instalar CapRover

CapRover se instala lanzando su contenedor una vez. Ese contenedor inicializa Docker Swarm, crea los servicios de CapRover y termina. La variable ACCEPTED_TERMS=true indica que aceptas los términos de uso del proyecto:

sudo 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

Todos los datos de CapRover (configuración, certificados, datos de las aplicaciones) se guardan en /captain. La instalación tarda uno o dos minutos. Después, comprueba que los servicios de CapRover están en marcha:

sudo docker service ls --format '{{.Name}} {{.Replicas}}'

Deberías ver al menos captain-captain y captain-nginx con 1/1 réplicas. Si algo falla, revisa el registro del servicio principal:

sudo docker service logs captain-captain --since 10m

Paso 5: Configurar el dominio raíz y HTTPS

Abre http://IP_DEL_SERVIDOR:3000 en el navegador e inicia sesión con la contraseña por defecto, captain42. En la página principal del panel:

  1. En CapRover Root Domain Configurations, escribe apps.tudominio.com y pulsa Update Domain. El navegador te redirigirá a http://captain.apps.tudominio.com; vuelve a iniciar sesión.
  2. Pulsa Enable HTTPS, introduce un correo para Let's Encrypt y confirma. CapRover solicita el certificado para captain.apps.tudominio.com.
  3. Cuando termine, activa Force HTTPS para que el panel solo sea accesible por HTTPS.
  4. En Settings, cambia la contraseña captain42 por una contraseña segura.

Verifica desde tu equipo que el panel responde con un certificado válido:

curl -sI https://captain.apps.tudominio.com | head -n 1

HTTP/2 200

Paso 6: Crear una aplicación

En el panel, ve a Apps, escribe hola como nombre de aplicación y pulsa Create New App. No marques Has Persistent Data para esta prueba: solo hace falta en aplicaciones que guardan datos en volúmenes, como bases de datos.

Abre la aplicación hola, pestaña HTTP Settings, y pulsa Enable HTTPS. Como el wildcard ya apunta al servidor, CapRover obtiene el certificado para hola.apps.tudominio.com sin más configuración. Activa también Force HTTPS y guarda con Save & Update.

Paso 7: Desplegar desde tu equipo con la CLI

La CLI de CapRover empaqueta tu proyecto, lo sube al servidor y CapRover construye la imagen a partir del Dockerfile. En tu equipo local, instálala con npm:

npm install -g caprover
caprover --version

Crea un proyecto mínimo con Git:

mkdir hola && cd hola
git init

Crea index.html:

<!doctype html>
<html lang="es">
  <head><meta charset="utf-8"><title>Hola</title></head>
  <body><h1>Hola desde CapRover</h1></body>
</html>

Crea un Dockerfile que sirva la página con Nginx:

FROM nginx:alpine
COPY index.html /usr/share/nginx/html/index.html

Crea el archivo captain-definition, que le dice a CapRover cómo construir la aplicación:

{
  "schemaVersion": 2,
  "dockerfilePath": "./Dockerfile"
}

La CLI despliega el contenido de la rama de Git, no los archivos sin confirmar, así que haz un commit:

git add .
git commit -m "Primera versión"

Inicia sesión en tu servidor. La CLI te pedirá la URL (https://captain.apps.tudominio.com), la contraseña del panel y un nombre para guardar esta conexión:

caprover login

Despliega la aplicación. Elige el servidor, la aplicación hola y la rama actual cuando te lo pregunte:

caprover deploy

Al terminar, la CLI muestra Deployed successfully y la URL de la aplicación. Compruébalo:

curl -s https://hola.apps.tudominio.com

<!doctype html>
<html lang="es">
  <head><meta charset="utf-8"><title>Hola</title></head>
  <body><h1>Hola desde CapRover</h1></body>
</html>

La aplicación escucha en el puerto 80 del contenedor, que es el valor por defecto de Container HTTP Port en HTTP Settings. Si tu aplicación usa otro puerto (por ejemplo 3000 en Node.js), cámbialo ahí.

Paso 8: Variables de entorno, dominio propio y despliegue continuo

Las variables de entorno se definen en la pestaña App Configs de cada aplicación, en Environmental Variables. Tras guardar con Save & Update, CapRover reinicia el contenedor con los nuevos valores.

Para servir la aplicación en un dominio propio, por ejemplo www.tuempresa.com:

  1. Crea un registro A www.tuempresa.com apuntando a IP_DEL_SERVIDOR.
  2. En HTTP Settings de la aplicación, añádelo en Connect New Domain.
  3. Pulsa Enable HTTPS junto al dominio recién añadido.

Para desplegar automáticamente con cada push a GitHub, activa Enable App Token en la pestaña Deployment de la aplicación y guarda el token como secreto CAPROVER_APP_TOKEN en el repositorio. Después añade este flujo de trabajo en .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
        uses: caprover/[email protected]
        with:
          server: "https://captain.apps.tudominio.com"
          app: hola
          token: "${{ secrets.CAPROVER_APP_TOKEN }}"

Solución de problemas

El despliegue falla durante la compilación. Revisa Deployment > View Build Logs en el panel. Los errores más habituales son un dockerfilePath que no coincide con la ruta real o falta de memoria al compilar; en ese caso añade swap o usa un servidor con más RAM.

La aplicación devuelve 502 Bad Gateway. El contenedor no escucha en el Container HTTP Port configurado o se está reiniciando. Consulta los logs en la pestaña Deployment o desde el servidor (los servicios de las aplicaciones se llaman srv-captain--nombre-app):

sudo docker service logs srv-captain--hola --tail 50

Let's Encrypt no emite el certificado. Comprueba que el subdominio resuelve a la IP del servidor con dig +short hola.apps.tudominio.com y que el puerto 80 es accesible desde Internet. Let's Encrypt limita los intentos fallidos, así que corrige el DNS antes de reintentar.

Conclusión

Tienes CapRover funcionando en Ubuntu 24.04 con un dominio wildcard, HTTPS automático y una aplicación desplegada desde tu equipo con la CLI. A partir de aquí puedes instalar bases de datos o aplicaciones completas desde One-Click Apps, programar copias de seguridad del directorio /captain y, si necesitas más capacidad, añadir nodos worker desde la sección Cluster del panel.