AWS Route 53 e CloudFront
Instrada il traffico /docs tramite AWS CloudFront e Route 53 al tuo sito Jamdesk, con configurazione della distribuzione, origine e cache.
Configura una distribuzione CloudFront per inoltrare /docs/* al tuo sito Jamdesk, usando Route 53 per il DNS. Sono necessari 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 (disponibile nelle impostazioni del dashboard)
- Il tuo dominio personalizzato registrato e verificato tramite DNS nel dashboard Jamdesk
Se usi un sottopercorso personalizzato invece del valore predefinito /docs, sostituisci /docs/* nel modello del percorso del comportamento della cache (Passaggio 3) con il tuo sottopercorso. Aggiorna nuovamente la distribuzione dopo ogni ridenominazione nel dashboard.
Passaggio 1: crea una distribuzione CloudFront
- Apri la console CloudFront
- Fai clic su Create Distribution
- Configura l'origine:
| Impostazione | Valore |
|---|---|
| Dominio dell'origine | YOUR_SLUG.jamdesk.app |
| Protocollo | HTTPS only |
| Nome | jamdesk-docs-origin |
Sostituisci YOUR_SLUG con il tuo sottodominio Jamdesk effettivo.
Passaggio 2: configura le impostazioni dell'origine
Nelle impostazioni dell'origine, aggiungi intestazioni personalizzate 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 e, se viene omesso, l'errore non è immediatamente visibile. La policy AllViewerExceptHostHeader (passaggio successivo) inoltra solo le intestazioni inviate dal browser del visitatore; non ne aggiunge di nuove. Pertanto, X-Jamdesk-Forwarded-Host raggiunge Jamdesk solo come intestazione personalizzata dell'origine. Senza questa intestazione, le richieste continuano ad avere esito positivo, ma le pagine vengono servite con noindex e collegamenti canonical che puntano a YOUR_SLUG.jamdesk.app invece che al tuo dominio.
Se servi più nomi di dominio alternativi da un'unica distribuzione, le intestazioni statiche dell'origine non possono variare in base alla richiesta: usa invece una CloudFront Function su viewer request, impostando 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 delle risorse alla tua origine Jamdesk:
- Vai alla scheda Behaviors
- Fai clic su Create Behavior
- Crea tre comportamenti con queste impostazioni:
| Modello percorso | Origine | Policy della cache | Policy delle richieste all'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.
Tutti e tre i comportamenti sono obbligatori: /_next/* e /_jd/* forniscono il JavaScript, i CSS, i font e le immagini caricati dalle pagine della documentazione. La policy AllViewerExceptHostHeader inoltra le intestazioni della richiesta del visitatore (tutto tranne Host, che CloudFront riserva all'origine) e deve essere impostata 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 zona ospitata
- Fai clic su Create Record
- Configura:
| Impostazione | Valore |
|---|---|
| Nome del record | yoursite.com (oppure lascia vuoto per l'apex) |
| Tipo di record | A |
| Alias | Yes |
| Instrada il traffico a | CloudFront distribution |
| Distribuzione | Seleziona la tua distribuzione |
Passaggio 6: verifica
Dopo la propagazione DNS (solitamente 5-15 minuti), visita https://yoursite.com/docs per verificare che la documentazione venga caricata correttamente.
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
Assicurati che il dominio dell'origine sia esattamente YOUR_SLUG.jamdesk.app, senza il prefisso https://.
Verifica che la policy Viewer protocol sia impostata su "Redirect HTTP to HTTPS" e che il certificato SSL sia valido.
Crea un'invalidazione CloudFront per /docs/* per cancellare i contenuti memorizzati nella cache dopo la pubblicazione delle modifiche.
Se visualizzi "Domain is not authorized to serve this content":
- Verifica che il tuo dominio sia registrato nel dashboard Jamdesk
- Completa la verifica DNS (record TXT) per il tuo dominio
- Assicurati che entrambe le intestazioni personalizzate
X-Forwarded-HosteX-Jamdesk-Forwarded-Hostsiano impostate nella 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 dal tuo dominio attivo e verifica cosa ha effettivamente raggiunto Jamdesk. Se indica che il proxy "doesn't identify itself", CloudFront raggiunge Jamdesk ma senza X-Jamdesk-Forwarded-Host: ricontrolla l'intestazione personalizzata dell'origine nel Passaggio 2. Consulta Custom domain only per comprendere il significato di ogni messaggio del controllo preliminare.