Do repositório Git à produção: guia de deploy do Dockup

Mover um repositório Git para produção exige mais do que conectar um remote e pressionar o botão de deploy. A plataforma precisa conhecer o destino do serviço, a branch, o método de build, o comando de start, a porta de escuta, o ambiente, o health gate e o caminho de recuperação. O Dockup torna essas decisões explícitas e oferece suporte tanto a builds automáticos com Nixpacks quanto a Dockerfiles mantidos no próprio repositório.

Este guia começa com um repositório que nunca foi colocado em produção e termina com uma URL verificada, histórico de deploys, logs e um comando de rollback testado.

O que deve ser verificado antes do primeiro deploy em produção?

Confirme que o repositório pode ser colocado em produção sem depender de estado local não documentado. Um clone limpo deve conter tudo o que é necessário para instalar as dependências e iniciar a aplicação, exceto os secrets.

Use este checklist:

Verificação	Resultado esperado
Branch padrão	A branch de produção pretendida existe
Lockfile de dependências	Está commitado para permitir instalações reproduzíveis
Processo de start	Vincula-se à porta configurada e a 0.0.0.0
Rota de health check	Retorna sucesso sem efeitos colaterais externos
Migrações do banco de dados	Têm um plano de execução seguro e explícito
Secrets	São armazenados fora do Git
Arquivos persistentes	Usam um volume, não o filesystem do container
Rollback	O deploy anterior pode ser executado novamente

Instale a CLI e faça a autenticação:

npm install -g dockup-cli
export DOCKUP_TOKEN="<TOKEN>"
dockup whoami --json

Liste os serviços existentes antes de criar qualquer coisa:

dockup services --json

Isso evita recursos duplicados e confirma a convenção exata de workspace e destino.

Como o Dockup create oferece suporte ao deploy do Git?

O comando usual do primeiro deploy cria o serviço, faz o deploy, aguarda o resultado e vincula o diretório atual:

dockup create api \
  --repo https://github.com/acme/api \
  --project production \
  --branch main \
  --deploy \
  --wait \
  --link \
  --json

O destino resultante é production/api. O link .dockup permite que comandos posteriores resolvam esse serviço quando executados dentro do repositório, mas a documentação de produção ainda deve registrar o destino completo.

Depois de uma tentativa de provisionamento interrompida, liste os serviços e inspecione o destino exato antes de executar a criação novamente:

dockup services --json

Se production/api já existir, continue lendo o status e o histórico de deploys. Isso evita transformar um resultado de rede incerto em um serviço duplicado. Mantenha as credenciais de acesso ao repositório fora do controle de versão e da saída dos comandos.

Como o Dockup escolhe entre Nixpacks e Dockerfile?

Se o repositório contiver um Dockerfile, o Dockup o utilizará. Caso contrário, o Nixpacks detectará a aplicação e fará o build automaticamente. Essa ordem torna a definição explícita do container no repositório a fonte de autoridade.

O Nixpacks é uma boa primeira escolha quando a aplicação segue convenções comuns do ecossistema e não precisa de customização no nível do sistema operacional. Um Dockerfile é útil quando você precisa de uma imagem base específica, pacotes do sistema, um build multi-stage, um usuário de runtime personalizado ou limites exatos para a cópia de arquivos.

Você não precisa adicionar um Dockerfile vazio apenas para “parecer pronto para produção”. Um Dockerfile incorreto pode ser menos reproduzível do que um build automático convencional. Use o processo de decisão em Nixpacks vs Dockerfile.

Inspecione o serviço depois da criação:

dockup info production/api --json

A resposta inclui a URL do repositório, a branch, o tipo de deploy, a porta, as configurações de build e start, as chaves de ambiente, os custom domains e os dados do deploy mais recente.

Se os comandos detectados precisarem de um override, use as configurações documentadas:

dockup set production/api \
  --build "npm ci && npm run build" \
  --start "npm start" \
  --port 3000 \
  --json

As configurações serão aplicadas no próximo deploy.

Como configurar o ambiente de produção e o health check?

Adicione valores comuns e secrets separadamente:

dockup env set NODE_ENV=production \
  -s production/api \
  --json

dockup env set DATABASE_URL="$DATABASE_URL" \
  --secret \
  -s production/api \
  --json

Os valores secretos ficam ocultos quando o ambiente é listado. Eles podem ser definidos ou substituídos, mas o valor armazenado não é retornado.

Alterações no ambiente exigem um novo deploy, porque o processo em execução não pode receber retroativamente um novo ambiente. O ciclo de vida completo é explicado em variáveis de ambiente e secrets.

Configure um health gate que represente a prontidão:

dockup health production/api \
  --path /healthz \
  --interval 5 \
  --timeout 3 \
  --retries 5 \
  --json

O Dockup usa um fluxo blue-green sem downtime e só direciona tráfego para o novo deploy depois que a prontidão é confirmada. Quando nenhum caminho HTTP é configurado, o gate pode usar como fallback a prontidão da porta TCP.

Uma rota de health check deve verificar se o processo da aplicação está pronto para atender às requisições. Evite fazê-la executar verificações destrutivas ou testes completos e dispendiosos do sistema. Verificações profundas de dependências podem criar falsos outages quando um serviço opcional está degradado.

Como fazer o deploy, acompanhar e verificar a produção?

Dispare o release e aguarde um estado terminal:

dockup deploy production/api --wait --json

O timeout padrão é de 900 segundos. O código de saída 0 significa sucesso. deploy_failed e deploy_timeout resultam em códigos diferentes de zero, para que scripts de shell e sistemas de CI parem corretamente.

Para acompanhar o build como NDJSON:

dockup logs production/api --build -f --json

O stream termina em caso de sucesso ou falha. Se o build for concluído, mas o container parar, inspecione os logs de runtime:

dockup logs production/api --json

Depois de um release bem-sucedido, verifique o estado da plataforma e o comportamento público:

dockup status production/api --json
dockup uptime production/api --hours 24 --json
dockup security production/api --json

As probes de uptime são executadas a cada minuto e informam o tempo médio e o tempo de resposta p95. A análise de segurança verifica CVEs da imagem e a configuração. Adicione um smoke test específico da aplicação para o endpoint de negócio real; a prontidão da plataforma é necessária, mas não suficiente.

O método detalhado de logs está disponível em debug de logs de build e runtime.

Como introduzir deploys automáticos e previews?

Faça o primeiro release de produção manualmente, observando cada etapa. Depois que o build, o health gate e o caminho de rollback forem conhecidos, habilite o deploy a cada push:

dockup auto-deploy production/api --on --json

O deploy automático deve seguir uma branch protegida e uma política de code review. Um push é um gatilho de produção, portanto as permissões do repositório tornam-se permissões de infraestrutura.

Previews de pull requests e branches fornecem URLs e ambientes isolados:

dockup pr-preview production/api --on --json
dockup preview branch feature/login production/api --json

Em um projeto com rede privada, os previews entram na rede do projeto. Eles podem acessar o mesmo banco de dados de produção em <slug>.internal, mas o Dockup cria automaticamente um usuário de banco de dados somente leitura para o preview. O preview pode consultar dados semelhantes aos de produção sem alterá-los.

Isso não elimina as obrigações de privacidade. O acesso aos previews ainda deve ser limitado, auditado e usado apenas quando a leitura de dados de produção for permitida.

Como fazer rollback de um deploy problemático?

Preserve as evidências antes da recuperação. Leia os logs de build em caso de falha no build e os logs de runtime em caso de crash. Em seguida, liste o histórico de deploys:

dockup deployments production/api -n 20 --json

Selecione um ID de deploy cujo status e timestamp sejam conhecidos e execute-o novamente:

dockup rollback <deploymentId> production/api --json

Um rollback deve ser uma ação explícita de incidente. Registre o ID do deploy com falha, o ID de recuperação selecionado, o motivo e a correção posterior. Se uma migração de banco de dados não for compatível com versões anteriores, reverter apenas a aplicação pode não restaurar a compatibilidade; o design das migrações deve fazer parte do plano de release.

O guia de deploy sem downtime explica a mudança de tráfego, enquanto a referência da CLI do Dockup documenta todas as flags dos comandos.

Registro de conclusão do primeiro deploy

Ao final do fluxo de repositório Git para produção, registre:

• O destino exato project/service.
• O repositório e a branch de produção.
• O método de build: Nixpacks ou Dockerfile.
• Os comandos de build e start, quando substituídos.
• A porta de escuta e o caminho do health check.
• O ID do deploy e o status terminal.
• A URL de produção e o plano de custom domain.
• A verificação de uptime e segurança.
• O ID do deploy de rollback ou a regra de seleção.

Esse registro transforma o segundo deploy em uma operação rotineira, em vez de outro exercício de descoberta.

Separe o estado da aplicação da imagem do container

O filesystem gravável dentro de um container de serviço deve ser tratado como substituível. Um novo deploy cria uma nova versão, e um rollback executa novamente uma imagem antiga; arquivos gravados apenas dentro do container antigo não são uma estratégia durável de armazenamento de dados.

Use bancos de dados gerenciados para dados relacionais, documentais ou de cache e anexe um volume para arquivos que precisam persistir entre deploys. Confirme os caminhos de montagem antes do primeiro release de produção. Um diretório de uploads em um container que nunca foi montado pode parecer saudável até o próximo deploy remover os dados.

Consulte volumes persistentes e snapshots antes de mover arquivos gerados pelos usuários. Para o estado do banco de dados, use o sistema de backup específico do banco, em vez de tratar um snapshot de volume em execução como um backup consistente com a transação.

Estime o primeiro mês sem inventar um custo fixo de instância

O Dockup mede o consumo de CPU, RAM e disco por minuto e subtrai o uso do saldo do plano. O plano Free inclui um crédito inicial de US$ 10 e até três deploys; o plano Pro recomendado custa US$ 20 por mês e inclui US$ 20 em créditos de uso.

Depois que o serviço receber tráfego real, consulte o consumo de CPU, RAM e disco em app.dockup.ai. Use o consumo observado por minuto — não um máximo estimado — para decidir se o serviço, o banco de dados ou o disco persistente precisa de ajustes.

Verifique um segundo deploy limpo

Depois do primeiro release, faça uma alteração inofensiva e revisada e execute outro deploy. Isso confirma que o link do repositório, as premissas do build cache, o health gate, o ambiente e o histórico funcionam como um processo contínuo, e não apenas como um sucesso pontual de provisionamento.

Mantenha o destino explícito

Registre a string final project/service.

Preserve a URL do release

Registre a URL de produção ao lado do ID do deploy.

Confirme o próximo gatilho

Registre se os releases futuros serão manuais ou usarão o deploy-on-push opcional. Isso mantém as permissões do repositório, a proteção da branch e as expectativas de produção alinhadas após o primeiro deploy.

Comece com um deploy verificável

Escolha um repositório pequeno, com um comando de start e uma rota de health check claros, e documente o destino exato e o ID de rollback após o primeiro release bem-sucedido.

Comece gratuitamente em app.dockup.ai. O plano Free custa US$ 0 por mês, inclui US$ 10 em crédito inicial e oferece suporte a um workspace, três bancos de dados e três deploys.

FAQ

O Dockup pode fazer deploy de um repositório sem Dockerfile?

Sim. Quando não há um Dockerfile, o Dockup usa o Nixpacks para detectar e fazer o build da aplicação automaticamente.

O que faz dockup create --link?

Ele grava um link .dockup no diretório atual para que os comandos posteriores possam resolver o destino de project/service associado.

Por que o primeiro deploy deve usar --wait?

Ele mantém o comando conectado até que o deploy alcance sucesso, falha ou timeout e retorna um código de saída que representa corretamente o resultado terminal.

As alterações nas variáveis de ambiente são aplicadas imediatamente?

Não. Elas são aplicadas a um novo container no próximo deploy. Portanto, faça um novo deploy do serviço depois de alterar a configuração do ambiente.

Como o Dockup faz rollback de uma aplicação?

Liste o histórico de deploys, identifique um ID de deploy anterior conhecido e use dockup rollback com esse ID e o destino exato do serviço.