Passer au contenu principal
Pour héberger votre documentation à un sous-chemin personnalisé comme yoursite.com/docs avec AWS Route 53 et CloudFront, vous devez configurer votre fournisseur DNS pour qu’il pointe vers votre distribution CloudFront.

​
Structure du dépôt

Organisez les fichiers de votre documentation dans votre dépôt pour respecter la structure de sous-chemin choisie. Par exemple, si vous souhaitez que votre documentation soit disponible à 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 de certificat 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 (*) - Page d’accueil de votre site
Tous les comportements doivent utiliser une origin request policy AllViewerExceptHostHeader. Page « Behaviors » de CloudFront avec 4 comportements : /docs/*, /docs, Default, et /.well-known/*.

​
Créer une distribution CloudFront

  1. Accédez à CloudFront dans la console AWS.
  2. Sélectionnez Create distribution.
Page des distributions CloudFront avec le bouton « Create distribution » mis en évidence.
  1. Pour le domaine d’origine, saisissez [SUBDOMAIN].mintlify.dev, où [SUBDOMAIN] correspond au sous-domaine unique de votre projet.
Page « Create distribution » de CloudFront affichant « acme.mintlify.dev » comme domaine d’origine.
  1. Pour « Web Application Firewall (WAF) », activez les protections de sécurité.
Options du Web Application Firewall (WAF) avec « Enable security protections » sélectionné.
  1. Laissez les autres paramètres par défaut.
  2. Sélectionnez Create distribution.

​
Ajouter une origine par défaut

  1. Après avoir créé la distribution, accédez à l’onglet « Origins ».
Une distribution CloudFront avec l’onglet « Origins » mis en évidence.
  1. Recherchez l’URL de préproduction qui reflète votre domaine principal. Cela varie fortement selon l’hébergeur de votre page d’accueil. Par exemple, l’URL de préproduction de Mintlify est mintlify-landing-page.vercel.app.
Si votre page d’accueil est hébergée sur Webflow, utilisez l’URL de préproduction de Webflow. Elle ressemble à .webflow.io.Si vous utilisez Vercel, utilisez le domaine .vercel.app disponible pour chaque projet.
  1. Créez une nouvelle origine et ajoutez votre URL de préproduction dans le champ « Origin domain ».
Page CloudFront « Create origin » avec le champ de saisie « Origin domain » mis en évidence.
À ce stade, vous devriez avoir deux origines : une avec [SUBDOMAIN].mintlify.app et une autre avec votre URL de préproduction.
Page CloudFront « Origins » avec deux origines : une pour mintlify et une autre pour mintlify-landing-page.

​
Configurer les comportements

Les comportements dans CloudFront permettent de contrôler la logique des sous-chemins. Globalement, 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 une autre page, rediriger vers la page d’accueil actuelle.
  1. Accédez à l’onglet « Behaviors » de votre distribution CloudFront.
Onglet « Behaviors » de CloudFront mis en évidence.
  1. Cliquez sur 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.
Page CloudFront « Create behavior » avec un « Path pattern » de « /.well-known/* » et « Origin and origin groups » pointant vers l’URL de staging.
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 Path pattern correspondant au sous-chemin de votre choix, par exemple /docs, avec Origin and origin groups 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.
Page CloudFront "Create behavior" avec un "Path pattern" de "/docs/*" et "Origin and origin groups" pointant vers l’URL acme.mintlify.dev.

​
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 .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 (*).
Une distribution CloudFront avec le comportement « Default (*) » sélectionné et le bouton Edit mis en évidence.
  1. Dans le comportement par défaut, remplacez Origin and origin groups par l’URL de préproduction (dans notre cas mintlify-landing-page.vercel.app).
Page CloudFront « Edit behavior » avec le champ de saisie « Origin and origin groups » mis en évidence.
  1. Sélectionnez Save changes.

​
Vérifiez que les comportements sont correctement configurés

Si vous suivez les étapes ci-dessus, vos comportements devraient ressembler à ceci :
Page CloudFront « Behaviors » avec 4 comportements : /docs/*, /docs, Default et /.well-known/*.

​
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 Distribution domain name.
Onglet CloudFront « General » avec l’URL « Distribution domain name » mise en évidence.
Toutes les pages devraient pointer vers votre page d’accueil principale. En revanche, si vous ajoutez le sous-chemin que vous avez choisi, par exemple /docs, à l’URL, vous devriez être redirigé vers votre instance de documentation Mintlify.

​
Connecter 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.
Page « Records » de Route 53 avec le bouton « Create record » mis en évidence.
  1. Activez Alias, puis, dans Route traffic to, choisissez l’option Alias to CloudFront distribution.
Page « Create record » de Route 53 avec l’interrupteur « Alias » et le menu « Route traffic to » mis en évidence.
  1. Sélectionnez Create records.
Vous devrez peut-être supprimer l’enregistrement A existant s’il y en a un.
Votre documentation est maintenant en ligne au sous-chemin choisi pour votre domaine principal.
Après avoir configuré votre DNS, les sous-domaines personnalisés sont généralement disponibles en quelques minutes. La propagation du 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.