Plataformas de despliegue: Parte 5 — Kamal: despliegue de aplicaciones Docker en tu propio servidor

Kamal — una herramienta de línea de comandos de la compañía 37signals (creadores de Basecamp y Ruby on Rails) para desplegar aplicaciones web en contenedores Docker en servidores propios. Ocupa un lugar entre plataformas como Heroku o Vercel, donde la comodidad se paga con recargos y dependencia del proveedor, y Kubernetes, que ofrece flexibilidad a costa de una complejidad notable. Kamal se conecta a los servidores por SSH, lanza contenedores en ellos y cambia el tráfico a la nueva versión sin tiempo de inactividad.

Inicialmente Kamal se hizo para Rails, pero ahora no depende del lenguaje: si la aplicación se construye en una imagen Docker, se puede desplegar. La rama actual es Kamal 2 (la última versión al momento de escribir esto — 2.12).

Cómo funciona el despliegue

El comando kamal deploy realiza la siguiente secuencia de pasos:

1. construye la imagen Docker de la aplicación;
2. la envía al registro de contenedores;
3. en cada servidor descarga la nueva imagen y lanza el contenedor;
4. espera hasta que el nuevo contenedor responda a la comprobación de disponibilidad;
5. cambia el tráfico al nuevo contenedor y detiene el antiguo.

Del cambio se encarga kamal-proxy — el proxy propio de Kamal, que en la segunda versión reemplazó a Traefik. Durante el despliegue consulta la ruta de comprobación de disponibilidad (por defecto /up) una vez por segundo y dirige las solicitudes al nuevo contenedor solo después de una respuesta satisfactoria. Si la aplicación no arranca en el tiempo asignado, el tráfico permanece en la versión anterior.

Instalación y preparación de los servidores

Kamal se instala en la máquina del desarrollador o en CI como gem de Ruby (gem install kamal); si no hay Ruby, se puede ejecutar desde un contenedor Docker. En los servidores solo se necesita acceso SSH por clave.

El primer despliegue se realiza con el comando kamal setup. Según la documentación se conecta a los servidores por SSH (por defecto como root), instala Docker donde no esté presente mediante el script get.docker.com, arranca kamal-proxy y ejecuta el primer despliegue. Para instalar Docker se requieren permisos de root.

Configuración

Toda la configuración está en un único archivo config/deploy.yml. Ejemplo mínimo con un servidor y HTTPS automático:

service: my-app
image: my-user/my-app

servers:
  web:
    hosts:
      - 192.0.2.10

proxy:
  host: app.example.ru
  app_port: 3000
  ssl: true
  healthcheck:
    path: /up

registry:
  server: registry.example.ru
  username: my-user
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  clear:
    LOG_LEVEL: info
  secret:
    - DATABASE_URL

builder:
  arch: amd64

Con el parámetro ssl: true kamal-proxy obtiene el certificado de Let’s Encrypt por sí mismo. Según la documentación esto funciona cuando la aplicación está desplegada en un único servidor, el dominio apunta a él y el puerto 443 está abierto. Si hay varios servidores, hace falta un balanceador delante de ellos y el certificado se emite en dicho balanceador.

Secretos

Los valores de los secretos no se almacenan en deploy.yml. Kamal los lee desde archivos en el directorio .kamal/: primero .kamal/secrets-common, luego .kamal/secrets (o un archivo para el entorno concreto). El formato es como dotenv; además se puede obtener el valor con un comando:

KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
DATABASE_URL=$(cat /secure/database_url)

Para gestores de contraseñas existe el comando kamal secrets, que extrae los valores del almacén durante el despliegue. Los propios archivos de secretos no deben subirse al repositorio, y las variables de la sección secret se entregan en el servidor en un archivo de entorno separado, no en los parámetros de inicio del contenedor.

Servicios auxiliares

Kamal puede lanzar bases de datos, Redis y otros servicios junto a la aplicación como accessories — contenedores separados en el servidor indicado. Para proyectos pequeños esto es conveniente. En sistemas de producción con datos valiosos la base normalmente se ubica en un servidor separado o en un servicio gestionado: Kamal no resuelve copias de seguridad, actualizaciones ni alta disponibilidad de la base.

Cuándo conviene Kamal

• Varios servidores o uno, carga estable, equipo pequeño sin un ingeniero de infraestructura dedicado.
• Se necesita migrar desde una plataforma en la nube que cobra por cada recurso a servidores propios, sin pasarse a Kubernetes.
• Servidores en cualquier centro de datos: lo importante es solo el acceso SSH y Docker. Para una empresa rusa pueden ser VPS de proveedores rusos.

Cuándo no conviene:

• se requiere escalado automático para picos bruscos de carga;
• decenas de servicios con conectividad de red compleja, donde ya se necesitan capacidades de orquestador;
• el equipo ya trabaja con Kubernetes y sabe mantenerlo.

Una comparación general de plataformas para despliegue está en la primera parte del ciclo. Una tarea similar la resuelve Dokploy, pero este tiene interfaz web y panel propio, mientras que Kamal es solo línea de comandos y un archivo de configuración en el repositorio.

Errores típicos

• No hay ruta de comprobación de disponibilidad. Si la aplicación no responde en /up (o en la ruta configurada), el despliegue no cambiará el tráfico.
• El archivo .kamal/secrets fue subido al repositorio junto con los valores reales.
• HTTPS automático en varios servidores. El certificado Let’s Encrypt a través de kamal-proxy se emite solo cuando se despliega en un único servidor.
• La arquitectura de la imagen no coincide con el servidor. Una imagen construida en un Mac con procesador ARM no se ejecutará en un servidor x86-64 sin indicar builder.arch.
• Base de datos como accessory sin copias de seguridad.