AWS Route 53 e CloudFront
Inoltra il traffico /docs tramite AWS CloudFront e Route 53 al tuo sito Jamdesk. Include configurazione della distribuzione, origine e regole di cache.
Configura una distribuzione CloudFront per inoltrare /docs/* al tuo sito Jamdesk, con Route 53 per il DNS. Richiede circa 15 minuti.
Prerequisiti
- Un account AWS con accesso a CloudFront e Route 53
- Il tuo dominio gestito in Route 53 (o la possibilità di aggiornare il DNS altrove)
- Il tuo sottodominio Jamdesk (si trova nelle impostazioni della dashboard)
- Il tuo dominio personalizzato registrato e verificato via DNS nella dashboard Jamdesk
Se utilizzi un sottopercorso personalizzato invece del predefinito /docs, sostituisci /docs/* nel pattern del percorso del comportamento della cache (Passaggio 3) con il tuo sottopercorso. Aggiorna di nuovo la distribuzione dopo qualsiasi rinomina nella dashboard.
Passaggio 1: crea una distribuzione CloudFront
- Apri la console CloudFront
- Fai clic su Create Distribution
- Configura l'origine:
| Impostazione | Valore |
|---|---|
| Dominio di origine | YOUR_SLUG.jamdesk.app |
| Protocollo | Solo HTTPS |
| Nome | jamdesk-docs-origin |
Sostituisci YOUR_SLUG con il tuo sottodominio Jamdesk.
Passaggio 2: configura le impostazioni dell'origine
Aggiungi intestazioni personalizzate nelle impostazioni di origine per identificare il tuo dominio:
| Nome intestazione | Valore |
|---|---|
X-Forwarded-Host | yoursite.com |
X-Jamdesk-Forwarded-Host | yoursite.com |
Queste intestazioni indicano a Jamdesk quale dominio sta effettuando la richiesta.
Questo passaggio è obbligatorio. Saltarlo causa un errore silenzioso. La policy AllViewerExceptHostHeader (passaggio successivo) inoltra solo le intestazioni inviate dal browser del visitatore. Non ne aggiunge di nuove. X-Jamdesk-Forwarded-Host raggiunge Jamdesk solo come intestazione personalizzata dell'origine. Senza di essa, le richieste hanno comunque successo, ma le pagine vengono servite con noindex e con link canonici che puntano a YOUR_SLUG.jamdesk.app invece che al tuo dominio.
Le intestazioni statiche dell'origine non possono variare per richiesta. Per servire più nomi di dominio alternativi da un'unica distribuzione, usa invece una CloudFront Function su viewer request. Falla impostare request.headers['x-jamdesk-forwarded-host'] = { value: request.headers.host.value }.
Passaggio 3: crea i comportamenti della cache
Aggiungi comportamenti per instradare /docs/* e le richieste di asset verso la tua origine Jamdesk:
- Vai alla scheda Behaviors
- Fai clic su Create Behavior
- Crea tre comportamenti con queste impostazioni:
| Pattern del percorso | Origine | Policy della cache | Policy della richiesta di origine |
|---|---|---|---|
/docs/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
/_next/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
/_jd/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
Imposta Viewer protocol policy su Redirect HTTP to HTTPS per tutti e tre.
Ogni comportamento è obbligatorio. /_next/* e /_jd/* servono JavaScript, CSS, font e immagini che le pagine della documentazione caricano. La policy AllViewerExceptHostHeader inoltra le intestazioni della richiesta del visitatore (tutte tranne Host, che CloudFront riserva per l'origine). Impostala su tutti e tre.
Passaggio 4: aggiungi il nome di dominio alternativo
- Nella scheda General, fai clic su Edit
- In Alternate domain name (CNAME), aggiungi
yoursite.com - Seleziona o richiedi un certificato SSL per il tuo dominio
Passaggio 5: configura Route 53
Crea un record alias che punti alla tua distribuzione CloudFront:
- Apri la console Route 53
- Seleziona la tua hosted zone
- Fai clic su Create Record
- Configura:
| Impostazione | Valore |
|---|---|
| Record name | yoursite.com (o lascia vuoto per l'apex) |
| Record type | A |
| Alias | Yes |
| Route traffic to | CloudFront distribution |
| Distribution | Seleziona la tua distribuzione |
Passaggio 6: verifica
Attendi la propagazione DNS (di solito 5-15 minuti). Poi visita https://yoursite.com/docs e verifica che la documentazione si carichi.
Riepilogo della configurazione CloudFront completa
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)Risoluzione dei problemi
Verifica che il dominio di origine sia esattamente YOUR_SLUG.jamdesk.app, senza il prefisso https://.
Verifica che la Viewer protocol policy sia impostata su "Redirect HTTP to HTTPS" e che il tuo certificato SSL sia valido.
Crea un'invalidazione CloudFront per /docs/* per svuotare i contenuti in cache dopo la pubblicazione delle modifiche.
Se vedi "Domain is not authorized to serve this content":
- Verifica che il tuo dominio sia registrato nella dashboard Jamdesk
- Completa la verifica DNS (record TXT) per il tuo dominio
- Imposta le intestazioni personalizzate
X-Forwarded-HosteX-Jamdesk-Forwarded-Hostnella configurazione dell'origine - Controlla che il tuo dominio sia associato al progetto corretto
Il dominio deve essere verificato prima che CloudFront possa servire la documentazione.
Il controllo preliminare recupera /_jd/preflight sul tuo dominio attivo e verifica cosa è arrivato a Jamdesk. Se segnala che il tuo proxy "non si identifica", CloudFront sta raggiungendo Jamdesk senza X-Jamdesk-Forwarded-Host. Ricontrolla l'intestazione personalizzata dell'origine al Passaggio 2. Vedi Custom domain only per il significato di ogni messaggio del controllo preliminare.