AWS Route 53 e CloudFront
Encaminhe o tráfego de /docs pelo AWS CloudFront e Route 53 até o seu site Jamdesk. Inclui configuração de distribuição, origem e regras de cache.
Configure uma distribuição do CloudFront para encaminhar /docs/* ao seu site Jamdesk, com o Route 53 para DNS. Leva cerca de 15 minutos.
Pré-requisitos
- Uma conta AWS com acesso ao CloudFront e ao Route 53
- Seu domínio gerenciado no Route 53 (ou a capacidade de atualizar o DNS em outro lugar)
- Seu subdomínio Jamdesk (encontrado nas configurações do dashboard)
- Seu domínio personalizado registrado e verificado por DNS no dashboard Jamdesk
Se você usar um subcaminho personalizado em vez do padrão /docs, substitua /docs/* no padrão de caminho do comportamento de cache (Passo 3) pelo seu subcaminho. Atualize a distribuição novamente após qualquer renomeação no dashboard.
Etapa 1: Criar uma distribuição do CloudFront
- Abra o console do CloudFront
- Clique em Create Distribution
- Configure a origem:
| Configuração | Valor |
|---|---|
| Origin domain | YOUR_SLUG.jamdesk.app |
| Protocol | HTTPS only |
| Name | jamdesk-docs-origin |
Substitua YOUR_SLUG pelo seu subdomínio Jamdesk.
Etapa 2: Configurar as definições da origem
Adicione cabeçalhos personalizados nas definições de origem para identificar seu domínio:
| Nome do cabeçalho | Valor |
|---|---|
X-Forwarded-Host | yoursite.com |
X-Jamdesk-Forwarded-Host | yoursite.com |
Esses cabeçalhos informam ao Jamdesk qual domínio está fazendo a requisição.
Esta etapa é obrigatória. Pular esta etapa falha silenciosamente. A política AllViewerExceptHostHeader (próximo passo) apenas encaminha cabeçalhos que o navegador do visitante enviou. Ela não adiciona novos. X-Jamdesk-Forwarded-Host chega ao Jamdesk somente como um cabeçalho personalizado de origem. Sem ele, as requisições ainda têm sucesso, mas as páginas são servidas com noindex e links canônicos apontando para YOUR_SLUG.jamdesk.app em vez do seu domínio.
Cabeçalhos estáticos de origem não podem variar por requisição. Para servir vários nomes de domínio alternativos a partir de uma única distribuição, use uma CloudFront Function no evento viewer request. Faça com que ela defina request.headers['x-jamdesk-forwarded-host'] = { value: request.headers.host.value }.
Etapa 3: Criar comportamentos de cache
Adicione comportamentos para direcionar /docs/* e as requisições de recursos à sua origem Jamdesk:
- Acesse a aba Behaviors
- Clique em Create Behavior
- Crie três comportamentos com estas configurações:
| Padrão de caminho | Origem | Política de cache | Política de requisição de origem |
|---|---|---|---|
/docs/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
/_next/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
/_jd/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
Defina Viewer protocol policy como Redirect HTTP to HTTPS para os três.
Todos os comportamentos são obrigatórios. /_next/* e /_jd/* servem o JavaScript, o CSS, as fontes e as imagens que as páginas da sua documentação carregam. A política AllViewerExceptHostHeader encaminha os cabeçalhos da requisição do visitante (tudo, exceto Host, que o CloudFront reserva para a origem). Defina-a nos três.
Etapa 4: Adicionar um nome de domínio alternativo
- Na aba General, clique em Edit
- Em Alternate domain name (CNAME), adicione
yoursite.com - Selecione ou solicite um certificado SSL para o seu domínio
Etapa 5: Configurar o Route 53
Crie um registro alias apontando para a sua distribuição do CloudFront:
- Abra o console do Route 53
- Selecione a sua zona hospedada
- Clique em Create Record
- Configure:
| Configuração | Valor |
|---|---|
| Record name | yoursite.com (ou deixe em branco para o apex) |
| Record type | A |
| Alias | Yes |
| Route traffic to | CloudFront distribution |
| Distribution | Selecione a sua distribuição |
Etapa 6: Verificar
Aguarde a propagação do DNS (geralmente de 5 a 15 minutos). Depois, acesse https://yoursite.com/docs e confirme que a sua documentação carrega.
Resumo completo da configuração do CloudFront
Distribution Settings:
├── Origin: YOUR_SLUG.jamdesk.app
│ ├── Custom Header: X-Forwarded-Host = yoursite.com
│ └── Custom Header: X-Jamdesk-Forwarded-Host = yoursite.com
├── Behavior: /docs/*
│ ├── Cache Policy: CachingOptimized
│ └── Origin Request Policy: AllViewerExceptHostHeader
├── Behavior: /_next/*
│ ├── Cache Policy: CachingOptimized
│ └── Origin Request Policy: AllViewerExceptHostHeader
├── Behavior: /_jd/*
│ ├── Cache Policy: CachingOptimized
│ └── Origin Request Policy: AllViewerExceptHostHeader
└── Alternate Domain: yoursite.com (with SSL certificate)
Solução de problemas
Verifique se o domínio de origem é exatamente YOUR_SLUG.jamdesk.app, sem o prefixo https://.
Verifique se a Viewer protocol policy está definida como "Redirect HTTP to HTTPS" e se o seu certificado SSL é válido.
Crie uma invalidação do CloudFront para /docs/* para limpar o conteúdo em cache após publicar alterações.
Se você vir "Domain is not authorized to serve this content":
- Verifique se o seu domínio está registrado no dashboard Jamdesk
- Conclua a verificação de DNS (registro TXT) do seu domínio
- Defina os cabeçalhos personalizados
X-Forwarded-HosteX-Jamdesk-Forwarded-Hostna configuração da sua origem - Verifique se o seu domínio está mapeado para o projeto correto
O domínio deve estar verificado antes que o CloudFront possa servir a documentação.
A verificação prévia busca /_jd/preflight no seu domínio ativo e verifica o que chegou ao Jamdesk. Se ela informar que o seu proxy "doesn't identify itself", o CloudFront está alcançando o Jamdesk sem X-Jamdesk-Forwarded-Host. Revise o cabeçalho personalizado de origem no Passo 2. Consulte Custom domain only para entender o que cada mensagem da verificação prévia significa.
