Domínio personalizado e TLS automático no Dockup

Uma configuração de domínio personalizado e TLS automático tem três camadas distintas: o serviço do Dockup precisa estar saudável, o DNS precisa apontar o hostname para a plataforma e o hostname precisa passar pela verificação antes que um certificado possa ser emitido. Tratar essas camadas separadamente torna a mudança previsível e evita que erros de DNS pareçam falhas da aplicação.

O Dockup também fornece a cada serviço um endereço *.dockup.tech. Mantenha esse endereço disponível durante a propagação do DNS para testar a aplicação independentemente do hostname personalizado.

O que deve estar pronto antes de adicionar um domínio personalizado do Dockup?

Comece com um serviço que já esteja em execução e passe pelo readiness gate:

dockup status production/web --json
dockup health production/web --json

Abra ou teste o URL *.dockup.tech existente. Se a aplicação estiver falhando nesse endereço, adicionar um domínio não resolverá o problema. Inspecione primeiro os logs de runtime.

Reúna as seguintes informações:

Item	Exemplo	Por que isso importa
Destino exato	production/web	Evita associar o domínio ao serviço errado
Hostname	app.example.com	O nome DNS que os usuários acessarão
Acesso ao DNS	Registrador ou provedor de DNS	Necessário para criar o registro
TTL atual	300 segundos	Controla a velocidade de propagação e rollback
URL canônica da aplicação	https://app.example.com	Pode afetar redirects e cookies
Rota de health	/health	Confirma o serviço antes da mudança

Reduza antecipadamente o TTL do DNS existente ao substituir um provedor em produção. Não exclua o registro antigo até conhecer o destino no Dockup, a configuração da aplicação e o plano de rollback.

Revise o comportamento da aplicação que depende do host. Callbacks de autenticação, allowlists de CORS, domínios de cookies, URLs de redirect do OAuth, destinos de webhooks e links absolutos gerados podem precisar do novo hostname HTTPS.

Como adicionar e verificar o domínio?

Liste primeiro os domínios atuais:

dockup domain list production/web --json

Adicione o hostname:

dockup domain add app.example.com production/web --json

A resposta fornece o destino DNS que deve ser configurado. Crie o registro CNAME indicado no provedor de DNS. Não invente um endereço IP nem copie um valor de outro serviço; use o destino retornado para esse domínio.

Depois que o DNS tiver se propagado, faça a verificação usando o ID do domínio retornado:

dockup domain verify <domainId> production/web --json

A verificação comprova que o registro DNS público é resolvido conforme o necessário. Uma falha normalmente significa uma destas quatro coisas:

1. O nome do registro está incorreto.
2. O destino CNAME está incorreto.
3. Ainda existe um registro A, AAAA ou CNAME antigo e conflitante.
4. Os caches dos resolvers ainda não receberam o novo valor.

Verifique o DNS autoritativo em vez de remover e recriar o domínio repetidamente. A propagação é um processo de cache distribuído, não um processo de build do Dockup.

Como o certificado HTTPS é emitido e mantido?

Depois que a verificação for concluída com sucesso, solicite o certificado:

dockup domain ssl <domainId> production/web --json

O Dockup gerencia a emissão do certificado para o hostname verificado e disponibiliza o domínio personalizado por HTTPS. A plataforma gerencia o ciclo de vida do TLS, portanto o container da aplicação não precisa armazenar arquivos de certificado nem executar um processo de renovação.

Valide o resultado de fora da plataforma:

curl -I https://app.example.com

Confirme que:

• O certificado corresponde ao hostname.
• A resposta é servida por HTTPS.
• Os redirects não entram em loop.
• A aplicação retorna o status esperado.
• Os fluxos de autenticação e callback usam a nova origem.
• Os assets estáticos são carregados sem erros de mixed content.

A emissão do certificado pode falhar mesmo quando a aplicação está saudável. Mantenha os diagnósticos de DNS e do serviço separados. Use domain verify para a propriedade do DNS e os logs do serviço para o comportamento da aplicação.

O artigo sobre deployments sem downtime explica o readiness gate independente de release.

Como mudar o tráfego sem causar uma interrupção?

Uma mudança segura mantém o caminho antigo disponível até que o novo hostname seja validado.

1. Faça o deploy e verifique o serviço do Dockup no URL da plataforma.
2. Adicione o domínio personalizado no Dockup.
3. Crie o registro DNS.
4. Verifique o DNS.
5. Emita o TLS.
6. Teste o HTTPS diretamente.
7. Atualize callbacks, URLs canônicas e monitoramento.
8. Envie uma pequena parte do tráfego operacional, se a configuração de DNS permitir.
9. Observe os logs e o uptime.
10. Desative o provedor antigo somente depois que o novo caminho estiver estável.

As verificações de uptime do Dockup são executadas a cada minuto e informam estatísticas de tempo de resposta, incluindo p95:

dockup uptime production/web --hours 24 --json

Mantenha um monitoramento externo independente para domínios críticos. Um probe da plataforma confirma a acessibilidade pública, enquanto um monitor externo verifica o caminho do usuário a partir de outro sistema.

Se o domínio personalizado substituir um host atual de produção, preserve um registro de rollback: valor DNS anterior, TTL anterior, status do provedor antigo e a condição que acionaria a reversão.

Como funcionam os domínios de portas adicionais?

Um serviço pode expor uma segunda porta HTTP para uma interface de administração, um endpoint de métricas ou outro processo web. O Dockup pode criar um domínio adicional da plataforma sem DNS personalizado:

dockup port list production/web --json
dockup port add 8080 production/web --name admin --json

O domínio retornado encaminha para a porta selecionada do container. Isso é separado do domínio personalizado principal.

Não exponha uma porta apenas porque há um processo escutando nela. Verifique se o endpoint tem autenticação, se contém dados de produção e se realmente deve ser público. Uma interface de administração interna não deve ficar acessível pela internet apenas por conveniência.

Remova um domínio de porta obsoleto somente pela interface de domínio compatível, depois de confirmar que nenhum monitor, callback ou fluxo operacional ainda o utiliza. Alterações em domínios de portas são mutações e aparecem no audit log.

Como solucionar problemas de DNS, TLS e aplicação?

Use um diagnóstico camada a camada:

Sintoma	Primeira verificação	Comando do Dockup
O domínio não é resolvido	Registro DNS e propagação	domain verify
O certificado não foi emitido	Status da verificação do domínio	domain list, domain ssl
O HTTPS funciona, mas a aplicação apresenta erros	Logs de runtime	logs --json
Redirect em loop	Configurações de proxy/host da aplicação	env list, logs de runtime
O URL da plataforma funciona, mas o host personalizado falha	Camada de DNS/TLS	Comandos de domínio
Os dois URLs falham	Deploy e runtime	status, logs de build/runtime
A porta secundária falha	Mapeamento do domínio da porta e processo	port list, logs de runtime

Inspecione a saída do serviço sem misturá-la a conclusões sobre DNS:

dockup logs production/web --json
dockup status production/web --json

Se uma alteração recente no ambiente adicionou a URL canônica, lembre-se de que ela requer um novo deploy:

dockup env set APP_URL=https://app.example.com \
  -s production/web \
  --json

dockup deploy production/web --wait --json

O guia de variáveis de ambiente e secrets explica esse ciclo de vida.

Remoção do domínio e rollback

Remover a associação do Dockup é destrutivo para a rota. Portanto, primeiro mova ou remova o registro DNS público e confirme a substituição desejada. Em seguida, remova a associação pela interface de domínio compatível usando o ID exato do domínio.

Não remova o domínio durante um incidente temporário de certificado ou propagação, a menos que o plano de recuperação exija isso. Manter a configuração permite que a verificação seja concluída quando os caches forem atualizados.

Revise as mutações com:

dockup audit --search domains --json

O audit trail deve mostrar quem adicionou, verificou, protegeu ou removeu o hostname.

Checklist de handoff para produção

Um handoff completo de domínio personalizado e TLS automático inclui o destino do serviço, hostname, ID do domínio, tipo e destino do registro DNS, resultado da verificação, resultado do certificado, alterações nos callbacks da aplicação, URL de monitoramento e valor DNS para rollback.

Não armazene chaves privadas de certificados no repositório nem no container. O limite de TLS gerenciado do Dockup existe justamente para que a equipe da aplicação possa operar o hostname sem distribuir material de certificado.

Para consultar todas as flags atuais, use a referência da CLI do Dockup. Para o deploy inicial antes do trabalho com o domínio, siga Do repositório Git à produção.

Planeje as opções de domínio apex e subdomínio

Um subdomínio como app.example.com costuma ser o hostname de aplicação mais simples, porque os provedores de DNS podem representá-lo com um CNAME. Um domínio apex como example.com pode exigir flattening ou comportamento de alias específico do provedor. Siga o destino DNS retornado pelo Dockup e os recursos do provedor de DNS autoritativo.

Escolha um host canônico e redirecione as alternativas na camada da aplicação ou de routing. Servir www e o apex sem uma política canônica pode dividir cookies, analytics, entradas de cache e indexação nos mecanismos de busca.

Teste as premissas de renovação do certificado

O TLS gerenciado elimina a necessidade de executar um cliente de renovação dentro do container, mas o hostname precisa continuar sendo resolvido corretamente. Uma futura migração de DNS, alteração de proxy ou exclusão de registro pode interromper a validação.

Inclua o status do domínio nas revisões de rotina:

dockup domain list production/web --json
dockup uptime production/web --hours 24 --json

O runbook de domínio personalizado e TLS automático deve indicar o responsável pelo DNS, o contato para renovação e a data da última verificação externa do certificado. Isso evita descobrir quem é o responsável somente quando ocorre um incidente com o certificado.

Proteja hostnames que não são de produção

Hostnames de staging e preview podem expor funcionalidades inacabadas e dados com formato semelhante aos de produção. Use autenticação da aplicação quando necessário, defina uma política de indexação na camada da aplicação e restrinja a distribuição de URLs que não são de produção.

Diretivas para mecanismos de busca não são controle de acesso. Um ambiente protegido ainda precisa de autenticação e do tratamento adequado dos dados.

Verifique novamente após a propagação

Repita os testes externos de HTTPS e callback depois que o TTL DNS original tiver transcorrido completamente.

Comece com um deploy verificável

Associe primeiro um hostname não crítico, mantenha o URL da plataforma durante a propagação e registre o valor DNS exato necessário para rollback.

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 deployments.

FAQ

De qual registro DNS um domínio personalizado do Dockup precisa?

Execute dockup domain add e crie o registro DNS mostrado na resposta. Use o destino retornado, em vez de copiar um valor de outro serviço.

Quando o Dockup pode emitir TLS para um domínio personalizado?

Depois que o registro DNS do hostname passar pela verificação de domínio do Dockup, solicite a emissão do certificado com o comando documentado domain ssl.

Meu container precisa armazenar certificados TLS?

Não. O Dockup gerencia o TLS para o domínio personalizado verificado, portanto o container da aplicação não precisa de arquivos de certificado nem de um processo de renovação.

O Dockup pode expor uma porta adicional do container?

Sim. Os comandos de porta podem criar um domínio separado gerado automaticamente para uma porta pública adicional, sem exigir DNS personalizado.

O que devo verificar quando o URL da plataforma funciona, mas o domínio personalizado falha?

Concentre-se nos registros DNS, na propagação, na verificação do domínio e no status do certificado. O URL saudável da plataforma mostra que a camada da aplicação provavelmente está funcionando.