O que o Kamal realmente faz

O Kamal é uma ferramenta de deploy que pressupõe que você tem servidores e Docker, e nada mais. Não há Kubernetes, plano de controle nem plataforma gerenciada, só SSH e contêineres. É um conjunto de peças móveis menor que o da maioria das alternativas, e é por isso que o Kamal cabe num único VPS.

O modelo inteiro num parágrafo

O Kamal constrói uma imagem Docker na sua máquina e a envia para um registro. Depois se conecta aos seus servidores por SSH, baixa a imagem lá e sobe contêineres a partir dela. Um proxy reverso na frente encaminha o tráfego para o contêiner que estiver saudável no momento.

Esse é o modelo inteiro. Todo o resto do config/deploy.yml é detalhe em cima desses cinco passos.

O que o arquivo desta aplicação diz

service: newbieonrails
image: gxolivei/nor

servers:
  web:
    hosts:
      - <%= ENV.fetch("NOR_SERVER_IP") %>

Há um servidor, identificado por uma variável de ambiente em vez de estar escrito no repositório. ENV.fetch sem valor padrão faz uma variável ausente falhar de forma ruidosa na hora do deploy, antes que algo seja implantado num lugar inesperado.

Isso funciona porque o arquivo é ERB: o Kamal o renderiza antes de interpretar o YAML.

flowchart TB
  L["sua máquina"] --> B["docker build"]
  B --> R["envio para ghcr.io"]
  R --> S["ssh no servidor"]
  S --> P["docker pull"]
  P --> C["sobe o contêiner novo"]
  C --> H["verificação de saúde em /up"]
  H --> X["o proxy troca o tráfego. o antigo para"]

O passo do registro que as pessoas pulam

registry.server: ghcr.io significa que a imagem passa pelo registro de contêineres do GitHub, e não vai direto do seu laptop para o servidor.

Esse desvio faz um trabalho real. O servidor nunca precisa do seu código-fonte nem de ferramentas de build. Cada imagem recebe como tag o commit do git, então reverter significa baixar uma tag anterior em vez de reconstruir.

builder.arch: amd64 força a arquitetura do build, o que importa numa máquina Apple Silicon. Sem isso, você construiria uma imagem arm64, e o servidor não conseguiria rodá-la.

Por que isto em vez de uma plataforma

Uma plataforma gerenciada faz tudo isso e mais. O que o Kamal oferece em troca é que cada peça fica visível. Os contêineres são contêineres Docker, o proxy é um processo que dá para inspecionar, e o servidor aceita que você entre por SSH.

A troca é assumir a responsabilidade operacional em troca de legibilidade e custo. Para uma aplicação num único VPS, essa troca costuma ser favorável, e foi a que este projeto fez.

Pontos-chave

• O Kamal constrói uma imagem, envia para um registro e sobe contêineres por SSH.
• O config/deploy.yml é ERB, então o endereço do servidor pode vir do ambiente.
• ENV.fetch sem valor padrão falha de forma ruidosa em vez de implantar no lugar errado.
• O registro faz o servidor não precisar de código-fonte nem de ferramentas de build, e reverter é trocar de tag.
• A troca é assumir a responsabilidade operacional em troca de legibilidade e custo.