Guía práctica para desplegar aplicaciones Rails usando Kamal 2

Introducción

Kamal 2 es una herramienta para desplegar aplicaciones Rails, pero actualmente la documentación relacionada es bastante dispersa y no está completa. Este artículo compartirá la experiencia práctica del autor en el proceso de despliegue con Kamal 2, con la esperanza de que sirva como referencia para todos.

Ejemplo de configuración completa

# config/deploy.staging.yml

# Nombre del servicio puma
service: ai-hub-server-staging
# Espacio de nombres / Nombre de la imagen
image: jayce9210/ai-hub-server-staging

servers:
  web:
    hosts:
      - your-host
  sidekiq:
    cmd: bundle exec sidekiq
    hosts:
      - your-host

proxy:
  ssl: true
  host: ai-hub-kamal.beansmile-dev.com
  # kamal-proxy se conecta a tu contenedor a través del puerto 80, usa `app_port` para especificar un puerto diferente.
  app_port: 3000

registry:
  # Tu nombre de usuario y contraseña de Docker Hub
  # Usando el servicio de Alibaba Cloud
  server: crpi-9ja5ymdca5joh9vj.cn-shenzhen.personal.cr.aliyuncs.com
  username: 396803555@qq.com
  password:
    - AI_HUB_KAMAL_REGISTRY_PASSWORD

builder:
  arch: amd64
  # Especifica la ruta del Dockerfile
  dockerfile: Dockerfile.staging

# Configuración de logs
logging:
  options:
    max-size: 100m

env:
  clear:
    HOST: http://ai-hub-kamal.beansmile-dev.com
    DB_HOST: ai-hub-server-staging-db
    REDIS_HOST: redis://ai-hub-server-staging-redis:6379/0
  secret:
    - RAILS_MASTER_KEY
    # Necesita ser declarado aquí, de lo contrario database.yml no podrá obtenerlo
    # conexión al servidor en "172.17.1.2", puerto 5432 falló: fe_sendauth: no se proporcionó contraseña
    - AI_HUB_KAMAL_POSTGRES_PASSWORD

accessories:
  db:
    image: postgres:15
    host: your-host # Tu IP del servidor
    env:
      clear:
        POSTGRES_USER: deploy
        POSTGRES_DB: ai-hub-server-staging
        POSTGRES_PASSWORD: AI_HUB_KAMAL_POSTGRES_PASSWORD
    volumes:
      - /var/lib/postgresql/data:/var/lib/postgresql/data
  redis:
    image: redis:7
    host: your-host # Tu IP del servidor

aliases:
  console: app exec --reuse -i "bin/rails console"

Ejemplo de configuración de base de datos:

# database.yml.example
staging:
  <<: *default
  database: ai_hub_server_staging
  username: deploy
  password: <%= ENV['AI_HUB_KAMAL_POSTGRES_PASSWORD'] %>

Descripción de la red Docker

Kamal 2 creará una red Docker llamada kamal y añadirá todos los contenedores a ella. Por lo tanto:

• No se puede usar IP o localhost
• La dirección de Redis debe ser redis://ai-hub-server-staging-redis:6379/0
• La dirección de la base de datos debe ser ai-hub-server-staging-db

Por ejemplo, si el proyecto usa redis, entra en el servidor y ejecuta docker ps para encontrar el nombre ai-hub-server-staging-redis, entonces REDIS_HOST debería ser redis://ai-hub-server-staging-redis:6379/0

env:
  clear:
    HOST: http://ai-hub-kamal.beansmile-dev.com
    DB_HOST: ai-hub-server-staging-db
    REDIS_HOST: redis://ai-hub-server-staging-redis:6379/0

Pasos de despliegue

1. Inicializar Kamal

kamal init

2. Configurar deploy.yml y Dockerfile

3. Ejecutar el comando setup

kamal setup -c "config/deploy.staging.yml"

Si hay accesorios, como pg, redis, etc., los contenedores se iniciarán y podrás ver los nombres de los contenedores.

4. Ajustar la configuración de Redis

env:
  clear:
    HOST: http://ai-hub-kamal.beansmile-dev.com
    DB_HOST: ai-hub-server-staging-db
    REDIS_HOST: redis://ai-hub-server-staging-redis:6379/0

5. Desplegar la aplicación

kamal deploy -c "config/deploy.staging.yml"

Es importante tener en cuenta que cada despliegue utiliza el código del último commit local. Por lo tanto, recuerda hacer commit después de realizar cambios.

Problemas comunes y soluciones

1. Acceso lento a Docker Hub

Soluciones:

• Usar el servicio de imágenes de Alibaba Cloud
• O configurar un proxy en Docker Daemon:

Incluso usando el servicio de imágenes de Alibaba Cloud, si al final no se puede pull de la imagen kamal-proxy, configurar un proxy resolverá el problema.

# /etc/systemd/system/docker.service.d/http-proxy.conf
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:10801"
Environment="HTTPS_PROXY=http://127.0.0.1:10801"

2. Problemas con las variables de entorno .kamal/secrets

Necesitas configurar en las variables de entorno del sistema:

# bash.rc / zshrc

export AI_HUB_KAMAL_REGISTRY_PASSWORD=
export AI_HUB_KAMAL_POSTGRES_PASSWORD=

# .kamal/secrets
AI_HUB_KAMAL_REGISTRY_PASSWORD=$AI_HUB_KAMAL_REGISTRY_PASSWORD
AI_HUB_KAMAL_POSTGRES_PASSWORD=$AI_HUB_KAMAL_POSTGRES_PASSWORD

3. Los logs de Rails no se pueden imprimir en Docker

Añadir en config/environments/staging.rb:

config.logger = ActiveSupport::Logger.new(STDOUT)
  .tap  { |logger| logger.formatter = ::Logger::Formatter.new }
  .then { |logger| ActiveSupport::TaggedLogging.new(logger) }

Confirma el formato de los logs de docker:

> docker inspect --format='{{.HostConfig.LogConfig.Type}}' 9b0b24c16554
json-file

Configuraciones relacionadas con kamal:

logging:
	# Este es el valor por defecto
  driver: json-file
  options:
    max-size: 100m

4. Configuración de SSL

Kamal-proxy soporta la configuración automática de HTTPS a través de Let’s Encrypt:

proxy:
  ssl: true
  host: ai-hub-kamal.beansmile-dev.com
  # kamal-proxy se conecta a tu contenedor a través del puerto 80, usa `app_port` para especificar un puerto diferente.
  app_port: 3000

Comandos útiles

Entrar en el contenedor para ver detalles

docker exec -it CONTAINER_ID bash

Liberar el bloqueo de despliegue

kamal lock release
# o
kamal lock release -c "config/deploy.staging.yml"

Consola de Rails

# deploy.staging.yml
# Configurar alias
aliases:
  console: app exec --reuse -i "bin/rails console"

# Usar en la línea de comandos
kamal console -c "config/deploy.staging.yml"

Ver logs remotos

kamal app logs  -c "config/deploy.staging.yml"

Parámetros de configuración útiles

Mapeo de puertos del servidor Rails

servers:
  web:
    hosts:
      - your-host
    options:
      publish:
        - "4022:3000"

Deshabilitar Kamal Proxy

servers:
  web:
    hosts:
      - your-host
    proxy: false

Conclusión

Kamal 2 es una herramienta de despliegue de aplicaciones Rails basada en Docker. En comparación con las soluciones de despliegue tradicionales como Capistrano, tiene las siguientes ventajas y desventajas:

Ventajas de Kamal 2

1. Despliegue en contenedores

   • Entorno de aplicación completamente aislado, evitando conflictos de dependencias del sistema
   • Asegura la consistencia entre el entorno de desarrollo y el de producción
   • Facilita la escalabilidad horizontal y la migración

2. Configuración sencilla

   • Archivo de configuración YAML único
   • Soporte SSL integrado, solicitud y renovación automática de certificados
   • Chequeo de salud y despliegue sin tiempo de inactividad listos para usar

3. Amigable para operaciones

   • Gestión de logs y límites de capacidad integrados
   • Soporta retrocesos con un solo clic
   • Proporciona herramientas de depuración remota convenientes

Ventajas de Capistrano

1. Maduro y estable

   • Historia de uso larga, recursos comunitarios abundantes
   • Soluciones a problemas bien desarrolladas
   • Gran cantidad de scripts de despliegue listos para usar

2. Bajo consumo de recursos

   • No requiere ejecutar contenedores, menor sobrecarga del sistema
   • Adecuado para servidores pequeños con recursos limitados

3. Alta flexibilidad

   • Permite un control detallado de cada paso del proceso de despliegue
   • Soporta lógica de despliegue personalizada compleja
   • Más fácil de integrar con sistemas existentes

Kamal 2 representa la tendencia de despliegue de la era de los contenedores, pero eso no significa que sea adecuado para todos los escenarios. Al elegir una herramienta de despliegue, es necesario considerar factores como el tamaño del proyecto, la situación del equipo y los recursos del servidor. Independientemente de la herramienta elegida, lo más importante es asegurarse de que satisfaga tus necesidades de despliegue.