Desplegar una app web con Kamal

Requisitos previos

• Una máquina de despliegue (tu laptop o un runner de CI) con Ruby 2.7 o superior. Ahí es donde corre Kamal.
• Un VPS con acceso SSH (root o un usuario con sudo). No necesita software preinstalado.
• Una cuenta en un registro Docker (Docker Hub, GHCR o cualquier registro privado) con credenciales.
• Tu aplicación web con un Dockerfile en la raíz del repositorio que construya una imagen ejecutable.
• Un dominio con un registro A o AAAA apuntando a la IP de tu VPS.

Kamal es una herramienta del lado cliente. Nunca se ejecuta en el servidor. El VPS es una máquina limpia que solo necesita ser accesible por SSH y tener los puertos 80 y 443 abiertos en el cortafuegos.

Paso 1: Instalar Kamal en tu máquina de despliegue

Instala la gema de Ruby:

gem install kamal

Verifica que está disponible:

kamal version

Eso es todo. No instales Kamal en el VPS. El VPS recibe comandos por SSH desde esta máquina.

Paso 2: Inicializar Kamal en tu aplicación

Entra en la raíz de tu aplicación y ejecuta:

cd /ruta/de/tu-app
kamal init

Esto crea dos archivos:

• config/deploy.yml — el archivo de configuración de despliegue
• .kamal/secrets — archivo local para valores sensibles (no lo subas al repositorio)

Ambos archivos los editarás en los siguientes pasos.

Paso 3: Configurar deploy.yml

Abre config/deploy.yml y reemplaza la plantilla con los valores de tu proyecto. Una configuración mínima funcional:

service: miapp
image: tu-usuario-registry/miapp

servers:
  web:
    - tu-dominio.com

proxy:
  ssl: true
  host: tu-dominio.com
  app_port: 3000

registry:
  server: ghcr.io
  username: tu-usuario-registry
  password: KAMAL_REGISTRY_PASSWORD

env:
  clear:
    RAILS_ENV: production
  secret:
    - RAILS_MASTER_KEY
    - DATABASE_URL

Campos clave:

• service — nombre para tu aplicación (se usa para nombrar contenedores)
• image — nombre completo de la imagen en el registro
• servers.web — lista de hostnames o IPs de tu VPS
• proxy — kamal-proxy termina SSL con Let's Encrypt y redirige tráfico a app_port
• registry — credenciales para subir y bajar imágenes
• env — variables de entorno que se pasan al contenedor

Para accesorios como PostgreSQL o Redis puedes añadir una sección accessories, pero empieza sin ellos en el primer despliegue.

Paso 4: Definir los secretos

Edita .kamal/secrets con los valores referenciados en deploy.yml:

KAMAL_REGISTRY_PASSWORD=tu-token-de-acceso
RAILS_MASTER_KEY=tu-rails-master-key
DATABASE_URL=postgres://usuario:pass@host/db

El archivo .kamal/secrets es solo local. En CI, inyecta estos valores desde el almacén de secretos de tu plataforma y pásalos como variables de entorno que Kamal pueda leer.

Nunca subas .kamal/secrets al control de versiones. El directorio .kamal ya está en .gitignore por defecto.

Paso 5: Preparar el VPS con kamal setup

Este es el comando principal. Hace todo en un solo paso:

kamal setup

Kamal se conecta por SSH a tu VPS y:

1. Instala Docker si no está presente
2. Inicia el contenedor kamal-proxy, que ocupa los puertos 80 y 443
3. Obtiene un certificado SSL de Let's Encrypt automáticamente para tu dominio
4. Descarga la imagen de tu aplicación desde el registro
5. Arranca tu aplicación detrás del proxy

Sin instalación manual de Docker, sin configurar Nginx, sin certbot. El VPS pasa de estar limpio a ejecutar tu app con un solo comando.

Paso 6: Desplegar actualizaciones

Después del setup inicial, despliega nuevas versiones con:

kamal deploy

Esto construye o descarga la nueva imagen, detiene el contenedor anterior de forma controlada, inicia el nuevo y verifica el health check. Kamal revierte el cambio automáticamente si el health check falla.

Mantenimiento

• Actualizar Kamal: gem update kamal en tu máquina de despliegue
• Ver logs: kamal app logs
• Ejecutar un comando en un contenedor: kamal app exec 'rails console'
• Reiniciar la app: kamal app restart
• Rollback: kamal deploy --version=<version-anterior>
• Actualizar kamal-proxy en el servidor: kamal proxy upgrade

Kamal no gestiona bases de datos. Haz backup de los datos persistentes por separado y documenta cómo recrear el servidor desde el repositorio y el almacén de secretos.