AWS Route 53 et CloudFront
Acheminez le trafic /docs via AWS CloudFront et Route 53 vers votre site Jamdesk : distribution, origine et règles de cache.
Configurez une distribution CloudFront pour transférer /docs/* vers votre site Jamdesk, avec Route 53 pour le DNS. Compte environ 15 minutes.
Prérequis
- Un compte AWS avec accès à CloudFront et Route 53
- Votre domaine géré dans Route 53 (ou la possibilité de mettre à jour le DNS ailleurs)
- Votre sous-domaine Jamdesk (disponible dans les paramètres du dashboard)
- Votre domaine personnalisé enregistré et vérifié par DNS dans le dashboard Jamdesk
Si vous utilisez un sous-chemin personnalisé au lieu du /docs par défaut, remplacez /docs/* dans le modèle de chemin du comportement de cache (étape 3) par votre sous-chemin. Mettez à jour la distribution à nouveau après tout renommage dans le dashboard.
Étape 1 : Créer une distribution CloudFront
- Ouvrez la console CloudFront
- Cliquez sur Create Distribution
- Configurez l'origine :
| Paramètre | Valeur |
|---|---|
| Domaine d'origine | YOUR_SLUG.jamdesk.app |
| Protocole | HTTPS uniquement |
| Nom | jamdesk-docs-origin |
Remplacez YOUR_SLUG par votre sous-domaine Jamdesk réel.
Étape 2 : Configurer les paramètres d'origine
Dans les paramètres d'origine, ajoutez des en-têtes personnalisés pour identifier votre domaine :
| Nom de l'en-tête | Valeur |
|---|---|
X-Forwarded-Host | yoursite.com |
X-Jamdesk-Forwarded-Host | yoursite.com |
Ces en-têtes indiquent à Jamdesk quel domaine effectue la requête.
Cette étape est obligatoire, et l'ignorer échoue silencieusement. La politique AllViewerExceptHostHeader (étape suivante) ne transmet que les en-têtes envoyés par le navigateur de votre visiteur — elle n'en ajoute pas de nouveaux — donc X-Jamdesk-Forwarded-Host n'atteint Jamdesk qu'en tant qu'en-tête personnalisé d'origine. Sans cela, les requêtes réussissent toujours, mais les pages servent noindex avec des liens canoniques pointant vers YOUR_SLUG.jamdesk.app au lieu de votre domaine.
Si vous diffusez plusieurs noms de domaine alternatifs depuis une seule distribution, les en-têtes d'origine statiques ne peuvent pas varier par requête — utilisez une CloudFront Function sur viewer request à la place, en définissant request.headers['x-jamdesk-forwarded-host'] = { value: request.headers.host.value }.
Étape 3 : Créer des comportements de cache
Ajoutez des comportements pour acheminer /docs/* et les requêtes d'assets vers votre origine Jamdesk :
- Accédez à l'onglet Behaviors
- Cliquez sur Create Behavior
- Créez trois comportements avec ces paramètres :
| Modèle de chemin | Origine | Politique de cache | Politique de requête d'origine |
|---|---|---|---|
/docs/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
/_next/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
/_jd/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
Définissez Viewer protocol policy sur Redirect HTTP to HTTPS pour les trois.
Les trois comportements sont obligatoires : /_next/* et /_jd/* servent le JavaScript, le CSS, les polices et les images que chargent vos pages de documentation. La politique AllViewerExceptHostHeader transmet les en-têtes de requête du visiteur (tout sauf Host, que CloudFront réserve à l'origine) et doit être définie sur les trois.
Étape 4 : Ajouter un nom de domaine alternatif
- Dans l'onglet General, cliquez sur Edit
- Sous Alternate domain name (CNAME), ajoutez
yoursite.com - Sélectionnez ou demandez un certificat SSL pour votre domaine
Étape 5 : Configurer Route 53
Créez un enregistrement alias pointant vers votre distribution CloudFront :
- Ouvrez la console Route 53
- Sélectionnez votre zone hébergée
- Cliquez sur Create Record
- Configurez :
| Paramètre | Valeur |
|---|---|
| Nom de l'enregistrement | yoursite.com (ou laisser vide pour l'apex) |
| Type d'enregistrement | A |
| Alias | Oui |
| Acheminer le trafic vers | Distribution CloudFront |
| Distribution | Sélectionnez votre distribution |
Étape 6 : Vérifier
Après la propagation DNS (généralement 5 à 15 minutes), visitez https://yoursite.com/docs pour confirmer que votre documentation se charge correctement.
Résumé complet de la configuration CloudFront
Distribution Settings:
├── Origin: YOUR_SLUG.jamdesk.app
│ ├── Custom Header: X-Forwarded-Host = yoursite.com
│ └── Custom Header: X-Jamdesk-Forwarded-Host = yoursite.com
├── Behavior: /docs/*
│ ├── Cache Policy: CachingOptimized
│ └── Origin Request Policy: AllViewerExceptHostHeader
├── Behavior: /_next/*
│ ├── Cache Policy: CachingOptimized
│ └── Origin Request Policy: AllViewerExceptHostHeader
├── Behavior: /_jd/*
│ ├── Cache Policy: CachingOptimized
│ └── Origin Request Policy: AllViewerExceptHostHeader
└── Alternate Domain: yoursite.com (with SSL certificate)Dépannage
Assurez-vous que le domaine d'origine est exactement YOUR_SLUG.jamdesk.app, sans le préfixe https://.
Vérifiez que le paramètre Viewer protocol policy est défini sur "Redirect HTTP to HTTPS" et que votre certificat SSL est valide.
Créez une invalidation CloudFront pour /docs/* afin de vider le contenu mis en cache après la publication de modifications.
Si vous voyez "Domain is not authorized to serve this content" :
- Vérifiez que votre domaine est enregistré dans le dashboard Jamdesk
- Effectuez la vérification DNS (enregistrement TXT) pour votre domaine
- Assurez-vous que les en-têtes personnalisés
X-Forwarded-HostetX-Jamdesk-Forwarded-Hostsont définis dans la configuration de votre origine - Vérifiez que votre domaine correspond au bon projet
Le domaine doit être vérifié avant que CloudFront puisse diffuser la documentation.
La vérification préliminaire récupère /_jd/preflight sur votre domaine actif et vérifie ce qui est réellement parvenu à Jamdesk. Si elle indique que votre proxy « doesn't identify itself », CloudFront atteint bien Jamdesk mais sans X-Jamdesk-Forwarded-Host — revérifiez l'en-tête personnalisé d'origine à l'étape 2. Consultez Domaine personnalisé uniquement pour savoir ce que signifie chaque message de la vérification préliminaire.