Por que um deploy de fato falha, motivo por motivo

“O deploy falhou” não é um problema só — são pelo menos uma dúzia de problemas diferentes que acabam aparecendo do mesmo jeito para quem só está olhando rapidamente para um painel. Saber qual deles de fato aconteceu é a maior parte da correção, que é por que a página de um deploy falho começa com por que falhou: a causa, a correção, e a linha de log que prova isso.

Os dois que parecem idênticos, mas não são

A confusão mais comum de todas: “a build ficou sem tempo” (parou num limite de 60 minutos; a próxima tentativa reaproveita o que já foi construído) contra “a build ficou sem memória” (uma etapa da build foi morta de vez por exceder o que o servidor de build tem). Os dois parecem “a build simplesmente não terminou” numa olhada rápida num status vermelho — a correção de um é paciência e reaproveitar o trabalho parcial, a correção do outro é um servidor de build maior ou fazer deploy de uma imagem já construída em vez de construir na plataforma.

O app roda, mas de algum jeito não roda

Esse merece seu próprio destaque porque raramente é óbvio a partir do código do próprio app: o container está rodando, mas nada responde HTTP. Não travou — rodando, saudável em toda métrica exceto a que importa. A causa real quase sempre é uma correção de uma linha: o app precisa escutar em 0.0.0.0, não em 127.0.0.1, e na porta em $PORT, não uma fixa no código. Um app perfeitamente correto, rodando perfeitamente correto, que só conversa consigo mesmo.

Um parente próximo: o comando rodou na pasta errada — a imagem não contém o app onde o comando de início espera, geralmente porque um Dockerfile escrito para desenvolvimento local (esperando um bind mount) foi usado para uma build real. Trocar para o Railpack em vez do Dockerfile do próprio repositório é a correção quando essa é a situação real.

As falhas em formato de banco de dados, de três jeitos diferentes

• O banco de dados não estava acessível — mais confuso quando acontece durante a build, porque um app conectando ao banco de dados enquanto compila assets ou roda uma verificação em tempo de build está tentando acessar uma infraestrutura que aquela etapa de build nunca teria acesso.
• O usuário do banco de dados não tem uma permissão — uma migração precisa de algo que o usuário de banco de dados do app ainda não tem. A correção é quase suspeitosamente simples: refaça o deploy uma vez, já que as permissões são atualizadas em cada deploy.
• A etapa de release falhou — geralmente migrações, rodadas uma vez antes de a nova versão receber tráfego. A primeira linha do erro real aparece direto na página do deploy, não escondida num dump de log inteiro.

Os dois que são o mesmo problema vestindo roupas diferentes

Uma variável obrigatória não está definida (o app para no boot porque algo que ele precisa está vazio) e o app precisa de credenciais para um serviço externo (uma API de terceiros, armazenamento em nuvem, e-mail, pagamentos — nenhuma chave configurada) são a mesma causa raiz — uma variável de ambiente faltando — com especificidades diferentes. Um é “falta algo,” o outro nomeia qual categoria de algo.

A imagem não pôde ser baixada (não existe, tag errada, ou privada sem credenciais) e o nome da imagem é inválido (caracteres que o Docker não aceita) são o par equivalente para deploys baseados em imagem em vez de baseados em build.

Por que nomear a causa exata importa mais do que parece

Cada uma dessas produz o mesmo sintoma visível para quem olha rapidamente um painel: um status vermelho e um deploy falho. A correção real só fica óbvia depois que a causa específica é nomeada — “ficou sem tempo” e “ficou sem memória” precisam de respostas opostas; um pipeline de deploy confiável tem menos a ver com nunca falhar e mais com uma falha que te diz imediata e especificamente o que fazer a seguir.

Referência completa, toda causa: Troubleshooting failed deploys.