Desplegar aplicaciones web con Kamal en un VPS

Kubernetes resuelve problemas de coordinación a gran escala — descubrimiento de servicios, escalado horizontal automático, espacios de nombres para múltiples equipos — que simplemente no existen en un VPS único o en un cluster pequeño. Solo para instalarlo con kubeadm, la documentación oficial pide 2 GB de RAM por máquina y 2 CPU para el plano de control, antes de cualquier aplicación. Kamal apunta a un espacio diferente: toma tu Dockerfile, construye la imagen, la envía al registro, la ejecuta en tus servidores vía SSH y cambia el tráfico sin interrupciones gracias a kamal-proxy. Toda la configuración reside en un único archivo config/deploy.yml versionado junto al código. Sin plano de control que mantener, sin certificados de API que renovar, sin YAML distribuido en diez tipos de recursos. Conservas la simplicidad operativa de un VPS — acceso SSH directo, docker ps legible, logs en un archivo — y obtienes un flujo de despliegue profesional con rollback instantáneo, health checks y HTTPS automático.

En el lado del VPS, Kamal necesita un servidor Linux accesible por SSH con clave (sin contraseña); su documentación no impone distribución ni tamaño, pero cuenta con al menos 2 vCPU y 2 GB de RAM para una aplicación web estándar con su base de datos. Kamal puede instalar Docker él mismo durante el primer kamal setup (script get.docker.com), pero para ello necesita acceso root por SSH — Kamal se conecta como root por defecto. Los puertos 80 y 443 abiertos en entrada y un registro DNS A apuntando a la IP del VPS son indispensables antes de activar el SSL. En tu máquina local, dos opciones: instalar la gema Ruby (gem install kamal, con un entorno Ruby) o usar la imagen Docker oficial. La versión actual es la 2.12.0 (junio de 2026). Prepara también un registro de contenedores — Docker Hub, GitHub Container Registry o un registro privado — junto con sus credenciales.

Kamal 2, publicado en septiembre de 2024 (incluido por defecto en Rails 8, publicado en noviembre de 2024), reemplaza Traefik por kamal-proxy, un proxy inverso desarrollado internamente por 37signals. El cambio es estructural: Traefik es declarativo (le envías una configuración y converge), mientras que Kamal es imperativo. La versión 1 tenía que consultar la API de Traefik repetidamente para saber si el despliegue había tenido éxito — fuente de condiciones de carrera. Con kamal-proxy, los comandos son directos y sincrónicos. En cuanto a la configuración, el bloque traefik: desaparece de deploy.yml y es reemplazado por proxy: con las claves host, ssl y app_port. Los secretos migran de .env a .kamal/secrets, un archivo shell evaluado que puede llamar a herramientas externas como op read o bw get. La configuración se convierte a mano; kamal upgrade migra después los servidores: retira Traefik, inicia kamal-proxy y reinicia la aplicación y los accesorios en la nueva red. Kamal 2 también introduce el despliegue de varias aplicaciones en un mismo proxy y el modo mantenimiento (kamal app maintenance, y luego kamal app live para volver a estar en línea).

Kamal despliega hacia todos los servidores de un rol en paralelo por defecto. Para un cluster de servidores web, lista sus IPs bajo servers: web:. Para un despliegue progresivo (rolling), añade boot: limit: 2 wait: 10 — Kamal desplegará en 2 servidores a la vez con 10 segundos entre grupos. Los roles permiten diferenciar los servidores: bajo servers: declara web: (servidores HTTP) y workers: con un comando específico como bundle exec sidekiq. Cada rol puede tener sus propios servidores, secretos y variables. kamal-proxy funciona en cada servidor del rol principal (web por defecto); los demás roles, como workers, no lo ejecutan. Con varios servidores web, coloca un balanceador de carga delante: el HTTPS automático de kamal-proxy supone un despliegue en un solo servidor.

La separación entre variables claras y secretos es explícita en Kamal 2. En deploy.yml, las variables no sensibles van bajo env: clear: (aparecen en los logs e inspección de contenedor), y los secretos bajo env: secret: — su valor se lee desde .kamal/secrets en el momento del despliegue y se escribe en un archivo de entorno en el servidor, en lugar de pasarse en texto plano en el comando docker run. Un secreto de .kamal/secrets solo se inyecta si figura bajo env: secret:, en la raíz para todos los roles o en el rol o accesorio que lo usa. El comando kamal secrets print muestra los valores resueltos para verificar que la lectura desde un gestor de contraseñas funciona correctamente antes de desplegar.

Kamal-proxy gestiona el ciclo de vida TLS completo: escucha en los puertos 80 y 443, responde a los desafíos ACME de Let's Encrypt, obtiene el certificado, lo almacena en el servidor y lo renueva automáticamente antes de su caducidad. El único requisito previo es que el nombre de host declarado en proxy: host: resuelva a la IP del VPS y que los puertos 80 y 443 estén abiertos — el certificado se solicita en la primera conexión HTTPS, y el desafío ACME falla mientras el DNS no se haya propagado. En un servidor con varias apps, cada una con su propio dominio, kamal-proxy enruta por nombre de host y gestiona un certificado separado por dominio. Este HTTPS automático supone un despliegue en un solo servidor: más allá, termina el TLS en un balanceador de carga.

SSH connection timeout: verifica que la IP del servidor sea accesible (ssh -i tu_clave [email protected]) y que el cortafuegos permita el puerto 22. El agente SSH debe estar activo. Target failed to become healthy: el health check por defecto consulta GET /up — si tu aplicación no responde en esa ruta, declara proxy: healthcheck: path: /health en deploy.yml. Verifica también que app_port: coincida con el puerto real del contenedor. Error de autenticación en el registro: ejecuta kamal registry login y reintenta. En CI, verifica que la variable KAMAL_REGISTRY_PASSWORD esté exportada antes de kamal deploy. Conflicto de puertos en el servidor: si un proceso externo ocupa el puerto 80 o 443, kamal-proxy no puede iniciarse; identifícalo con ss -tlnp | grep -E '80|443'. kamal setup falla al instalar Docker: la instalación automática requiere acceso root por SSH; si no, instala Docker manualmente y relanza kamal setup.

Un flujo de trabajo típico de GitHub Actions para Kamal 2 tiene dos trabajos: un trabajo de pruebas (ejecutado en cada push) y un trabajo de despliegue condicional (activado al hacer push a main o al publicar una release). En el trabajo de despliegue: instala Ruby y la gema Kamal, luego ejecuta kamal deploy con los secretos inyectados desde GitHub Secrets. Elementos clave del archivo .github/workflows/deploy.yml: el trabajo de despliegue depende del de pruebas (needs: test), configura las variables de entorno necesarias, instala Kamal con una versión fijada (gem install kamal -v 2.12.0) y ejecuta kamal deploy. El agente SSH se configura vía webfactory/[email protected] con la clave privada almacenada en GitHub Secrets. La variable KAMAL_REGISTRY_PASSWORD: ${{ secrets.KAMAL_REGISTRY_PASSWORD }} inyecta la contraseña del registro de contenedores desde GitHub Secrets.

Un VPS Cloud de ServOrbit con Ubuntu 24.04 cumple todos los requisitos de Kamal desde el primer momento: acceso SSH por clave, red de 1 Gbit/s e IP dedicada. El flujo de trabajo habitual: crea un registro DNS A apuntando app.your-domain.com a la IP del VPS, luego ejecuta kamal setup desde tu máquina local — Kamal instala Docker, inicia kamal-proxy, obtiene el certificado Let's Encrypt y despliega tu aplicación en una sola pasada. A partir de entonces, cada kamal deploy desde tu terminal o pipeline CI aplica la actualización sin interrupciones. Para alojar varios proyectos en el mismo VPS, cada uno con su propio dominio y certificado, añade una aplicación en un segundo deploy.yml apuntando al mismo servidor — kamal-proxy enruta por hostname sin reconfiguración. La facturación es la del VPS, sin coste adicional asociado al despliegue.