Jamdesk Documentation logo

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

  1. Abra o console do CloudFront
  2. Clique em Create Distribution
  3. Configure a origem:
ConfiguraçãoValor
Origin domainYOUR_SLUG.jamdesk.app
ProtocolHTTPS only
Namejamdesk-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çalhoValor
X-Forwarded-Hostyoursite.com
X-Jamdesk-Forwarded-Hostyoursite.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:

  1. Acesse a aba Behaviors
  2. Clique em Create Behavior
  3. Crie três comportamentos com estas configurações:
Padrão de caminhoOrigemPolítica de cachePolítica de requisição de origem
/docs/*jamdesk-docs-originCachingOptimizedAllViewerExceptHostHeader
/_next/*jamdesk-docs-originCachingOptimizedAllViewerExceptHostHeader
/_jd/*jamdesk-docs-originCachingOptimizedAllViewerExceptHostHeader

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

  1. Na aba General, clique em Edit
  2. Em Alternate domain name (CNAME), adicione yoursite.com
  3. 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:

  1. Abra o console do Route 53
  2. Selecione a sua zona hospedada
  3. Clique em Create Record
  4. Configure:
ConfiguraçãoValor
Record nameyoursite.com (ou deixe em branco para o apex)
Record typeA
AliasYes
Route traffic toCloudFront distribution
DistributionSelecione 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":

  1. Verifique se o seu domínio está registrado no dashboard Jamdesk
  2. Conclua a verificação de DNS (registro TXT) do seu domínio
  3. Defina os cabeçalhos personalizados X-Forwarded-Host e X-Jamdesk-Forwarded-Host na configuração da sua origem
  4. 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.

O que vem a seguir?

Custom Domain Only

Impeça que o seu subdomínio responda diretamente

Custom Domains

Verifique o DNS e solucione problemas

Subpath Hosting

Sirva a documentação em /docs