Funcionamento
Preparar sua aplicação
Leia a porta de process.env.PORT
Não fixe a porta no código. Escute em 0.0.0.0, nunca em localhost. Se ignorar: O roteador entrega na porta declarada e ninguém atende. O visitante recebe 502 com o container saudável.
Rode as migrações na inicialização, não na construção
Um migrate deploy antes de subir o servidor. Durante a construção da imagem não existe banco para conectar. Se ignorar: O banco fica com zero tabelas e o app responde erro na primeira consulta. Foi o defeito mais comum nas migrações reais.
Falhe alto quando a migração falhar
Se o migrate der erro, o processo deve morrer com a mensagem no log — não subir mesmo assim. Se ignorar: O app fica no ar servindo erro, o painel mostra verde, e ninguém descobre até um cliente reclamar.
Variáveis NEXT_PUBLIC_* são argumentos de construção
No Next.js elas são gravadas dentro do pacote durante o build. Declare cada uma como ARG e promova a ENV antes da linha que constrói. Se ignorar: O valor de desenvolvimento fica embutido para sempre. A API de produção continua apontando para localhost.
Nada importante no disco do container
Upload, imagem, anexo: mande para o armazenamento S3. Disco de container some quando a cópia é recriada. Se ignorar: Os arquivos desaparecem no próximo deploy, sem aviso e sem como recuperar.
Não guarde estado só na memória do processo
Sessão, fila, cache compartilhado: coloque no banco ou no Redis. Com mais de uma cópia, cada processo tem a sua memória. Se ignorar: O usuário perde a sessão a cada requisição que cai noutra cópia, e escritas somem sem erro nenhum.
Um agendador embutido exige uma cópia só
Se o app tem cron interno, diga isso a quem for publicar. A alternativa é mover a rotina para um serviço próprio. Se ignorar: Cobrança em duplicidade, mensagem enviada duas vezes, cliente bloqueado por engano.
Responda algo em /
Qualquer resposta abaixo de 500 serve — inclusive um redirecionamento para o login. É por aí que a plataforma sabe que o app está vivo. Se ignorar: O app é considerado fora do ar e o dono recebe aviso de queda que não existe.
Log no stdout, sem arquivo
Escreva na saída padrão. Não abra arquivo de log dentro do container. Se ignorar: O log fica preso num disco que ninguém alcança, exatamente quando você precisa dele.
Todo segredo vem do ambiente
Chave de API, segredo de token, credencial de terceiro: só de variável de ambiente. Nunca comitado, nunca com valor padrão que funcione. Se ignorar: O segredo vaza no repositório e passa a valer para qualquer um que clone o código.
Monorepo: um serviço por programa, no mesmo projeto
Site e API do mesmo repositório entram como dois serviços do mesmo projeto, cada um com seu Dockerfile e sua porta. Não crie dois projetos. Se ignorar: Com dois projetos, os segredos precisam ser copiados de um para o outro na mão — e no dia em que um for trocado e o outro não, o token deixa de ser aceito e ninguém entende por quê.
Dockerfile: diga o caminho, mantenha o contexto na raiz
Em monorepo, informe o caminho completo do Dockerfile do serviço. O contexto continua na raiz para achar o lockfile compartilhado. Se ignorar: A construção morre com "open Dockerfile: no such file or directory" num repositório que tem Dockerfile.