Guida pratica per il deployment di applicazioni Rails con Kamal 2

Introduzione

Kamal 2 è uno strumento per il deployment di applicazioni Rails, ma attualmente la documentazione disponibile è piuttosto dispersa e incompleta. In questo articolo condividerò le mie esperienze pratiche durante il processo di deployment con Kamal 2, sperando di fornire qualche riferimento utile.

Esempio di configurazione completa

# config/deploy.staging.yml

# nome del servizio puma
service: ai-hub-server-staging
# namespace / nome dell'immagine
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 si connette al tuo container sulla porta 80, usa `app_port` per specificare una porta diversa.
  app_port: 3000

registry:
  # il tuo nome utente e password di Docker Hub
  # utilizza il servizio di Alibaba Cloud
  server: crpi-9ja5ymdca5joh9vj.cn-shenzhen.personal.cr.aliyuncs.com
  username: 396803555@qq.com
  password:
    - AI_HUB_KAMAL_REGISTRY_PASSWORD

builder:
  arch: amd64
  # specifica il percorso del Dockerfile
  dockerfile: Dockerfile.staging

# configurazione dei log
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
    # deve essere dichiarato qui, altrimenti database.yml non può accedervi
    # connection to server at "172.17.1.2", port 5432 failed: fe_sendauth: no password supplied
    - AI_HUB_KAMAL_POSTGRES_PASSWORD

accessories:
  db:
    image: postgres:15
    host: your-host # il tuo IP del server
    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 # il tuo IP del server

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

Esempio di configurazione del database:

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

Descrizione della rete Docker

Kamal 2 crea una rete Docker chiamata kamal e aggiunge tutti i container a essa. Pertanto:

• non è possibile utilizzare IP o localhost
• l’indirizzo Redis dovrebbe essere redis://ai-hub-server-staging-redis:6379/0
• l’indirizzo del database dovrebbe essere ai-hub-server-staging-db

Ad esempio, se nel progetto si utilizza redis, accedi al server e usa docker ps per trovare il nome ai-hub-server-staging-redis
quindi REDIS_HOST dovrebbe essere 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

Passaggi per il deployment

1. Inizializza Kamal

kamal init

2. Configura deploy.yml e Dockerfile

3. Esegui il comando setup

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

Se ci sono accessori come pg, redis, ecc., i container verranno avviati e potrai vedere i nomi dei container.

4. Regola la configurazione di 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. Deploy dell’applicazione

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

Nota: ogni volta che esegui il deploy, viene utilizzato il codice dell’ultimo commit locale. Quindi ricorda di fare il commit dopo le modifiche.

Domande frequenti e soluzioni

1. Accesso lento a Docker Hub

Soluzioni:

• Utilizza il servizio di immagini di Alibaba Cloud
• Oppure configura un proxy nel Docker Daemon:

Anche se utilizzi il servizio di immagini di Alibaba Cloud, alla fine il deployment potrebbe comunque non riuscire a pullare l’immagine kamal-proxy. Configura un proxy per risolvere il 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. Problema con le variabili d’ambiente .kamal/secrets

Devi configurare le variabili d’ambiente di 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. I log di Rails non vengono visualizzati in Docker

Aggiungi nel file config/environments/staging.rb:

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

Controlla il formato dei log di Docker:

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

Configurazione relativa a kamal:

logging:
	# di default è questo
  driver: json-file
  options:
    max-size: 100m

4. Configurazione SSL

Kamal-proxy supporta la configurazione automatica di HTTPS tramite Let’s Encrypt:

proxy:
  ssl: true
  host: ai-hub-kamal.beansmile-dev.com
  # kamal-proxy si connette al tuo container sulla porta 80, usa `app_port` per specificare una porta diversa.
  app_port: 3000

Comandi comuni

Accedi al container per vedere i dettagli

docker exec -it CONTAINER_ID bash

Rilascia il lock del deployment

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

Console di Rails

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

# utilizzo da linea di comando
kamal console -c "config/deploy.staging.yml"

Visualizza i log remoti

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

Parametri di configurazione utili

Mappatura della porta del server Rails

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

Disabilita Kamal Proxy

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

Conclusione

Kamal 2 è uno strumento di deployment per applicazioni Rails basato su Docker. Rispetto alle tradizionali soluzioni di deployment come Capistrano, presenta i seguenti vantaggi e svantaggi:

Vantaggi di Kamal 2

1. Deployment containerizzato

   • Ambiente applicativo completamente isolato, evitando conflitti di dipendenze di sistema
   • Garantisce coerenza tra ambiente di sviluppo e produzione
   • Facilita l’espansione orizzontale e la migrazione

2. Configurazione semplice

   • Unico file di configurazione YAML
   • Supporto SSL integrato, con richiesta e rinnovo automatico dei certificati
   • Controllo della salute e deployment senza downtime pronti all’uso

3. Amministrazione amichevole

   • Gestione dei log e limitazione della capacità integrate
   • Supporto per rollback con un clic
   • Fornisce strumenti di debug remoto convenienti

Vantaggi di Capistrano

1. Maturità e stabilità

   • Storia d’uso lunga, risorse comunitarie abbondanti
   • Soluzioni per problemi ben definite
   • Molti script di deployment pronti all’uso

2. Basso utilizzo di risorse

   • Non richiede l’esecuzione di container, con minori costi di sistema
   • Adatto per server di piccole dimensioni con risorse limitate

3. Elevata flessibilità

   • Possibilità di controllare in dettaglio ogni fase del processo di deployment
   • Supporto per logiche di deployment personalizzate complesse
   • Maggiore facilità di integrazione con sistemi esistenti

Kamal 2 rappresenta la tendenza del deployment nell’era della containerizzazione, ma ciò non significa che sia adatto a tutti gli scenari. Quando si sceglie uno strumento di deployment, è importante considerare fattori come la dimensione del progetto, la situazione del team e le risorse del server. Indipendentemente dallo strumento scelto, la cosa più importante è assicurarsi che soddisfi le tue esigenze di deployment.