AWS Route 53 e CloudFront

Hospede a documentação em um subcaminho personalizado usando serviços da AWS

Para hospedar sua documentação em um subcaminho personalizado, como yoursite.com/docs, usando o AWS Route 53 e o CloudFront, você precisa configurar seu provedor de DNS para apontar para sua distribuição do CloudFront.

Estrutura do repositório

Seus arquivos de documentação devem ser organizados no repositório para corresponder à estrutura de subcaminho escolhida. Por exemplo, se você quiser a documentação em yoursite.com/docs, crie um diretório docs/ com todos os arquivos de documentação.

Visão geral

Direcione o tráfego para estes caminhos com a Política de Cache CachingDisabled:

• /.well-known/acme-challenge/* - Necessário para a verificação de certificado do Let’s Encrypt
• /.well-known/vercel/* - Necessário para verificação de domínio
• /docs/* - Necessário para roteamento por subcaminho
• /docs/ - Necessário para roteamento por subcaminho

Direcione o tráfego para este caminho com a Política de Cache CachingEnabled:

• /mintlify-assets/_next/static/*
• Default (*) - Página inicial do seu site

Todos os comportamentos devem ter a origin request policy AllViewerExceptHostHeader.

Criar distribuição do CloudFront

1. Acesse o CloudFront no console da AWS.
2. Selecione Create distribution.

3. Em Origin domain, insira [SUBDOMAIN].mintlify.dev, onde [SUBDOMAIN] é o subdomínio exclusivo do seu projeto.

4. Em “Web Application Firewall (WAF)”, ative as proteções de segurança.

5. Deixe as demais configurações no padrão.
6. Selecione Create distribution.

Adicionar origem padrão

1. Após criar a distribuição, vá até a guia “Origins”.

2. Encontre a sua URL de staging que replica o domínio principal. Isso varia bastante dependendo de como a sua landing page está hospedada. Por exemplo, a URL de staging da Mintlify é mintlify-landing-page.vercel.app.

Se a sua landing page estiver hospedada no Webflow, use a URL de staging do Webflow. Ela terá o formato .webflow.io.

Se você usa Vercel, utilize o domínio .vercel.app, disponível para cada projeto.

3. Crie uma nova Origin e adicione a sua URL de staging como o “Origin domain”.

Neste ponto, você deve ter duas Origins: uma com [SUBDOMAIN].mintlify.app e outra com a sua URL de staging.

Definir comportamentos

Os comportamentos no CloudFront permitem controlar a lógica de subcaminhos. Em linhas gerais, queremos criar a seguinte lógica:

• Se um usuário acessar seu subcaminho personalizado, redirecione para [SUBDOMAIN].mintlify.dev.
• Se um usuário acessar qualquer outra página, redirecione para a página inicial atual.

1. Acesse a guia “Behaviors” da sua distribuição do CloudFront.

2. Selecione o botão Create behavior e crie os seguintes comportamentos.

/.well-known/*

Crie comportamentos para os caminhos de verificação de domínio da Vercel com um Path pattern de /.well-known/* e defina Origin and origin groups para a URL da sua documentação.

Para “Cache policy”, selecione CachingDisabled para garantir que essas solicitações de verificação passem sem cache.

Se .well-known/* for muito genérico, você pode restringir para, no mínimo, 2 comportamentos para a Vercel:

• /.well-known/vercel/* - Necessário para verificação de domínio da Vercel
• /.well-known/acme-challenge/* - Necessário para verificação de certificado do Let’s Encrypt

Seu subcaminho personalizado

Crie um comportamento com um Padrão de caminho do subcaminho escolhido, por exemplo /docs, com Origin and origin groups apontando para a URL .mintlify.dev (no nosso caso, acme.mintlify.dev).

• Defina “Cache policy” como CachingOptimized.
• Defina “Origin request policy” como AllViewerExceptHostHeader.
• Defina “Viewer Protocol Policy” como Redirect HTTP to HTTPS.

Seu subcaminho personalizado com curinga

Crie um comportamento com um Padrão de caminho do subcaminho escolhido seguido de /*, por exemplo /docs/*, e Origem e grupos de origem apontando para a mesma URL .mintlify.dev.

Essas configurações devem corresponder exatamente ao comportamento do seu subcaminho base, com exceção do Padrão de caminho.

• Defina “Cache policy” como CachingOptimized.
• Defina “Origin request policy” como AllViewerExceptHostHeader.
• Defina “Viewer protocol policy” como Redirect HTTP to HTTPS

/mintlify-assets/_next/static/*

• Defina “Cache policy” como CachingOptimized
• Defina “Origin request policy” como AllViewerExceptHostHeader
• Defina “Viewer protocol policy” como Redirect HTTP to HTTPS

Default (*)

Por fim, vamos editar o comportamento Default (*).

1. Altere Origin and origin groups do comportamento padrão para a URL de staging (no nosso caso, mintlify-landing-page.vercel.app).

2. Selecione Save changes.

Verifique se os comportamentos estão configurados corretamente

Se você seguir as etapas acima, seus comportamentos deverão ficar assim:

Pré-visualização da distribuição

Agora você pode testar se sua distribuição está configurada corretamente acessando a guia “General” e visitando a URL de Distribution domain name.

Todas as páginas devem redirecionar para sua página inicial principal, mas se você adicionar o subcaminho escolhido — por exemplo, /docs — à URL, deverá ver que ela aponta para sua instância de documentação do Mintlify.

Conectar o Route53

Agora, vamos levar a funcionalidade da distribuição CloudFront para o seu domínio principal.

Para esta seção, você também pode consultar o guia oficial da AWS: Configurar o Amazon Route 53 para rotear tráfego para uma distribuição do CloudFront

1. Acesse o Route53 no console da AWS.
2. Vá até a “Hosted zone” do seu domínio principal.
3. Selecione Create record.

4. Ative Alias e, em Route traffic to, escolha a opção Alias to CloudFront distribution.

5. Selecione Create records.

Pode ser necessário remover o registro A existente, caso haja um.

Sua documentação agora está ativa no subcaminho escolhido do seu domínio principal.

Após configurar o seu DNS, subdomínios personalizados geralmente ficam disponíveis em poucos minutos. A propagação do DNS às vezes pode levar de 1 a 4 horas e, em casos raros, até 48 horas. Se o seu subdomínio não estiver disponível imediatamente, aguarde antes de tentar solucionar o problema.