AWS Route 53 et CloudFront

Hébergez la documentation sur un sous-chemin personnalisé avec les services AWS

Pour héberger votre documentation sur un sous-chemin personnalisé tel que yoursite.com/docs avec AWS Route 53 et CloudFront, vous devez configurer votre fournisseur DNS pour qu’il pointe vers votre distribution CloudFront. ---MDX_CONTENTEND---

Structure du dépôt

Vos fichiers de documentation doivent être organisés dans votre dépôt afin de correspondre à la structure de sous-chemin que vous avez choisie. Par exemple, si vous souhaitez que votre documentation soit accessible à l’adresse yoursite.com/docs, créez un répertoire docs/ contenant tous vos fichiers de documentation.

Vue d’ensemble

Dirigez le trafic vers ces chemins avec une stratégie de cache CachingDisabled :

• /.well-known/acme-challenge/* - Requis pour la vérification des certificats Let’s Encrypt
• /.well-known/vercel/* - Requis pour la vérification de domaine
• /docs/* - Requis pour le routage par sous-chemin
• /docs/ - Requis pour le routage par sous-chemin

Dirigez le trafic vers ce chemin avec une stratégie de cache CachingEnabled :

• /mintlify-assets/_next/static/*
• Default (*) - La page d’accueil de votre site

Tous les comportements doivent utiliser une origin request policy AllViewerExceptHostHeader.

Créer une distribution CloudFront

1. Accédez à CloudFront dans la console AWS.
2. Sélectionnez Create distribution.

3. Pour le domaine d’origine, saisissez [SUBDOMAIN].mintlify.dev, où [SUBDOMAIN] est le sous-domaine unique de votre projet.

4. Pour « Web Application Firewall (WAF) », activez les protections de sécurité.

5. Laissez les autres paramètres à leurs valeurs par défaut.
6. Sélectionnez Create distribution.

Ajouter une origine par défaut

1. Après avoir créé la distribution, accédez à l’onglet « Origins ».

2. Recherchez l’URL de préproduction qui reflète votre domaine principal. Cela dépend fortement de la façon dont votre landing page est hébergée. Par exemple, l’URL de préproduction de Mintlify est mintlify-landing-page.vercel.app.

Si votre landing page est hébergée sur Webflow, utilisez l’URL de préproduction de Webflow. Elle se présentera sous la forme .webflow.io.

Si vous utilisez Vercel, utilisez le domaine .vercel.app disponible pour chaque projet.

3. Créez une nouvelle origine et ajoutez votre URL de préproduction en tant que « Origin domain ».

À ce stade, vous devriez avoir deux origins : une avec [SUBDOMAIN].mintlify.app et une autre avec votre URL de préproduction.

Définir des comportements

Les comportements dans CloudFront permettent de contrôler la logique des sous-chemins. À un niveau général, nous voulons mettre en place la logique suivante :

• Si un utilisateur arrive sur votre sous-chemin personnalisé, rediriger vers [SUBDOMAIN].mintlify.dev.
• Si un utilisateur arrive sur n’importe quelle autre page, rediriger vers la page d’accueil actuelle.

1. Accédez à l’onglet « Behaviors » de votre distribution CloudFront.

2. Sélectionnez le bouton Create behavior et créez les comportements suivants.

/.well-known/*

Créez des comportements pour les chemins de vérification de domaine Vercel avec un Path pattern /.well-known/* et définissez Origin and origin groups sur l’URL de votre documentation.

Pour « Cache policy », sélectionnez CachingDisabled afin de garantir que ces requêtes de vérification passent sans mise en cache.

Si /.well-known/* est trop générique, vous pouvez le restreindre à au moins 2 comportements pour Vercel :

• /.well-known/vercel/* — requis pour la vérification de domaine Vercel
• /.well-known/acme-challenge/* — requis pour la vérification de certificat Let’s Encrypt

Votre sous-chemin personnalisé

Créez un comportement avec un modèle de chemin correspondant au sous-chemin de votre choix, par exemple /docs, avec Origine et groupes d’origines pointant vers l’URL .mintlify.dev (dans notre cas acme.mintlify.dev).

• Définissez « Cache policy » sur CachingOptimized.
• Définissez « Origin request policy » sur AllViewerExceptHostHeader.
• Définissez « Viewer Protocol Policy » sur Redirect HTTP to HTTPS.

Votre sous-chemin personnalisé avec caractère générique

Créez un comportement avec un Path pattern correspondant au sous-chemin de votre choix, suivi de /* (par exemple /docs/*), et des Origin and origin groups pointant vers la même URL en .mintlify.dev.

Ces paramètres doivent correspondre exactement au comportement de votre sous-chemin de base, à l’exception du Path pattern.

• Définissez « Cache policy » sur CachingOptimized.
• Définissez « Origin request policy » sur AllViewerExceptHostHeader.
• Définissez « Viewer protocol policy » sur Redirect HTTP to HTTPS

/mintlify-assets/_next/static/*

• Définissez la « Cache policy » sur CachingOptimized
• Définissez la « Origin request policy » sur AllViewerExceptHostHeader
• Définissez la « Viewer protocol policy » sur Redirect HTTP to HTTPS

Default (*)

Enfin, nous allons modifier le comportement Default (*).

1. Modifiez le paramètre Origin and origin groups du comportement par défaut pour le pointer vers l’URL de préproduction (dans notre cas mintlify-landing-page.vercel.app).

2. Sélectionnez Save changes.

Vérifiez que les comportements sont correctement configurés

Si vous avez suivi les étapes ci-dessus, vos comportements devraient apparaître comme suit :

Prévisualiser la distribution

Vous pouvez maintenant vérifier que votre distribution est correctement configurée en accédant à l’onglet « General » et en ouvrant l’URL du Distribution domain name.

Toutes les pages devraient rediriger vers votre page d’accueil principale. En revanche, si vous ajoutez le sous-chemin de votre choix, par exemple /docs, à l’URL, vous devriez être redirigé vers votre instance de documentation Mintlify.

Connecter avec Route53

Nous allons maintenant associer la distribution CloudFront à votre domaine principal.

Pour cette section, vous pouvez également consulter le guide officiel d’AWS sur la configuration d’Amazon Route 53 pour acheminer le trafic vers une distribution CloudFront

1. Accédez à Route53 dans la console AWS.
2. Accédez à la « Hosted zone » de votre domaine principal.
3. Sélectionnez Create record.

4. Activez Alias, puis, dans Route traffic to, choisissez l’option Alias to CloudFront distribution.

5. Sélectionnez Create records.

Vous devrez peut-être supprimer l’enregistrement A existant s’il y en a déjà un.

Votre documentation est maintenant en ligne au sous-chemin choisi de votre domaine principal.

Après avoir configuré votre DNS, les sous-domaines personnalisés sont généralement disponibles en quelques minutes. La propagation DNS peut parfois prendre 1 à 4 heures, et dans de rares cas jusqu’à 48 heures. Si votre sous-domaine n’est pas immédiatement disponible, veuillez patienter avant d’entreprendre tout dépannage.