Learn safe, practical deployment patterns for solo AI engineers — from build pipelines to rollback strategies, grounded in real Mac Mini + Cloudflare Tunnel self-hosting.
Quando implantei a plataforma de IA clínica, tinha uma restrição que moldou cada decisão: eu era o único engenheiro e também o único de plantão.
Sem equipe de operações. Sem SRE de prontidão. Sem runbook com vinte pessoas para acionar.
Essa restrição acabou sendo esclarecedora. Me forçou a perguntar: qual é a história de implantação mais simples que ainda me permite fazer rollback em menos de um minuto se algo quebrar?
A resposta não era Kubernetes. Não eram Helm charts ou pools de nós GPU. Eram três coisas:
npm run build:production — um passo de build determinísticosystemd no Mac MiniEsse é o playbook completo de operações. E funciona de forma confiável, dia após dia, sem equipe de ops.
Restrição Real Gera Bom Design: A implantação clínica de IA me ensinou que simplicidade de implantação não é um compromisso — é uma decisão de engenharia. Cada camada de infraestrutura que você adiciona é uma camada que você precisa depurar às 2h da manhã quando algo quebra.
Pense em implantar como enviar carga em um navio. Você não troca o motor no meio do oceano — você prepara tudo no porto, testa, e então parte. A chave é: quando algo dá errado no mar, você precisa de um bote salva-vidas pronto. Esse bote é sua história de rollback, e você a constrói antes de precisar dela.
Ao final deste módulo, você irá:
build:production → restart → smoke-checkOs padrões clássicos de zero downtime (blue-green, canary) foram projetados para ambientes com múltiplos servidores. Quando você está rodando um único Mac Mini com um Cloudflare Tunnel, os mesmos conceitos ainda se aplicam — mas a implementação é mais simples.
O npm run start do Next.js serve a partir de .next/ — a saída compilada. Quando você executa build:production, ele escreve um novo diretório .next/. O servidor em execução continua servindo o .next/ antigo até você reiniciá-lo.
Isso te dá um padrão natural de "preparar então trocar":
A janela em que os usuários veem downtime é apenas o restart, que leva alguns segundos para um app Next.js. O tempo de build, por outro lado, leva minutos — e durante todo esse tempo a versão antiga está servindo tráfego normalmente.
Não Pule a Etapa de Verificação do Build: O erro de implantação mais comum é reiniciar o serviço antes de confirmar que o build teve sucesso. Se build:production sair com erro, pare — não reinicie. A versão antiga ainda está funcionando corretamente.
Mesmo sem múltiplos servidores, você pode aplicar o pensamento canary:
Isso tem fidelidade menor do que um canary real, mas detecta a maioria das classes de erros de produção antes que os usuários os vejam.
Aqui está o fluxo de trabalho de implantação que uso para este site. Ele é executado via um job do GitHub Actions que faz SSH no Mac Mini e executa um script de deploy.
O set -e no topo é fundamental: se build:production falhar, o script sai imediatamente. O serviço nunca é reiniciado com um build quebrado.
Por Que SSH em Vez de um Serviço de Deploy: Para uma única máquina auto-hospedada, SSH é o caminho mais simples e confiável. Sem servidor de webhook para manter, sem serviço adicional para proteger — apenas uma chave de deploy com permissões restritas no servidor.
Na primeira vez que implantei a plataforma de IA clínica no Mac Mini, o health check passou — mas um caminho específico de consulta RAG estava retornando resultados vazios. O erro estava em um caminho de código que o health check não exercitava.
Eu precisava fazer rollback rapidamente, enquanto o sistema estava em uso ativo.
O padrão que uso: crie uma tag em cada deploy de produção e mantenha a tag anterior como alvo de rollback.
Isso te dá um rollback de um comando para qualquer estado anterior de produção. Sem precisar adivinhar qual commit estava rodando em produção.
Um rollback só é útil se você consegue executá-lo sob pressão — às 23h, quando algo está quebrado, com usuários esperando.
Isso significa:
O Drill de Rollback: Uma vez por trimestre, escolha uma implantação recente aleatória e pratique o rollback para a anterior. Você encontrará atrito (tags faltando, permissões erradas) em um contexto seguro em vez de durante um incidente.
Gerenciamento de segredos é onde engenheiros solo fazem os atalhos mais perigosos. A plataforma de IA clínica lidava com dados sensíveis, então tive que acertar isso desde o primeiro dia.
Para o serviço systemd, use EnvironmentFile para injetar segredos sem colocá-los na unit file (que pode ser legível por todos):
O Erro de Segredos Mais Comum: Usar um único arquivo .env que "vive no servidor." Se o servidor for comprometido ou o arquivo for acidentalmente commitado, todas as suas chaves de API ficam expostas de uma vez. Use arquivos de ambiente por serviço com permissões restritas (600, owned pelo root) para limitar o raio de impacto.
Mantenha suas configurações de staging e produção estruturalmente idênticas — mesmos nomes de variáveis de ambiente, mesmo layout de arquivo de serviço. Apenas os valores diferem (chaves de API de staging, domínio de staging, etc.).
Isso significa que você pode testar seu processo de deploy em staging com confiança de que ele se comportará da mesma forma em produção.
Um health check responde a uma pergunta: "O serviço está vivo e capaz de lidar com requisições?"
Este endpoint é chamado pelo script de deploy após o restart. Se retornar algo diferente de 200, o deploy é considerado falho e o rollback é executado.
Diferentes verificações respondem a diferentes perguntas:
| Verificação | O Que Testa | Quando Executar |
|---|---|---|
| Health check | Serviço está vivo e configurado | Após cada restart |
| Smoke test | Caminhos críticos do usuário funcionam | Após cada deploy |
| Suite de testes completa | Todas as funcionalidades funcionam | No CI, antes do deploy |
Um smoke test exercita os caminhos mais críticos voltados ao usuário. Para este site, isso significa que a página inicial carrega, o índice do caminho de aprendizado retorna módulos e o endpoint de health retorna 200.
Automatize o Smoke Test: Adicione o smoke test ao seu script de deploy. Se alguma verificação falhar, acione o rollback automaticamente. Os 30 segundos que você gasta executando verificações valem muito menos do que o incidente que você previne.
1. Você executa 'npm run build:production' e ele sai com um código de status não-zero. O que você deve fazer a seguir?
Correct Answer: B
Com 'set -e' no seu script de deploy, o serviço nunca é reiniciado quando um build falha. A versão antiga continua servindo tráfego normalmente. Investigue o erro do build antes de prosseguir — não há urgência porque nada está quebrado ainda.
2. Qual é a principal vantagem de criar uma tag git em cada deploy de produção?
Correct Answer: B
Tags git fornecem uma referência nomeada e persistente para o código exato que estava rodando em produção em qualquer ponto. O rollback se torna uma operação de 'checkout da tag, build, restart' em vez de um teste de memória sobre qual commit foi implantado.
3. Por que o script de deploy usa 'set -e' no início?
Correct Answer: B
'set -e' é uma rede de segurança crítica. Sem ele, um passo de build com falha é ignorado silenciosamente e o próximo comando — reiniciar o serviço — ainda é executado, o que substituiria um serviço funcionando por um quebrado. Com 'set -e', o script para na primeira falha.
4. O health check da plataforma de IA clínica passou, mas um caminho de consulta específico estava quebrado. O que isso revela?
Correct Answer: B
Um health check responde 'o serviço está rodando?' Um smoke test responde 'os caminhos críticos estão funcionando?' Ambos são necessários. O health check passar corretamente indicou que o serviço iniciou — um smoke test exercitando o caminho de consulta RAG teria detectado o comportamento quebrado antes que os usuários o vissem.
5. Qual é o risco de armazenar todos os segredos de produção em um único arquivo .env compartilhado no servidor?
Correct Answer: B
Um único arquivo de segredos é um único ponto de comprometimento. Se um atacante ganhar acesso de leitura a esse arquivo, todas as suas chaves de API, credenciais de banco de dados e outros segredos ficam expostos simultaneamente. Arquivos de ambiente por serviço com permissões restritas (600, owned pelo root) limitam o raio de impacto de qualquer comprometimento único.
6. Você precisa testar uma nova integração de API em staging antes de implantar em produção. Qual abordagem melhor se encaixa no princípio de 'paridade de ambiente'?
Correct Answer: A
Paridade de ambiente significa que staging espelha a produção estruturalmente. Mesmos nomes de variável, mesma estrutura de arquivo de serviço, mesmo script de deploy. Apenas os valores diferem. Se o staging usa 'STAGING_ANTHROPIC_KEY' mas a produção usa 'ANTHROPIC_API_KEY', seus testes de staging não validam o que a produção fará de fato.
7. Pensando nos seus próprios projetos: se seu serviço de IA implantado parasse de responder aos usuários, qual seria seu primeiro passo de diagnóstico?
Correct Answer: A
O primeiro passo é delimitar onde está a falha: O processo do serviço está rodando? O Cloudflare Tunnel está ativo? O endpoint de health está acessível localmente? Trabalhe de fora para dentro — rede → processo do serviço → logs da aplicação. Fazer rollback antes de diagnosticar a causa pode não resolver o problema e obscurece o que deu errado.
Pense nisto: Se seu script de deploy rodasse hoje à noite e o smoke test detectasse uma regressão, como seria sua sequência de rollback? Percorra cada passo — desde receber o alerta até confirmar que a versão antiga está servindo tráfego novamente. Escreva a sequência antes de precisar dela. O melhor plano de rollback é aquele que existe antes do incidente.