AWS Route 53 y CloudFront

Aloja la documentación en una subruta personalizada usando servicios de AWS

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 documentación deben organizarse dentro de tu repositorio para que coincidan con la estructura de subruta que elijas. Por ejemplo, si quieres que tu documentación esté en yoursite.com/docs, crea un directorio docs/ con todos tus archivos de documentación.

​

Descripción general

Redirige 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

Redirige 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 deben tener una política de solicitud de origen de AllViewerExceptHostHeader.

​

Crear una distribución de CloudFront

1. Ve a CloudFront en la consola de AWS.
2. Selecciona Create distribution.

3. En Origin domain, introduce [SUBDOMAIN].mintlify.dev, donde [SUBDOMAIN] es el subdomain único de tu proyecto.

4. En “Web Application Firewall (WAF)”, habilita las protecciones de seguridad.

5. Deja el resto de la configuración con los valores predeterminados.
6. Selecciona Create distribution.

​

Agregar origen predeterminado

1. Después de crear la distribución, ve a la pestaña “Origins”.

2. Busca tu URL de staging que refleje el dominio principal. Esto varía mucho según dónde esté alojada tu landing page. Por ejemplo, la URL de staging de Mintlify es mintlify-landing-page.vercel.app.

Si tu landing page 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.

3. Crea un nuevo Origin y agrega tu URL de staging como el “Origin domain”.

A estas alturas, deberías tener dos Origins: uno con [SUBDOMAIN].mintlify.app y otro con tu URL de staging.

​

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, dirigir a [SUBDOMAIN].mintlify.dev.
• Si un usuario llega a cualquier otra página, dirigir a la página de inicio actual.

1. Ve a la pestaña “Behaviors” de tu distribución de CloudFront.

2. Selecciona el botón Create behavior y crea los siguientes comportamientos.

​

/.well-known/*

Crea comportamientos para las rutas de verificación de dominio de Vercel con un Patrón de ruta de /.well-known/* y configura Origin and origin groups a la URL de tu documentación.

Para “Cache policy”, selecciona CachingDisabled para asegurarte de que estas solicitudes de verificación se transmitan sin caché.

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 dominio de Vercel
• /.well-known/acme-challenge/* - Obligatorio para la verificación de certificados de Let’s Encrypt

​

Tu subruta personalizada

Crea un comportamiento con un Patrón de ruta para la subruta que elijas, por ejemplo /docs, con Origin and origin groups apuntando a la URL .mintlify.dev (en nuestro caso acme.mintlify.dev).

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

​

Tu subruta personalizada con comodín

Crea un comportamiento con un Patrón de ruta de la subruta que elijas seguida de /*, por ejemplo /docs/*, y Origen y grupos de orígenes apuntando a la misma URL .mintlify.dev.

Estos ajustes 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/*

• Configura “Cache policy” en CachingOptimized
• Configura “Origin request policy” en AllViewerExceptHostHeader
• Configura “Viewer protocol policy” en Redirect HTTP to HTTPS

​

Default (*)

Por último, vamos a editar el comportamiento Default (*).

1. Cambia Origin and origin groups del comportamiento predeterminado a la URL de staging (en nuestro caso, mintlify-landing-page.vercel.app).

2. Selecciona Guardar cambios.

​

Comprueba que los comportamientos estén configurados correctamente

Si seguiste los pasos anteriores, tus comportamientos deberían verse así:

​

Vista previa de la distribución

Ahora puedes comprobar si tu distribución está configurada correctamente yendo a la pestaña “General” y visitando la URL de Distribution domain name.

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 llevaremos la funcionalidad de la distribución de CloudFront a tu domain 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 domain principal.
3. Selecciona Create record.

4. Activa Alias y luego, en Route traffic to, elige la opción Alias to CloudFront distribution.

5. Selecciona Create records.

Es posible que debas eliminar el registro A existente si ya hay uno.

Tu documentación ahora está disponible en la subruta que elegiste para tu domain 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.