Configurar um domínio personalizado para sua central de ajuda

Este guia mostra como apontar um domínio que você possui (por exemplo ajuda.suaempresa.com) para a sua central de ajuda do Deskwoot. Nenhum conhecimento técnico necessário, explicamos cada passo além do que está acontecendo nos bastidores. Tempo total: 5 minutos de configuração e depois 2 a 10 minutos de espera. Disponível no plano Enterprise.

O que você está fazendo em palavras simples

No momento sua central de ajuda fica em suaempresa.deskwoot.com. Isso é perfeitamente normal, mas empresas maiores costumam querer a central em um subdomínio da própria marca, como ajuda.suaempresa.com ou suporte.suaempresa.com. Para que isso funcione, você precisa dizer à agenda global de endereços da internet (o DNS) que ajuda.suaempresa.com deve servir o conteúdo da central de ajuda do Deskwoot.

Você faz isso adicionando dois pequenos registros no seu registrador de domínios (Cloudflare, GoDaddy, Namecheap, Google Domains, etc.). Um registro aponta o tráfego para nós. O outro nos permite instalar automaticamente um certificado SSL gratuito para que a página carregue com o cadeado verde. É só isso.

Antes de começar

Você precisa ser administrador na sua conta do Deskwoot.
Você precisa estar no plano Enterprise. Os planos inferiores veem o mesmo painel bloqueado.
Você precisa de acesso ao seu provedor de DNS. É onde você comprou o domínio (ou para onde moveu o DNS dele). Os mais comuns: Cloudflare, GoDaddy, Namecheap, Route 53, Google Domains.
Escolha um subdomínio, não o domínio raiz. Subdomínios como ajuda, suporte ou docs funcionam. O domínio raiz (suaempresa.com sozinho) NÃO funciona, explicaremos por que mais adiante.

Passo 1: insira o domínio no Deskwoot

Abra a Central de Ajuda no painel do Deskwoot.
Clique na aba Configurações no painel à direita.
Role até a seção Domínio personalizado.
Digite o hostname completo que você quer (por exemplo ajuda.acme.com) e clique em Registrar.

O Deskwoot reserva o hostname na nossa camada de borda e mostra dois registros DNS para você adicionar no seu provedor de DNS. Ambos os registros têm um botão Copiar ao lado. A etiqueta de status muda para "Aguardando DNS".

Passo 2: adicione os dois registros DNS no seu provedor

Você vai adicionar dois registros. Ambos são registros CNAME. Um CNAME é apenas uma entrada do tipo "este nome aponta para aquele outro nome" no DNS. A maioria dos provedores tem um formulário simples: escolha o tipo (CNAME), digite um Nome, digite um Valor, salve.

Registro 1: o CNAME principal (encaminha seus visitantes para o Deskwoot)

Tipo: CNAME
Nome / Host: a parte de subdomínio do seu hostname. Se você registrou ajuda.acme.com, isto é ajuda. A maioria dos provedores acrescenta o resto automaticamente, mas alguns querem o hostname completo (ajuda.acme.com). Ambos funcionam, dependendo do seu provedor.
Valor / Destino / Aponta para: copie isto do painel do Deskwoot. Tem a aparência de xxxxx.up.railway.app.
TTL: deixe em automático / padrão (normalmente 300 segundos = 5 minutos).
Proxy / nuvem laranja do Cloudflare: DESLIGADO (somente DNS, veja as observações específicas do Cloudflare abaixo).

Registro 2: o CNAME do desafio ACME (permite que emitamos o certificado SSL)

Tipo: CNAME (alguns provedores também aceitam TXT, mas o CNAME é o preferido).
Nome / Host: _acme-challenge.ajuda (ou _acme-challenge.ajuda.acme.com dependendo do provedor, veja o valor exato no painel).
Valor / Destino: o valor que o Deskwoot mostra ao lado da linha ACME. Tem a aparência de xxxxx.dns.railwaydns.net.
TTL: automático / padrão.
Proxy / nuvem laranja do Cloudflare: DESLIGADO.

Os dois registros são obrigatórios. Se você adicionar só o primeiro, a página não carrega por HTTPS, porque o certificado SSL não pode ser emitido sem o registro do desafio ACME.

Passo 3: aguarde e depois clique em "Verificar agora"

As mudanças de DNS levam tempo para se propagar pelo mundo. Propagação típica:

Cloudflare: 1 a 2 minutos.
Namecheap / GoDaddy / Google Domains: 5 a 15 minutos.
Provedores antigos ou lentos / TTL alto: até 24 horas (raro).

Depois que passarem alguns minutos, volte ao painel do Deskwoot e clique em Verificar agora no painel de Domínio personalizado. A etiqueta de status vai atualizar:

Aguardando DNS: seus registros CNAME ainda não estão visíveis de onde o Deskwoot está verificando. Espere mais um minuto ou dois.
Emitindo certificado SSL: o DNS está bom, o Let's Encrypt está gerando seu certificado. Normalmente leva menos de um minuto.
No ar: seu domínio está servindo tráfego com HTTPS. Pronto.

O botão Verificar agora tem um intervalo de espera de 10 segundos para você não clicar nele à toa. A propagação de DNS não fica mais rápida só porque você clica mais.

O que acontece nos bastidores

Você não precisa saber disto para fazer funcionar, mas para os curiosos:

Quando você clica em Registrar, o Deskwoot avisa o Railway (nossa plataforma de hospedagem) para adicionar seu hostname à tabela de roteamento dele.
O Railway gera um par de destinos DNS: o CNAME principal para encaminhar o tráfego, e um CNAME especial de desafio ACME que permite ao Let's Encrypt verificar que você controla o domínio.
Você adiciona os dois registros no seu provedor de DNS.
O observador de DNS em segundo plano do Railway consulta os registros a cada poucos segundos.
Assim que os dois registros ficam visíveis globalmente, o Railway pede automaticamente ao Let's Encrypt um certificado SSL gratuito via protocolo ACME.
O Let's Encrypt valida o desafio (ele confirma que seu CNAME _acme-challenge.<domínio> aponta para onde dissemos que apontaria), emite o certificado, e o Railway o instala na borda.
Seu domínio agora serve tráfego HTTPS. O certificado se renova sozinho a cada 60 a 90 dias; você nunca precisa mexer nele.

Custo: $0. Os certificados do Let's Encrypt são gratuitos, o Railway os provisiona para nós sem custo extra, e o Deskwoot inclui domínios personalizados no plano Enterprise sem taxa por domínio.

Observações específicas por provedor

Cloudflare

O erro mais comum: deixar a nuvem laranja (proxy) LIGADA. O proxy do Cloudflare encerra a requisição antes que ela chegue ao Railway, o que quebra tanto o CNAME principal quanto o desafio ACME. Clique na nuvem laranja para trocá-la por uma nuvem cinza (somente DNS) nos DOIS registros.
Se você usa o Universal SSL do Cloudflare, ele pode avisar sobre um conflito. Ignore o aviso, o certificado que instalamos na borda do Deskwoot é o que seus visitantes veem.
A propagação no Cloudflare é rápida: normalmente 60 a 90 segundos.

GoDaddy

Na página de Gerenciamento de DNS, use o botão "Adicionar" e depois CNAME.
Para o registro ACME, o campo Host aceita o formato completo _acme-challenge.ajuda.
O GoDaddy remove os pontos finais do campo Valor, isso é esperado.

Namecheap

Vá em Domain List, depois Manage, depois Advanced DNS.
Add New Record, depois CNAME Record.
No campo Host, "ajuda" acrescenta automaticamente .suaempresa.com.

Google Domains / Squarespace Domains

O Google migrou a maioria dos clientes de domínio para o Squarespace em 2024. Qualquer uma das plataformas tem o mesmo fluxo de CNAME.
Procure por "DNS", depois "Manage custom records", depois Add, depois CNAME.

AWS Route 53

Abra a zona hospedada do seu domínio, depois Create record, depois CNAME.
Use o hostname completo no campo Name. O Route 53 não acrescenta nada automaticamente.

Por que o domínio raiz não funciona

Você não pode usar suaempresa.com sozinho (sem subdomínio) porque o padrão de DNS não permite registros CNAME na "raiz" de um domínio. Isso é chamado de domínio "apex" ou "nu".

Se você realmente quer a central de ajuda no seu domínio raiz, tem duas opções:

Use um subdomínio (recomendado): ajuda.suaempresa.com, suporte.suaempresa.com, docs.suaempresa.com.
Use o recurso "ALIAS" ou "ANAME" do seu provedor de DNS, se ele oferecer (CNAME Flattening do Cloudflare, registros alias do Route 53, ALIAS do DNSimple). Esses são contornos específicos de cada fornecedor e não têm suporte formal.

Solução de problemas

Travado em "Aguardando DNS"

Você adicionou OS DOIS registros? Só um não funciona. Você precisa do CNAME principal e do CNAME _acme-challenge.
Você copiou o Valor exato do Deskwoot? Até um pequeno erro de digitação (caractere a mais, ponto faltando) quebra a busca.
Você desligou o proxy do Cloudflare? Nuvem laranja significa "com proxy" e quebra o desafio. Nuvem cinza é o correto.
Existe um registro A conflitante? Se antes você tinha ajuda.suaempresa.com apontando para outro lugar com um registro A, exclua-o. Um CNAME não pode coexistir com outros registros no mesmo nome.
Verifique os registros com uma ferramenta externa: rode dig CNAME ajuda.suaempresa.com em um terminal, ou use uma ferramenta web de consulta de DNS. Você deve ver o destino do Railway. Se não vir, o registro ainda não se propagou.

Travado em "Emitindo certificado SSL" por mais de 2 minutos

Causa mais comum: o CNAME _acme-challenge está faltando, apontando para o destino errado, ou também com proxy pelo Cloudflare.
Verifique-o especificamente: dig CNAME _acme-challenge.ajuda.suaempresa.com deve retornar o destino railwaydns.net.
Alguns provedores de DNS removem o prefixo de sublinhado ou o transformam. Se o seu provedor não aceita nomes que começam com _, troque de provedor para este domínio ou fale com a gente, podemos ajudar a contornar.

O domínio mostra "No ar" mas a página exibe um aviso de segurança no navegador

Force uma recarga da página (Cmd+Shift+R no Mac, Ctrl+Shift+R no Windows). Os navegadores guardam os certificados SSL em cache de forma agressiva.
Espere 1 a 2 minutos. Às vezes o certificado é emitido mas ainda não está instalado em todos os nós de borda.
Tente uma janela anônima / privada.

Quero usar um domínio diferente, como faço para mudar?

Clique em Remover no painel de Domínio personalizado. Isso cancela o registro do hostname no Railway e limpa os valores de DNS do Deskwoot.
Exclua os registros CNAME antigos no seu provedor de DNS (opcional, mas mais organizado).
Registre o novo hostname e adicione os registros DNS dele.

Perguntas frequentes

Há algum custo pelo domínio personalizado ou pelo SSL?

Não. Os dois estão incluídos no plano Enterprise sem taxa extra. O certificado SSL é emitido pelo Let's Encrypt (gratuito) e o Railway o instala para nós (gratuito no nosso caso de uso). Você só paga ao seu provedor de DNS pelo próprio registro do domínio, o que não tem relação com o Deskwoot.

E quanto às renovações?

Os certificados do Let's Encrypt duram 90 dias. O Railway os renova automaticamente antes de expirarem, normalmente a cada 60 dias. Você nunca precisa mexer nisso.

Posso usar vários domínios personalizados para a mesma central de ajuda?

Hoje não, um domínio personalizado por portal da central de ajuda. Se você quer vários portais com marca própria, crie um portal separado por marca e registre um domínio separado para cada um.

A URL deskwoot.com para de funcionar quando eu adiciono um domínio personalizado?

Não. As duas URLs servem a mesma central de ajuda em paralelo. Você pode escolher qual delas compartilhar com os clientes; a outra continua funcionando como reserva.

Ainda posso personalizar a central de ajuda depois de ir ao ar em um domínio personalizado?

Sim, tudo nas configurações da Central de Ajuda (categorias, artigos, design, identidade visual, white-label) continua funcionando exatamente igual. O domínio personalizado só muda de onde a página é servida.

E se meu domínio expirar ou eu movê-lo para outro provedor?

Se o seu domínio expirar ou os registros DNS forem excluídos, os visitantes verão um erro de "não foi possível acessar este site" no navegador. A URL <slug>.deskwoot.com continua funcionando em paralelo. Adicione os registros CNAME de novo (ou transfira o DNS de volta) para restaurar o domínio personalizado.