Saltar al contenido principal
Para alojar tu documentación en una subruta 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. Antes de configurar AWS, define tu ruta base en tu dashboard:
  1. Ve a la página de configuración de dominio personalizado en tu dashboard.
  2. Habilita el interruptor Host at e ingresa tu ruta base. Por ejemplo, /docs o /help.
  3. Ingresa tu dominio.
  4. Ingresa tu ruta base.
  5. Haz clic en Add domain.

​
Descripción general

Los siguientes ejemplos usan la ruta base /docs. Si utilizas otra ruta base, reemplaza /docs por la tuya.
Dirige 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 dominio
  • /docs/* - Obligatorio para el enrutamiento por subruta
  • /docs/ - Obligatorio para el enrutamiento por subruta
Dirige 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 comportamientos (Behaviors) deben tener una origin request policy de AllViewerExceptHostHeader. Los comportamientos de tu subruta deben permitir todos los métodos HTTP. CloudFront solo permite solicitudes GET y HEAD de forma predeterminada, lo que bloquea las solicitudes POST que Mintlify usa para analíticas y otras funciones interactivas. 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.site, donde [SUBDOMAIN] es el subdomain único de tu proyecto.
Página «Create distribution» de CloudFront mostrando «acme.mintlify.site» 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.
Las reglas de WAF pueden bloquear las solicitudes POST que Mintlify usa para analíticas y otras funciones interactivas. Si las analíticas dejan de aparecer en tu panel después de habilitar WAF, revisa los registros de WAF en busca de solicitudes bloqueadas a rutas bajo /docs/_mintlify/.
  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 según el proveedor de alojamiento de tu página de inicio. Por ejemplo, la URL de staging de Mintlify es mintlify-landing-page.vercel.app.
Si Webflow aloja tu página de inicio, 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.site 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.site.
  • 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, puedes acotarlo 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

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.site (en nuestro caso acme.mintlify.site).
  • Establece “Cache policy” en CachingDisabled.
  • Establece “Origin request policy” en AllViewerExceptHostHeader.
  • Establece “Viewer protocol policy” en Redirect HTTP to HTTPS.
  • Establece “Allowed HTTP methods” en GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
CloudFront solo permite solicitudes GET y HEAD de forma predeterminada. Si no permites todos los métodos HTTP, CloudFront rechaza las solicitudes POST que Mintlify usa para analíticas, y tu panel no mostrará ninguna vista de página aunque tu documentación se cargue normalmente.
Página "Create behavior" de CloudFront con un "Path pattern" de "/docs/*" y "Origin and origin groups" apuntando a la URL acme.mintlify.site.

​
Tu subruta con comodín

Crea un comportamiento con un Path pattern que sea la subruta que elijas seguida de /*, por ejemplo /docs/*, y con Origin and origin groups apuntando a la misma URL .mintlify.site. Esta configuración debe coincidir exactamente con el comportamiento de tu subruta base, con la excepción de Path pattern.
  • Establece “Cache policy” en CachingDisabled.
  • Establece “Origin request policy” en AllViewerExceptHostHeader.
  • Establece “Viewer protocol policy” en Redirect HTTP to HTTPS.
  • Establece “Allowed HTTP methods” en GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.

​
/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 hayas configurado los comportamientos 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 configuraste tu distribución correctamente 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 Route 53

Ahora vamos a llevar las capacidades 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 desplegar tus cambios, tu documentación suele estar disponible en tu subruta en unos minutos. Si tu configuración incluye cambios de DNS, la propagación puede tardar entre 1 y 4 horas y, en casos excepcionales, hasta 48 horas. Si tu documentación no está disponible de inmediato, espera antes de intentar solucionar el problema.