Saltar al contenido principal
Para alojar tu documentación en una subruta personalizada como yoursite.com/docs con AWS Route 53 y CloudFront, debes configurar tu proveedor de DNS para que apunte a tu distribución de CloudFront.

​
Estructura del repositorio

Los archivos de tu documentación deben organizarse dentro de tu repositorio para que coincidan con la estructura de subruta que elijas. Por ejemplo, si quieres tu documentación en yoursite.com/docs, crea un directorio docs/ con todos tus archivos de documentación.

​
Descripción general a alto nivel

Enruta el tráfico a estas rutas con una política de caché CachingDisabled:
  • /.well-known/acme-challenge/* - Obligatorio para la verificación de certificados de Let’s Encrypt
  • /.well-known/vercel/* - Obligatorio para la verificación del domain
  • /docs/* - Obligatorio para el enrutamiento por subruta
  • /docs/ - Obligatorio para el enrutamiento por subruta
Enruta el tráfico a esta ruta con una política de caché CachingEnabled:
  • /mintlify-assets/_next/static/*
  • Default (*) - La página de inicio de tu sitio web
Todos los Behaviors deben tener una origin request policy de AllViewerExceptHostHeader. Página de CloudFront "Behaviors" con 4 behaviors: /docs/*, /docs, Default, y /.well-known/*.

​
Crear una distribución de CloudFront

  1. Navega a CloudFront en la consola de AWS.
  2. Selecciona Create distribution.
Página de CloudFront Distributions con el botón «Create distribution» resaltado.
  1. En Origin domain, ingresa [SUBDOMAIN].mintlify.dev, donde [SUBDOMAIN] es el subdomain único de tu proyecto.
Página «Create distribution» de CloudFront mostrando «acme.mintlify.dev» como Origin domain.
  1. En «Web Application Firewall (WAF)», habilita las protecciones de seguridad.
Opciones de Web Application Firewall (WAF) con «Enable security protections» seleccionado.
  1. Deja el resto de la configuración con los valores predeterminados.
  2. Selecciona Create distribution.

​
Agregar origen predeterminado

  1. Después de crear la distribución, ve a la pestaña “Origins”.
Una distribución de CloudFront con la pestaña "Origins" resaltada.
  1. Busca tu URL de staging que refleje el dominio principal. Esto varía mucho según cómo esté alojada tu página de inicio. Por ejemplo, la URL de staging de Mintlify es mintlify-landing-page.vercel.app.
Si tu página de inicio está alojada en Webflow, usa la URL de staging de Webflow. Se verá como .webflow.io.Si usas Vercel, usa el domain .vercel.app disponible para cada proyecto.
  1. Crea un nuevo Origin y agrega tu URL de staging como el “Origin domain”.
Página de CloudFront "Create origin" con el campo de entrada "Origin domain" resaltado.
A este punto, deberías tener dos Origins: uno con [SUBDOMAIN].mintlify.app y otro con tu URL de staging.
Página de CloudFront "Origins" con dos orígenes: uno para mintlify y otro para mintlify-landing-page.

​
Configurar comportamientos

Los comportamientos en CloudFront permiten controlar la lógica de subrutas. A grandes rasgos, queremos implementar la siguiente lógica:
  • Si un usuario llega a tu subruta personalizada, redirigir a [SUBDOMAIN].mintlify.dev.
  • Si un usuario llega a cualquier otra página, redirigir a la página de inicio actual.
  1. Ve a la pestaña “Behaviors” de tu distribución de CloudFront.
Pestaña "Behaviors" de CloudFront resaltada.
  1. Selecciona el botón Create behavior y crea los siguientes comportamientos.

​
/.well-known/*

Crea comportamientos para las rutas de verificación de domain de Vercel con un Patrón de ruta de /.well-known/* y establece Origin and origin groups en la URL de tu documentación. Para “Cache policy”, selecciona CachingDisabled para garantizar que estas solicitudes de verificación se procesen sin caché.
Página de CloudFront "Create behavior" con un "Path pattern" de "/.well-known/*" y "Origin and origin groups" apuntando a la URL de staging.
Si .well-known/* es demasiado genérico, puede acotarse a un mínimo de 2 comportamientos para Vercel:
  • /.well-known/vercel/* - Obligatorio para la verificación de domain de Vercel
  • /.well-known/acme-challenge/* - Obligatorio para la verificación del certificado de Let’s Encrypt

​
Tu subruta personalizada

Crea un comportamiento con un Path pattern de la subruta que elijas, por ejemplo /docs, con Origin and origin groups apuntando a la URL .mintlify.dev (en nuestro caso acme.mintlify.dev).
  • Establece “Cache policy” en CachingOptimized.
  • Establece “Origin request policy” en AllViewerExceptHostHeader.
  • Establece “Viewer Protocol Policy” en Redirect HTTP to HTTPS.
Página de CloudFront "Create behavior" con un "Path pattern" de "/docs/*" y "Origin and origin groups" apuntando a la URL acme.mintlify.dev.

​
Tu subruta personalizada con comodín

Crea un comportamiento con un Patrón de ruta de la subruta que elijas seguido de /*, por ejemplo /docs/*, y con Origen y grupos de origen apuntando a la misma URL .mintlify.dev. Estas configuraciones deben coincidir exactamente con el comportamiento de tu subruta base, con la excepción del Patrón de ruta.
  • Establece «Cache policy» en CachingOptimized.
  • Establece «Origin request policy» en AllViewerExceptHostHeader.
  • Establece «Viewer protocol policy» en Redirect HTTP to HTTPS.

​
/mintlify-assets/_next/static/*

  • Establece la “política de caché” en CachingOptimized
  • Establece la “política de solicitud de origen” en AllViewerExceptHostHeader
  • Establece la “política de protocolo del visor” en Redirect HTTP to HTTPS

​
Default (*)

Por último, vamos a editar el comportamiento de Default (*).
Una distribución de CloudFront con el comportamiento "Default (*)" seleccionado y el botón Edit resaltado.
  1. Cambia Origin and origin groups del comportamiento predeterminado a la URL de staging (en nuestro caso, mintlify-landing-page.vercel.app).
Página de CloudFront "Edit behavior" con el campo de entrada "Origin and origin groups" resaltado.
  1. Selecciona Guardar cambios.

​
Verifica que los comportamientos estén configurados correctamente

Si sigues los pasos anteriores, tus comportamientos deberían verse así:
Página de CloudFront “Behaviors” con 4 comportamientos: /docs/*, /docs, Default y /.well-known/*.

​
Vista previa de la distribución

Ahora puedes comprobar si tu distribución está correctamente configurada yendo a la pestaña “General” y visitando la URL de Distribution domain name.
Pestaña "General" de CloudFront con la URL de "Distribution domain name" resaltada.
Todas las páginas deberían redirigir a tu página de inicio principal, pero si agregas la subruta que elegiste, por ejemplo /docs, a la URL, deberías ver que te lleva a tu instancia de documentación de Mintlify.

​
Conectar con Route53

Ahora vamos a llevar la funcionalidad de la distribución de CloudFront a tu dominio principal.
Para esta sección, también puedes consultar la guía oficial de AWS sobre Configurar Amazon Route 53 para enrutar el tráfico a una distribución de CloudFront
  1. Ve a Route53 en la consola de AWS.
  2. Ve a la “Hosted zone” de tu dominio principal.
  3. Selecciona Create record.
Página de "Records" de Route 53 con el botón "Create record" resaltado.
  1. Activa Alias y luego, en Route traffic to, selecciona la opción Alias to CloudFront distribution.
Página "Create record" de Route 53 con el interruptor "Alias" y el menú "Route traffic to" resaltados.
  1. Selecciona Create records.
Es posible que tengas que eliminar el registro A existente si ya hay uno.
Tu documentación ahora está disponible en la subruta elegida de tu dominio principal.
Después de configurar tu DNS, los subdomains personalizados suelen estar disponibles en pocos minutos. La propagación de DNS a veces puede tardar de 1 a 4 horas y, en casos raros, hasta 48 horas. Si tu subdomain no está disponible de inmediato, espera antes de intentar solucionarlo.
⌘I