Domínios custom

O que é

Todo serviço web nasce com um endereço gerado em *.apps.upuai.cloud. Um domínio custom é o seu próprio nome (exemplo.com, app.exemplo.com) apontado para esse serviço: a plataforma cuida do roteamento, do certificado TLS e — se você quiser — do redirect entre www e apex.

Adicionar um domínio

Dois caminhos, mesmo resultado. Em ambos, a plataforma mostra os registros DNS exatos que você precisa criar no seu provedor.

$ upuai domain add exemplo.com -s site

▸ Configure estes registros DNS:

  Tipo    Nome               Valor
  A       exemplo.com        <IP exibido pelo painel/CLI>
  TXT     <nome exibido>     <token de verificação>
  CNAME   www.exemplo.com    <alvo exibido pelo painel/CLI>

✓ Domínio adicionado (par: exemplo.com + www.exemplo.com).
  A verificação é automática assim que o DNS propagar.

Registros DNS

O tipo de registro depende de onde o hostname está na hierarquia do seu domínio. Os valores exatos (IP, alvo de CNAME e token de verificação) são os que o painel e a CLI exibem — não copie de exemplos.

Par apex + www

Quem digita exemplo.com espera que www.exemplo.com também funcione — e vice-versa. Por isso os dois são tratados como um par.

• Ao adicionar exemplo.com a plataforma cria www.exemplo.com automaticamente (e o contrário: adicionar www.exemplo.com cria o apex).
• O par conta como 1 domínio na quota do seu plano.
• Os dois lados ganham certificado TLS próprio assim que o DNS de cada um apontar.
• Deletar um lado deleta o par inteiro.

Host canônico (redirect entre domínios)

Dois hostnames servindo o mesmo site são duas cópias para os buscadores: o Google rastreia o dobro de páginas e divide sinais de ranking entre elas. A solução padrão é eleger um host canônico e responder 301 nos outros — é o que este recurso faz, na borda, antes de a requisição chegar ao seu app.

No painel, na aba Networking, o par mostra o seletor Host canônico: escolha exemplo.com ou www.exemplo.com e o outro lado passa a redirecionar. Qualquer domínio do serviço (inclusive o gerado *.apps.upuai.cloud) tem o campo Redirecionar para, com o código 301 (permanente, recomendado para SEO) ou 302 (temporário).

# Adicionar já com redirect (www → apex, 301)
$ upuai domain add www.exemplo.com --redirect-to exemplo.com --status 301 -s site

# Ligar ou trocar o redirect de um domínio existente
$ upuai domain update www.exemplo.com --redirect-to exemplo.com -s site

# Desligar
$ upuai domain update www.exemplo.com --no-redirect -s site

# Conferir
$ upuai domain list -s site

DOMAIN               TYPE     STATUS      REDIRECT
exemplo.com          Custom   ● Active    -
www.exemplo.com      Custom   ● Active    → exemplo.com (301)

Regras

• O alvo precisa ser um domínio do mesmo serviço e ambiente.
• Sem cadeia: um domínio que já é alvo de redirect não pode redirecionar, e vice-versa.
• Domínios wildcard (*.exemplo.com) não podem ser origem nem alvo.
• Caminho e query string são preservados: www.exemplo.com/blog?x=1 → exemplo.com/blog?x=1.
• Não precisa de redeploy — o redirect entra em até 2 minutos e some da mesma forma ao ser desligado.
• Se o domínio alvo for removido, o redirect é desligado e a origem volta a servir o site.

HTTPS e HSTS

O certificado TLS é emitido e renovado automaticamente (Let's Encrypt) para cada domínio verificado, e http:// é redirecionado para https:// na borda. HSTS — o header que faz o navegador nunca mais tentar http:// — é opt-in, declarado no upuai.toml do serviço:

#:schema https://upuai.com.br/schemas/upuai-toml-v1.json

[http.headers]
Strict-Transport-Security = "max-age=31536000"

Antes de ligar

• includeSubDomains só se TODO subdomínio do seu domínio — inclusive os que não estão na Upuai — servir HTTPS. O navegador vai recusar http:// em todos eles.
• preload entra numa lista embutida nos navegadores e, na prática, é irreversível. Só peça quando tiver certeza.
• O header vale para todos os hostnames do serviço, inclusive o endereço gerado *.apps.upuai.cloud.
• A resposta 301 de um host que redireciona não carrega os headers do serviço — o host canônico (destino) é quem os envia.

[http] do upuai.toml × redirect de domínio

São duas ferramentas para problemas diferentes. Escolha pela pergunta "isso depende do caminho ou do host?".

Troubleshooting

O que mais confunde ao testar um redirect é o método HTTP. Teste sempre com GET — é o que o navegador e o Googlebot usam.

# GET — é isto que o navegador e o Googlebot recebem
$ curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' https://www.exemplo.com/
301 https://exemplo.com/

# HEAD (curl -I) — o Traefik responde 308 a métodos não-GET em redirect permanente
$ curl -sI https://www.exemplo.com/ | head -1
HTTP/2 308

FAQ

Perguntas frequentes sobre domínios custom.

Recursos

Links relacionados.