Configuração de domínio personalizado para apps web: DNS, SSL e migração

O que muda com um domínio personalizado (e o que pode dar errado)

Um domínio personalizado é mais que uma URL mais bonita. No momento em que você sai do endereço da plataforma (por exemplo, um app que você construiu no Koder.ai sob um subdomínio da plataforma) para o seu próprio domínio, navegadores e redes passam a tratar como um site diferente. Isso afeta roteamento, segurança e o comportamento de sessões de usuário.

Assim que você troca para um domínio personalizado, algumas coisas mudam imediatamente:

• Roteamento DNS: os usuários deixam de ir para o hostname antigo e começam a alcançar o que seu DNS aponta.
• TLS/SSL: o certificado precisa corresponder aos novos hostname(s) e estar ativo antes que usuários reais cheguem.
• Redirecionamentos: você decide se os usuários caem no www ou no domínio apex, e precisa de regras consistentes de HTTP para HTTPS.
• Cookies e sessões: cookies são limitados por domínio. Um cookie de login para old-platform.example não funcionará automaticamente em app.yourdomain.com.
• Cache e propagação: resolvers DNS e navegadores cacheiam resultados, então nem todo mundo muda ao mesmo tempo.

Quedas curtas geralmente vêm do tempo das mudanças. O DNS pode começar a encaminhar tráfego para o novo host antes do certificado SSL estar pronto, o que gera avisos do navegador. Ou o contrário: o SSL fica pronto, mas muitos usuários ainda entram no local antigo porque o cache DNS não expirou.

Redirecionamentos também podem quebrar logins de forma sutil. Um redirecionamento que troca o hostname (apex para www, ou o inverso) pode fazer cookies sumirem se foram definidos para o outro host. Provedores de autenticação podem falhar se a URL de callback continuar sendo o domínio antigo.

Uma migração de baixo risco significa planejar sobreposição: mantenha a URL antiga funcionando, leve o novo domínio no ar em paralelo, troque o tráfego em um momento previsível e torne o rollback tão simples quanto trocar o DNS de volta.

Decida seu domínio e hostnames antes de mexer no DNS

Antes de mudar qualquer coisa, escreva exatamente quais nomes você quer que usuários digitem e quais devem redirecionar silenciosamente. A maioria dos momentos de “por que isso está funcionando pela metade?” vem de equipes que nunca concordaram num único hostname verdadeiro.

Comece pela escolha principal: apex (example.com) ou www (www.example.com) como o primário. Ambos funcionam, mas escolha um e trate o outro como redirecionamento. Isso importa depois para cookies também: sessões geralmente são mais simples quando o app vive em um host consistente.

Depois, decida quais subdomínios você precisa agora e quais podem esperar. Um padrão comum é app.example.com para o web app e api.example.com para APIs, com admin.example.com ou assets.example.com adicionados depois. Se você está configurando um domínio personalizado em uma plataforma como o Koder.ai, essas escolhas mapeiam diretamente para o que você validará para SSL e para o que apontará no DNS.

Saiba quem realmente controla o DNS

Muita gente compra um domínio no registrador, mas o DNS pode ser hospedado em outro lugar. Confirme onde os registros são editados hoje, quem tem acesso e se há automação gerenciando mudanças (TI da empresa, uma agência ou um provedor DNS gerenciado). Se você não consegue entrar e ver os registros atuais, pare e resolva isso primeiro.

Audite também o que já usa o domínio. E‑mail é a armadilha clássica: você pode quebrar a entrega de emails deletando ou sobrescrevendo registros.

Antes de prosseguir, registre essas decisões por escrito:

• Hostname primário (apex ou www) e a direção do redirecionamento
• Subdomínios necessários agora (app, api, admin) vs ideias para depois
• Onde o DNS é hospedado e quem pode publicar mudanças
• Registros críticos existentes (MX, SPF, DKIM, DMARC, TXT de verificação)
• Expectativas de cookies e auth (host único vs compartilhado entre subdomínios)

Se o time de marketing já roda email em example.com, mantenha os registros de mail intactos enquanto adiciona apenas o que o app precisa.

Registros DNS que você usará e por que importam

A maior parte do risco em uma mudança de domínio personalizado não é o app em si. É uma alteração errada no DNS que manda o tráfego para lugar nenhum, quebra e‑mail ou faz a validação do SSL falhar.

Os registros principais (A, CNAME e semelhantes)

Um A record aponta um nome para um endereço IP. Em termos simples: “mande as pessoas para este servidor.” É comum para o apex (example.com) quando seu provedor dá um IP fixo.

Um CNAME record aponta um nome para outro nome. Em termos simples: “trate este nome como um alias daquele hostname.” É comum para www.example.com apontando para um hostname da plataforma.

Muitos provedores DNS também oferecem ALIAS/ANAME no apex. Ele se comporta como um CNAME mas funciona para example.com. Se seu provedor suportar, pode ser mais fácil de gerenciar porque o alvo pode se mover sem você mexer em IPs.

Um modelo mental simples:

• A: name -> IP (direto)
• CNAME: name -> name (alias)
• TXT: name -> texto (provas e políticas)
• MX: name -> servidores de mail (não mexa a menos que saiba o que faz)

Registros TXT: verificação, SSL e segurança de e‑mail

Você frequentemente adicionará TXT para checar propriedade (verificação de plataforma) e para validação de certificados SSL (algumas CAs validam via token TXT). TXT também é usado para políticas de email como SPF. Deletar ou substituir um SPF existente por engano pode quebrar entrega de email.

TTL: o “controle de velocidade” das mudanças

TTL controla por quanto tempo outros sistemas cacheiam sua resposta DNS. Um dia antes do corte, reduza o TTL nos registros que você planeja mudar (comum: 300 a 600 segundos). Depois que tudo estiver estável, aumente de novo para reduzir carga de consultas.

Evite sobrescrever registros existentes e documente o rollback

Antes de editar, exporte ou faça screenshots da zona atual. Anote cada registro que você vai mudar, o valor antigo, o novo valor e o TTL. Se algo der errado, o rollback é restaurar os valores anteriores.

Isso é especialmente importante quando seu domínio já tem MX, DKIM ou outros TXT para e‑mail.

Emissão de SSL: validação, tempo e cobertura

SSL (o cadeado) criptografa o tráfego entre o navegador e seu app. Navegadores modernos e muitas APIs esperam HTTPS por padrão. Sem ele, há avisos, requisições bloqueadas e recursos como service workers, geolocalização e alguns fluxos de pagamento podem parar de funcionar.

Para emitir um certificado, a autoridade certificadora precisa verificar que você controla o domínio. Os métodos comuns são validação via HTTP e via TXT no DNS:

• Validação HTTP: coloca um arquivo temporário ou resposta em uma URL específica no seu app.
• Validação DNS TXT: adiciona um registro TXT na sua zona DNS.

A validação via DNS costuma ser mais simples quando você usa um CDN ou quando seu app ainda não é alcançável pelo novo domínio.

Onde o certificado é emitido depende da sua arquitetura. Algumas equipes emitem certificados no próprio stack de hosting, outras no CDN, e algumas plataformas que suportam domínios personalizados cuidam disso para você (por exemplo, o Koder.ai pode gerenciar o certificado durante a configuração do domínio). O que importa é saber quem é responsável pelo ciclo de vida do certificado, incluindo renovações.

Tempo e tentativas

A emissão nem sempre é instantânea. Propagação DNS, checagens de validação e limites de taxa podem atrasar. Planeje tentativas repetidas e evite marcar o corte para o último minuto.

Um plano prático de tempo:

• Reduza TTL um dia antes para que mudanças apliquem mais rápido.
• Adicione registros de validação cedo (TXT no DNS ou token HTTP).
• Aguarde até o certificado aparecer como emitido para todos os hostnames.
• Só então aponte o tráfego para o novo alvo.

Cobertura: garanta que os hostnames certos estejam incluídos

Um certificado precisa cobrir todo hostname que os usuários irão acessar. Verifique a lista SAN (Subject Alternative Names). Se seu app estará acessível em example.com e www.example.com, o certificado deve incluir ambos.

Curingas (como *.example.com) ajudam para muitos subdomínios, mas não cobrem o domínio apex (example.com).

Exemplo concreto: se você emitir um certificado apenas para www.example.com, usuários que digitarem example.com ainda verão avisos, a menos que você redirecione em uma camada que já tenha certificado válido para example.com.

Regras de redirecionamento: www, apex, HTTP para HTTPS e defaults seguros

Redirecionamentos parecem simples, mas é onde surgem a maioria dos problemas: loops, conteúdo misto e usuários sendo deslogados por pularem entre hosts.

Escolha um host canônico e mantenha‑se nele: www.example.com ou example.com (apex). O outro ponto de entrada deve redirecionar para o host canônico para que cookies, sessões e sinais de SEO se mantenham consistentes.

Defaults seguros:

• Um host canônico, com um único redirecionamento 301 do outro host
• 301 de http:// para https:// em todas as requisições
• Preserve caminho e query string durante redirecionamentos (deep links devem continuar funcionando)
• Redirecione apenas uma vez (evite cadeias como http -> https -> www)

Para HTTP → HTTPS, evite regras que façam os usuários irem e voltarem. A forma mais fácil de prevenir loops é basear a decisão no que a requisição realmente foi. Se sua app está atrás de um proxy ou CDN, configure para respeitar headers encaminhados (por exemplo, um header que indica que o esquema original era HTTP). Caso contrário, sua app pode achar que toda requisição é HTTP e continuar redirecionando indefinidamente.

Durante uma migração, mantenha caminhos antigos ativos. Se você estiver mudando rotas (como /login para /sign-in), adicione redirecionamentos explícitos para essas rotas. Não conte com um redirecionamento genérico para a homepage — isso quebra bookmarks e links compartilhados.

Segure o uso de HSTS no início. Se habilitar cedo demais e depois precisar servir HTTP para validação ou troubleshooting, navegadores podem recusar. Espere até que o HTTPS esteja estável e você tenha confirmado a cobertura de subdomínios.

Para testar redirecionamentos sem impactar todos, use um hostname de teste temporário, experimente alguns deep links reais (incluindo páginas de autenticação) e rode uma requisição em linha de comando que mostre cada etapa de redirecionamento e o destino final.

Plano passo a passo de migração de baixo risco (sem downtime)

Uma migração segura é principalmente sobre timing. Você quer que o novo domínio esteja pronto e testado antes que usuários reais sejam enviados para ele, e quer que mudanças DNS se espalhem rápido para não ficar esperando durante um incidente.

1) Prepare e teste antes de tocar no DNS de produção

Reduza seu TTL (nos registros que irá mudar) com antecedência. Faça isso no dia anterior se possível, e espere a janela do TTL antigo expirar para que caches atualizem com o novo valor.

Em seguida, adicione o domínio no seu host/provedor e conclua a verificação que solicitarem. Se estiver usando uma plataforma como o Koder.ai, adicione o domínio lá primeiro para que a plataforma confirme propriedade e prepare o roteamento.

Emita o SSL cedo. Certificados podem levar minutos ou mais, dependendo da validação, e você não quer esse atraso no momento da troca.

Antes de tornar o domínio público, faça um teste privado: acesse o novo endpoint de modo que não dependa do DNS público (por exemplo, usando uma entrada temporária de hosts na sua máquina) e confirme que o site carrega via HTTPS com o certificado correto.

2) Corte em passos pequenos e reversíveis

Use uma abordagem em etapas para poder parar rápido se algo parecer errado:

• Reduza o TTL com antecedência e espere o período do TTL antigo passar.
• Complete a verificação de domínio no host e confirme que o domínio aponta internamente para o app correto.
• Confirme que o SSL está ativo para todos os hostnames que vai servir (apex e/ou www) antes de mudar usuários.
• Mude o DNS de forma controlada: comece por um subdomínio, uma região pequena ou um público limitado se possível.
• Mantenha o domínio antigo online e redirecionando enquanto observa tráfego e taxas de erro estabilizarem.

Se não for possível um canary verdadeiro no nível DNS, você ainda pode escalonar mudando apenas um hostname primeiro (por exemplo, www) e deixando o apex intacto até ganhar confiança.

3) Planeje o rollback enquanto ainda está com calma

Anote exatamente o que vai reverter (quais registros, quais valores) e quem fará isso. Rollback normalmente é restaurar o DNS como era.

Assegure que a configuração antiga ainda esteja válida (incluindo SSL no domínio antigo) para que usuários possam voltar limpo enquanto você corrige o novo caminho.

Evite cookies, sessões e auth quebrados após a mudança

Uma troca de domínio não é só uma alteração de DNS. Para muitos apps, “estar logado” depende de cookies que navegadores amarram a um hostname específico. Se você muda de hostname, o navegador pode parar de enviar os cookies antigos e sua app parecerá ter deslogado todo mundo.

As configurações de cookie são geralmente a causa:

• Domain decide quais hostnames recebem o cookie. Um cookie para app.old.com não será enviado para app.new.com. Um cookie definido para .example.com pode funcionar entre app.example.com e www.example.com.
• Path limita onde o cookie é enviado. Se for muito restrito (como /api), a UI web pode não enxergá‑lo.
• Secure significa que o cookie só é enviado via HTTPS. Após migrar para HTTPS-only, requisições HTTP não incluirão o cookie.
• SameSite afeta redirecionamentos cross-site e fluxos embutidos. Lax costuma ser suficiente, mas alguns SSO ou pagamentos podem precisar de None + Secure.

Para reduzir risco, planeje uma transição curta onde ambos os domínios funcionem. Mantenha o hostname antigo respondendo e redirecionando com cuidado, mas permita que sessões sejam renovadas no novo domínio. Se possível, use um store de sessão compartilhado para que um usuário que chegue por qualquer hostname seja reconhecido.

Se você usa SSO ou OAuth, atualize configurações antes do corte: URLs de callback, origins permitidos e qualquer allowlist de redirect URIs. Caso contrário, logins podem ser bem sucedidos no provedor de identidade mas falhar ao retornar para sua app.

Teste os fluxos que costumam quebrar primeiro: cadastro (e verificação por e‑mail), login/logout, recuperação de senha, checkout ou retorno de pagamento, e sessões em múltiplas abas.

Exemplo: se você redireciona www.example.com para example.com, certifique‑se de definir cookies para .example.com (ou use um hostname consistente). Caso contrário, usuários pulam entre hosts e perdem a sessão.

Erros comuns que causam downtime ou comportamento estranho

A maioria dos problemas de domínio não é “misterioso”. São pequenas incompatibilidades entre DNS, certificados e regras de redirecionamento que só aparecem com usuários reais.

Uma armadilha fácil é o domínio apex (example.com). Muitos provedores DNS não permitem um CNAME verdadeiro no apex. Se você tentar forçar um CNAME no apex, pode falhar silenciosamente, resolver de forma inconsistente ou quebrar apenas em algumas redes. Use o que seu host DNS suporta (frequentemente um A/AAAA, ou um registro ALIAS/ANAME).

Outra causa frequente de downtime é trocar o DNS antes do SSL estar pronto no novo endpoint. Usuários chegam, a app carrega e o navegador bloqueia porque o certificado falta ou cobre apenas parte dos hostnames. Na prática, normalmente você quer o certificado cobrindo tanto example.com quanto www.example.com, mesmo se planejar redirecionar um para o outro.

Erros comuns que criam downtime ou comportamento estranho:

• Mudar DNS sem reduzir TTL antes, então esperar horas pela expiração de respostas antigas
• Manter regras de redirecionamento que criam loops (www → apex, então apex de volta para www) ou forçar HTTP em um lugar e HTTPS em outro
• Enviar conteúdo misto por hardcoding de http:// em assets, o que provoca avisos do navegador e recursos quebrados
• Esquecer registros DNS não web, especialmente MX e TXT, que podem quebrar email e validações de domínio
• Testar em apenas um navegador e perder quirks de cache, HSTS ou cookies que outros usuários enfrentarão

Um check rápido de sanidade: abra ambos os hostnames (www e apex) via HTTPS, faça login, atualize e confirme que a barra de endereço não volta para HTTP.

Se estiver fazendo isso em uma plataforma como o Koder.ai, confirme que domínios personalizados estão conectados e que o SSL foi emitido antes de mexer no DNS de produção, e mantenha uma opção de rollback pronta para que um redirecionamento ruim ou mudança de registro não fique pendente.

Checklist rápida antes, durante e depois do corte

Uma migração calma é principalmente trabalho de preparação. O objetivo é simples: usuários devem continuar logando, cookies devem continuar funcionando e você precisa poder reverter rápido se algo estiver errado.

Antes do corte

Faça isto enquanto o tráfego ainda vai para o domínio antigo. Dê pelo menos um dia se puder, para que mudanças DNS tenham tempo de assentar.

• Reduza o TTL dos registros que vai mudar e anote os valores atuais para restaurar rapidamente.
• Documente cada hostname que irá servir (apex, www, api, etc.) e escolha o método de validação SSL (DNS ou HTTP).
• Prepare regras de redirecionamento e teste em staging: HTTP → HTTPS, www → apex (ou o inverso) e um host canônico.
• Atualize configurações de auth que dependem de URLs exatas: callbacks OAuth, allowed origins, configurações de cookie e SSO.
• Decida quem monitora o que durante o corte (logs, checagens de uptime, suporte) e defina uma janela curta para mudanças.

Durante e depois do corte

Quando você trocar o DNS, trate a primeira hora como um exercício de incidente. Observe fluxos reais de usuário, não só dashboards de status.

• Durante: monitore picos de 4xx/5xx, loops de redirecionamento e falhas de login (especialmente “invalid redirect URI” ou quedas súbitas de sessão).
• Depois: confirme a cadeia de certificados em vários navegadores e que páginas importantes carregam em HTTPS sem conteúdo misto.
• Depois: verifique o comportamento do host canônico (apenas um host na barra) e que cookies críticos são definidos e enviados.
• Depois: mantenha o domínio antigo redirecionando por um tempo. Muitos usuários voltarão por bookmarks, e‑mails ou links em cache.

Mesmo que o Koder.ai (ou outra plataforma) trate domínios personalizados e SSL para você, essa checklist continua válida. A maioria dos problemas vem de DNS e redirecionamentos, não do código da app.

Cenário de exemplo: saindo de uma URL de plataforma para um domínio personalizado

Seu app roda em um endereço temporário da plataforma como myapp.koder.ai. Está funcionando, mas você quer que clientes usem example.com, com www.example.com redirecionando para o apex, e tudo forçado para HTTPS.

Um plano DNS simples mantém o risco baixo. Antes de mudar qualquer coisa, registre o estado atual (tire snapshot se sua plataforma suportar, como o Koder.ai faz) e reduza o TTL para algo curto um dia antes.

Adicione os novos registros deixando a URL da plataforma intacta:

• example.com: registro A/ALIAS apontando para o alvo de hosting que sua plataforma fornece
• www.example.com: CNAME apontando para example.com (ou para o alvo da plataforma, dependendo do provedor)
• Mantenha myapp.koder.ai como está para sempre ter um fallback conhecido

Uma vez que o DNS esteja no lugar, solicite SSL para ambos os hostnames (example.com e www.example.com). Não mude o tráfego até que o certificado esteja emitido e ativo, caso contrário usuários verão avisos do navegador.

Linha do tempo de corte com checkpoints claros:

• T-24h: reduzir TTL, confirmar que pode reverter rápido
• T-0: habilitar domínio no host da app, verificar que o SSL está pronto
• T+15m: testar example.com em uma janela anônima (homepage, assets estáticos, chamadas de API)
• T+30m: habilitar redirecionamentos (HTTP → HTTPS e www → apex)
• Momento de rollback: se login ou chamadas de API falharem, reponha o DNS para o alvo anterior e mantenha a URL da plataforma ativa

Depois da mudança, valide comportamento de cookies. Faça login, atualize e verifique que permanece logado em www e no apex. Se sessões quebrarem, quase sempre é configuração de domínio do cookie ou SameSite ainda assumindo o host antigo.

Próximos passos: monitore, documente e torne mudanças futuras mais seguras

Depois que a migração der certo, o trabalho não acabou. A maioria das mudanças falha depois porque ninguém percebe um desgaste: um certificado perto do vencimento, uma alteração DNS feita às pressas ou um ajuste de redirecionamento que quebra um fluxo de login.

Estabeleça uma rotina de monitoramento pequena que você realmente mantenha. Não precisa de ferramenta enterprise para começar, mas precisa de alguns sinais confiáveis: checagens de disponibilidade para páginas-chave (home, login e uma página autenticada), alertas de expiração de certificado (por exemplo, 30 dias e 7 dias), monitoramento de taxa de erro (observe picos de 4xx/5xx, não só uptime) e validações ocasionais de redirecionamento (HTTP vai para HTTPS e o hostname preferido vence).

Mantenha uma janela curta de rollback, mesmo que tudo pareça bem. Por 24–72 horas, deixe a configuração anterior pronta (alvos DNS antigos, configuração de hosting antiga, ajustes TLS antigos) para poder reverter rápido se aparecer um problema escondido, como um callback de pagamento ou um provedor OAuth ainda apontando para o domínio antigo.

Quando estiver confiante, aumente novamente os TTLs. TTL baixo é útil durante mudanças, mas adiciona carga aos resolvers e aumenta impacto de pequenos erros. Escolha um TTL normal que combine com a frequência de mudanças (muitos times escolhem 1 a 4 horas).

Por fim, documente o estado final enquanto ainda estiver fresco: quais registros existem (tipo, nome, valor, TTL), quais hostnames são suportados e as regras exatas de redirecionamento. Inclua onde os certificados são emitidos, o que cobrem (apex, www, subdomínios) e quem é responsável pelas renovações.

Se você constrói e deploya em uma plataforma, ajuda quando domínios são tratados como um recurso de primeira classe e o rollback é simples. No Koder.ai, domínios personalizados ficam ao lado de snapshots e rollback, o que pode tornar mudanças futuras menos estressantes quando algo precisar ser desfeito rapidamente.