De um app para uma frota

O curso de fundamentos colocou uma aplicação num servidor: kamal setup, um config/deploy.yml com service, image, uma lista de servidores, um proxy com SSL e um accessory de banco. Aquela configuração é honesta, e deixa de bastar assim que aparecem necessidades reais.

Elas costumam aparecer assim:

• Uma segunda aplicação precisa morar no mesmo servidor, porque um segundo servidor custa dinheiro que você prefere não gastar.
• Os jobs em segundo plano crescem além do processo web e precisam dos próprios containers, com os próprios limites de memória.
• Você quer um ambiente de staging que compartilhe a configuração de produção em vez de ser um fork dela.
• O build leva oito minutos no seu notebook e você gostaria que levasse um.
• Um deploy dá errado às 23h40 e você precisa da versão anterior de volta em menos de um minuto.

Nada disso pede outra ferramenta. Quase tudo isso são chaves do mesmo arquivo, e este curso é sobre essas chaves.

O formato de um host de produção

Um host Kamal é mais do que "o seu app". É um conjunto pequeno e previsível de containers:

flowchart TB
  I["Internet :443"] --> P["kamal-proxy"]
  P -->|"host: nor.app"| A1["nor-web"]
  P -->|"host: blog.nor.app"| A2["blog-web"]
  A1 --> W1["nor-worker (sem proxy)"]
  A1 --> DB[("accessory postgres")]
  A2 --> DB

Um proxy é dono das portas 80 e 443. Todo o resto é um container de app para onde o proxy roteia, um container de role para onde nada roteia, ou um accessory que o Kamal inicia uma vez e deixa quieto. Saber qual dos três é cada container responde a maior parte das dúvidas sobre por que ele se comporta como se comporta.

O arquivo único, visto de cima

Quase toda capacidade deste curso é uma chave de topo no config/deploy.yml. As duas exceções ficam ao lado dele: um destino acrescenta um pequeno config/deploy.<destino>.yml, mesclado por cima deste arquivo, e os hooks são scripts em .kamal/hooks. Primeiro, o mapa inteiro:

service: nor            # prefixo do nome do container — a identidade do app no host
image: gxolivei/nor     # o que é enviado ao registry

servers:                # roles: quais containers rodam onde, com qual comando
  web:
    hosts: [ "203.0.113.10" ]
  worker:
    hosts: [ "203.0.113.10" ]
    cmd: bin/jobs

proxy:                  # roteamento: qual hostname chega neste app
  host: nor.app
  ssl: true

builder:                # como a imagem é construída, e onde
  arch: amd64

accessories:            # serviços que o Kamal roda mas não faz deploy
  db:
    image: postgres:17

registry: ...           # onde as imagens moram
env: ...                # variáveis claras e secretas
aliases: ...            # seus próprios comandos

O curso de fundamentos usou service, image, servers como lista plana, proxy, registry, env e accessories. Este curso volta a servers e o transforma em roles, volta a proxy e o torna multi-app, e acrescenta builder, destinos, hooks e rollback.

O que o Kamal continua não sendo

Dois limites continuam valendo, por mais configuração que você aprenda.

Primeiro, o Kamal não faz agendamento. Você nomeia hosts. Se um host está fora do ar, o Kamal não move os containers dele para outro lugar: o deploy naquele host falha e os outros passam. Nesta escala isso é uma vantagem, porque o deploy continua fácil de entender. É disso que você abre mão ao escolher Kamal em vez de Kubernetes.

Segundo, o Kamal não gerencia os seus dados. Um accessory é um container que o Kamal inicia com um volume. Backup, replicação e upgrade daquele PostgreSQL são seus. Muitos times rodam o app com Kamal e o banco num serviço gerenciado por esse motivo, e essa é uma configuração legítima.

O que este curso cobre

1. De um app para uma frota (você está aqui).
2. Dois apps, um host.
3. Roles: web, workers e os que não recebem tráfego.
4. Destinos: staging e produção a partir de um arquivo.
5. Builds que não desperdiçam a sua tarde.
6. Hooks, rollbacks e o deploy que dá errado.
7. Juntando tudo: uma configuração de produção.

No fim você terá lido e escrito um deploy.yml que roda duas aplicações e um worker num host, com destino de staging, builder remoto e um gate de pre-deploy. E vai saber o que cada linha faz.

Pontos-chave

• A configuração dos fundamentos está correta e se esgota no segundo app, num worker, num segundo ambiente, em builds lentos ou num deploy ruim.
• Um host Kamal é proxy, containers de app, containers de role e accessories. Saber qual é qual explica quase todo comportamento.
• Quase toda capacidade deste curso é uma chave de topo no config/deploy.yml; destinos acrescentam um arquivo por cima, e hooks são scripts em .kamal/hooks.
• O Kamal não agenda entre hosts e não gerencia os seus dados; os dois limites são deliberados.