AWS Route 53 y CloudFront

Aloja la documentación en una subruta personalizada con 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

Tus archivos de documentación deben estar organizados 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, deberías crear un directorio docs/ con todos tus archivos de documentación.

Descripción general

Encamina el tráfico a estas rutas con una política de caché CachingDisabled:

• /.well-known/acme-challenge/* - Necesario para la verificación de certificados de Let’s Encrypt
• /.well-known/vercel/* - Necesario para la verificación de dominio
• /docs/* - Necesario para el enrutamiento por subruta
• /docs/ - Necesario para el enrutamiento por subruta

Encamina 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, ingresa [SUBDOMAIN].mintlify.dev, donde [SUBDOMAIN] es el subdominio ú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 según cómo 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, utiliza el dominio .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, dirígelo a [SUBDOMAIN].mintlify.dev.
• Si un usuario llega a cualquier otra página, dirígelo 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 dominios de Vercel con un Patrón de ruta /.well-known/* y establece Origin and origin groups a la URL de tu sitio de documentación.

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

Si .well-known/* es demasiado genérico, puedes reducirlo como mínimo a 2 comportamientos para Vercel:

• /.well-known/vercel/* - Requerido para la verificación de dominios de Vercel
• /.well-known/acme-challenge/* - Requerido para la verificación de certificados de Let’s Encrypt

Tu subruta personalizada

Crea un comportamiento con un Patrón de ruta de la subruta que elijas, por ejemplo /docs, con Origen y grupos de origen 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.

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 Origen y grupos de origen que apunten 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 Save changes.

Verifica que los comportamientos estén configurados correctamente

Si sigues los pasos anteriores, los 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 dirigir a tu página principal, pero si añades 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: 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. Entra en la “Hosted zone” de tu dominio 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 necesites 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 subdominios personalizados suelen estar disponibles en pocos minutos. La propagación de DNS a veces puede tardar entre 1 y 4 horas y, en casos raros, hasta 48 horas. Si tu subdominio no está disponible de inmediato, espera antes de intentar solucionarlo.