Domínio personalizado: como usar seu próprio domínio no app

Todo app hospedado nasce com um endereço técnico, algo como meuapp.exemplo-host.app. Funciona, mas ninguém quer mandar esse link para um cliente. Um domínio personalizado troca esse endereço por meusite.com.br ou app.meusite.com.br, e o app continua o mesmo.

O processo sempre envolve três peças: o domínio, registrado no seu registrador; o DNS, onde você diz para onde cada nome aponta; e a hospedagem, que precisa reconhecer aquele nome para servir o app e emitir o certificado. Se uma peça não bate com as outras, o domínio não abre.

O que preciso ter antes de começar?#

• Um domínio registrado em seu nome, em qualquer registrador (Registro.br, Namecheap, GoDaddy e outros).
• Acesso ao painel de DNS do domínio. Se o DNS foi delegado a outro provedor, como a Cloudflare, é nele que você edita.
• Um app web no ar na hospedagem, respondendo no endereço técnico dela.
• Um plano que permita domínio próprio. Nem toda hospedagem libera isso em todos os planos, então confira antes de começar.

Se ainda não está clara a diferença entre comprar domínio e contratar hospedagem, veja domínio vs. hospedagem.

Raiz, www ou subdomínio: qual usar?#

Para o DNS, os três são nomes diferentes:

• Raiz (meusite.com.br): o nome sem prefixo, também chamado de apex.
• www (www.meusite.com.br): um subdomínio como outro qualquer.
• Outro subdomínio (app.meusite.com.br, api.meusite.com.br): bom para separar o app do site institucional.

A diferença prática está no tipo de registro. Pela RFC 1034, um CNAME não convive com outros dados no mesmo nome, e a raiz sempre tem registros NS e SOA. Por isso a raiz geralmente usa um registro A (ou AAAA, para IPv6), enquanto o www e os demais subdomínios usam CNAME. Alguns provedores de DNS oferecem CNAME flattening, que permite apontar a raiz para um nome; outros chamam recursos parecidos de ALIAS ou ANAME.

Na dúvida, comece por um subdomínio: é o caminho com menos restrições.

Como adicionar o domínio, passo a passo?#

1. Cadastre o domínio na hospedagem. No painel do app, informe exatamente o nome que as pessoas vão digitar, por exemplo app.meusite.com.br.

2. Copie os registros que a hospedagem mostra. Ela informa o tipo (A ou CNAME) e o valor de destino. Use sempre esses valores, nunca os de outro tutorial.

3. Crie os registros no DNS. Exemplo genérico para um subdomínio:

   Tipo	Nome (host)	Valor	TTL
   CNAME	app	destino-da-hospedagem.exemplo	300

   E para a raiz e o www:

   Tipo	Nome (host)	Valor	TTL
   A	@	203.0.113.10	300
   CNAME	www	meusite.com.br.	300

   Os valores destino-da-hospedagem.exemplo e 203.0.113.10 são fictícios.

4. Apague conflitos. Um A ou AAAA antigo no mesmo nome de um CNAME costuma fazer o painel recusar o registro.

5. Aguarde o DNS e a validação. Assim que a hospedagem enxergar o registro, ela aceita o domínio.

Se o painel de DNS completa o domínio sozinho, digite só o prefixo (app). Se você digitar o nome inteiro, o resultado é app.meusite.com.br.meusite.com.br, um erro muito comum. O passo a passo de DNS em detalhe está em como apontar um domínio para sua hospedagem.

Como saber se o domínio está funcionando?#

Consulte o DNS diretamente, sem passar pelo cache do navegador:

dig app.meusite.com.br CNAME +short
dig meusite.com.br A +short

A resposta deve ser o destino que a hospedagem indicou. Depois confirme o HTTP e o certificado:

curl -I https://app.meusite.com.br

Um status 200 (ou um redirecionamento esperado) com o certificado aceito indica que está tudo certo. Se o dig já responde certo mas o navegador mostra o endereço antigo, o problema é cache: teste numa aba anônima.

O tempo até a mudança valer depende do TTL do registro anterior, que fica em cache nos resolvedores. Um nome novo costuma resolver em minutos; trocar um registro existente com TTL de 3600 pode levar até uma hora. Antes de migrar um domínio em uso, baixe o TTL para 300 e espere o valor antigo expirar.

E o HTTPS?#

O certificado só pode ser emitido depois que o domínio resolve para a hospedagem, porque você precisa provar à autoridade certificadora que controla o nome. Em hospedagens com TLS automático, a emissão acontece sozinha logo em seguida. Para entender o mecanismo, veja como o Let's Encrypt funciona.

Registros CAA restringem quais autoridades podem emitir certificados para o domínio (RFC 8659). Sem nenhum CAA, qualquer autoridade pode emitir. Se houver algum, inclua a autoridade que a sua hospedagem usa. Para o Let's Encrypt, o valor é letsencrypt.org, segundo a documentação dele:

meusite.com.br.  CAA  0 issue "letsencrypt.org"

Confirme com a hospedagem qual autoridade ela usa antes de criar um CAA.

Quais são os erros mais comuns?#

• CNAME na raiz: o painel recusa. Use A ou um provedor com CNAME flattening.
• Registro conflitante: um A antigo no mesmo nome do CNAME.
• Nameservers errados: você edita o DNS no registrador, mas o domínio está delegado a outro provedor. Confira com dig NS meusite.com.br +short.
• Só um dos nomes configurado: meusite.com.br abre e www.meusite.com.br não. Cadastre os dois.
• Proxy da Cloudflare ligado na validação: o registro proxied esconde o destino real e pode atrapalhar a validação. Teste em DNS only.
• CAA bloqueando a emissão: veja a seção anterior.
• Erro de domínio inexistente: veja DNS_PROBE_FINISHED_NXDOMAIN.

Se o navegador mostrar erro de certificado, o guia de erros de certificado SSL explica as causas.

Como fazer isso na Square Cloud#

Na Square Cloud, as três peças deste guia ficam bem separadas. O domínio segue registrado em seu nome no seu registrador, a zona DNS continua no registrador ou no provedor de DNS que você escolheu, e a plataforma reconhece o nome e entrega o HTTPS. O domínio personalizado está disponível a partir do plano Standard (a partir de R$ 44,99 por mês). O Hobby não inclui esse recurso e usa o subdomínio *.squareweb.app, que toda aplicação web recebe com HTTPS em todo plano.

O passo a passo é o da seção acima, com valores fixos. No painel da aplicação, você adiciona o domínio e vê os dois registros a criar: um CNAME para cname.squareweb.app e um TXT de validação. O status da validação aparece em tempo real, e o certificado é emitido e renovado automaticamente depois que o DNS resolve. Para usar a raiz, o seu provedor de DNS precisa aceitar CNAME na raiz (flattening ou ALIAS); para o www, o recomendado é redirecionar para o domínio principal. Domínios com acento (Punycode) são aceitos, e o painel oferece purge de cache.

Com o domínio no ar, o mesmo nome pode atender mais de uma aplicação com load balancing. Veja os detalhes em domínios personalizados e compare os planos em preços.