Implante uma aplicação web com o Kamal

Pré-requisitos

• Uma máquina de implantação (seu computador ou um executor de CI) com Ruby instalado (2.7 ou superior). É nela que o Kamal será executado.
• Um VPS de destino com acesso SSH (como root ou um usuário com sudo). Não é necessário pré-instalar nenhum software.
• Uma conta em um registro Docker (Docker Hub, GHCR ou qualquer registro privado) com credenciais.
• Sua aplicação web, com um Dockerfile na raiz do repositório que compile uma imagem executável.
• Um nome de domínio com um registro A/AAAA apontando para o IP do VPS.

O Kamal é uma ferramenta que roda no cliente. Ele nunca é executado no servidor. O VPS é uma máquina vazia que precisa apenas aceitar conexões SSH e ter as portas 80 e 443 abertas no firewall.

Etapa 1: Instalar o Kamal na máquina de implantação

Instale a gem Ruby do Kamal:

gem install kamal

Verifique se ela está disponível:

kamal version

É só isso. Não instale o Kamal no VPS. O VPS receberá comandos desta máquina por SSH.

Etapa 2: Inicializar o Kamal na aplicação

Acesse a raiz da sua aplicação e execute:

cd /path/to/your-app
kamal init

Isso cria dois itens:

• config/deploy.yml: o arquivo de configuração da implantação
• .kamal/secrets: um arquivo local para valores confidenciais (não versione esse arquivo)

Você deverá editar os dois arquivos nas próximas etapas.

Etapa 3: Configurar deploy.yml

Abra config/deploy.yml e substitua o modelo por valores do seu projeto. Uma configuração mínima funcional:

service: myapp
image: your-registry-user/myapp

servers:
  web:
    - your-domain.com

proxy:
  ssl: true
  host: your-domain.com
  app_port: 3000

registry:
  server: ghcr.io
  username: your-registry-user
  password: KAMAL_REGISTRY_PASSWORD

env:
  clear:
    RAILS_ENV: production
  secret:
    - RAILS_MASTER_KEY
    - DATABASE_URL

Principais campos:

• service: nome da aplicação (usado para nomear o contêiner)
• image: nome completo da imagem no registro
• servers.web: lista dos nomes de host ou IPs do VPS
• proxy: o kamal-proxy encerra o SSL com o Let's Encrypt e encaminha o tráfego para app_port
• registry: credenciais para enviar e baixar imagens
• env: variáveis de ambiente repassadas ao contêiner

Para serviços auxiliares, como PostgreSQL ou Redis, você pode adicionar uma seção accessories, mas comece sem eles na primeira implantação.

Etapa 4: Definir os segredos

Edite .kamal/secrets para definir os valores referenciados em deploy.yml:

KAMAL_REGISTRY_PASSWORD=your-personal-access-token
RAILS_MASTER_KEY=your-rails-master-key
DATABASE_URL=postgres://user:pass@host/db

O arquivo .kamal/secrets deve permanecer apenas na máquina local. No CI, injete esses valores pelo repositório de segredos do CI e repasse-os pelas variáveis de ambiente lidas pelo Kamal.

Nunca inclua .kamal/secrets no controle de versão. O diretório .kamal já consta no .gitignore por padrão.

Etapa 5: Preparar o VPS com kamal setup

Este é o comando principal. Ele faz tudo de uma vez:

kamal setup

O Kamal se conectará ao VPS por SSH e:

1. Instalará o Docker, caso ainda não esteja instalado
2. Iniciará o contêiner kamal-proxy, que usa as portas 80 e 443
3. Obterá automaticamente um certificado SSL Let's Encrypt para seu domínio
4. Baixará a imagem da aplicação do registro
5. Iniciará o contêiner da aplicação atrás do proxy

Sem instalação manual do Docker, sem configuração do Nginx, sem certbot. Com um único comando, o VPS passa de uma máquina vazia a um servidor com sua aplicação em execução.

Etapa 6: Implantar atualizações

Depois da configuração inicial, implante novas versões com:

kamal deploy

O comando compila ou baixa a nova imagem, interrompe o contêiner antigo de forma controlada, inicia o novo e verifica a checagem de integridade. O Kamal reverte automaticamente se a verificação falhar.

Manutenção

• Atualizar o Kamal: gem update kamal na máquina de implantação
• Conferir os logs: kamal app logs
• Executar um comando em um contêiner: kamal app exec 'rails console'
• Reiniciar a aplicação: kamal app restart
• Reverter: kamal deploy --version=<previous-version>
• Atualizar o kamal-proxy no servidor: kamal proxy upgrade

O Kamal não gerencia bancos de dados. Faça backup dos dados persistentes separadamente e documente como recriar o servidor usando apenas o repositório e o repositório de segredos.