Per ospitare la documentazione in un sottopercorso personalizzato come yoursite.com/docs usando AWS Route 53 e CloudFront, devi configurare il tuo provider DNS in modo che punti alla tua distribuzione CloudFront.

​
Struttura del repository

I file della documentazione devono essere organizzati nel repository in modo da rispecchiare la struttura del sottopercorso scelta. Ad esempio, se desideri che la documentazione sia su yoursite.com/docs, crea una directory docs/ contenente tutti i file della documentazione.

​
Panoramica generale

Instrada il traffico a questi percorsi con una Cache Policy CachingDisabled:
  • /.well-known/acme-challenge/* - Necessario per la verifica del certificato Let’s Encrypt
  • /.well-known/vercel/* - Necessario per la verifica del dominio
  • /docs/* - Necessario per il routing del sotto-percorso
  • /docs/ - Necessario per il routing del sotto-percorso
Instrada il traffico a questo percorso con una Cache Policy CachingEnabled:
  • /mintlify-assets/_next/static/*
  • Default (*) - La pagina di destinazione del tuo sito
Tutti i Behaviors devono avere una origin request policy impostata su AllViewerExceptHostHeader. Pagina "Behaviors" di CloudFront con 4 behaviors: /docs/*, /docs, Default e /.well-known/*.

​
Crea una distribuzione CloudFront

  1. Vai a CloudFront nella console AWS.
  2. Seleziona Create distribution.
Pagina "CloudFront Distributions" con il pulsante "Create distribution" evidenziato.
  1. Per l’Origin domain, inserisci [SUBDOMAIN].mintlify.dev, dove [SUBDOMAIN] è il sottodominio univoco del tuo progetto.
Pagina "Create distribution" di CloudFront che mostra "acme.mintlify.dev" come Origin domain.
  1. Per “Web Application Firewall (WAF)”, abilita le protezioni di sicurezza.
Opzioni del Web Application Firewall (WAF) con "Enable security protections" selezionato.
  1. Lascia le restanti impostazioni ai valori predefiniti.
  2. Seleziona Create distribution.

​
Aggiungi l’origine predefinita

  1. Dopo aver creato la distribuzione, vai alla scheda “Origins”.
Una distribuzione CloudFront con la scheda "Origins" evidenziata.
  1. Trova l’URL di staging che rispecchia il dominio principale. Questo varia molto in base a come è ospitata la tua landing page. Ad esempio, l’URL di staging di Mintlify è mintlify-landing-page.vercel.app.
Se la tua landing page è ospitata su Webflow, usa l’URL di staging di Webflow. Avrà la forma .webflow.io.Se usi Vercel, usa il dominio .vercel.app disponibile per ogni progetto.
  1. Crea una nuova origin e aggiungi il tuo URL di staging come “Origin domain”.
Pagina CloudFront "Create origin" con il campo di input "Origin domain" evidenziato.
A questo punto dovresti avere due origins: una con [SUBDOMAIN].mintlify.app e un’altra con il tuo URL di staging.
Pagina CloudFront "Origins" con due origins: una per mintlify e un’altra per mintlify-landing-page.

​
Configura i comportamenti

I comportamenti in CloudFront consentono di controllare la logica dei sottopercorsi. In sintesi, vogliamo implementare la seguente logica:
  • Se un utente accede al tuo sottopercorso personalizzato, reindirizza a [SUBDOMAIN].mintlify.dev.
  • Se un utente accede a qualsiasi altra pagina, reindirizza all’attuale landing page.
  1. Vai alla scheda “Behaviors” della tua distribuzione CloudFront.
Scheda "Behaviors" di CloudFront evidenziata.
  1. Seleziona il pulsante Create behavior e crea i seguenti comportamenti.

​
/.well-known/*

Crea i behavior per i percorsi di verifica del dominio Vercel con un Path pattern /.well-known/* e imposta Origin and origin groups all’URL della tua documentazione. Per “Cache policy”, seleziona CachingDisabled per assicurare che queste richieste di verifica passino senza essere memorizzate in cache.
Pagina CloudFront "Create behavior" con un "Path pattern" di "/.well-known/*" e "Origin and origin groups" che puntano all'URL di staging.
Se .well-known/* è troppo generico, può essere ristretto ad almeno 2 behavior per Vercel:
  • /.well-known/vercel/* - Necessario per la verifica del dominio Vercel
  • /.well-known/acme-challenge/* - Necessario per la verifica del certificato Let’s Encrypt

​
Il tuo sottopercorso personalizzato

Crea un comportamento con un modello di percorso del sottopercorso scelto, ad esempio /docs, con Origine e gruppi di origine che puntano all’URL .mintlify.dev (nel nostro caso acme.mintlify.dev).
  • Imposta “Cache policy” su CachingOptimized.
  • Imposta “Origin request policy” su AllViewerExceptHostHeader.
  • Imposta “Viewer Protocol Policy” su Redirect HTTP to HTTPS.
Pagina di CloudFront "Create behavior" con un "Path pattern" di "/docs/*" e "Origin and origin groups" che puntano all'URL acme.mintlify.dev.

​
Sottopercorso personalizzato con wildcard

Crea un comportamento con un Path pattern del sottopercorso scelto seguito da /*, ad esempio /docs/*, e con Origin and origin groups che puntano allo stesso URL .mintlify.dev. Queste impostazioni devono corrispondere esattamente a quelle del comportamento del sottopercorso di base, fatta eccezione per il Path pattern.
  • Imposta “Cache policy” su CachingOptimized.
  • Imposta “Origin request policy” su AllViewerExceptHostHeader.
  • Imposta “Viewer protocol policy” su Redirect HTTP to HTTPS

​
/mintlify-assets/_next/static/*

  • Imposta la “Cache policy” su CachingOptimized
  • Imposta la “Origin request policy” su AllViewerExceptHostHeader
  • Imposta la “Viewer protocol policy” su Redirect HTTP to HTTPS

​
Default (*)

Infine, modificheremo il comportamento Default (*).
Una distribuzione CloudFront con il comportamento "Default (*)" selezionato e il pulsante Edit evidenziato.
  1. Imposta Origin and origin groups del comportamento predefinito sull’URL di staging (nel nostro caso mintlify-landing-page.vercel.app).
Pagina CloudFront "Edit behavior" con il campo di input "Origin and origin groups" evidenziato.
  1. Seleziona Save changes.

​
Verifica che i comportamenti siano configurati correttamente

Se segui i passaggi sopra, i tuoi comportamenti dovrebbero essere così:
Pagina "Behaviors" di CloudFront con 4 comportamenti: /docs/*, /docs, Default e /.well-known/*.

​
Distribuzione di anteprima

Ora puoi verificare se la tua distribuzione è configurata correttamente andando alla scheda “General” e visitando l’URL Distribution domain name.
Scheda "General" di CloudFront con l'URL "Distribution domain name" evidenziato.
Tutte le pagine dovrebbero reindirizzare alla tua pagina principale, ma se aggiungi il sottopercorso che hai scelto, ad esempio /docs, all’URL, dovresti vedere che porta alla tua istanza della documentazione Mintlify.

​
Connessione con Route 53

Ora porteremo la funzionalità della distribuzione CloudFront nel tuo dominio principale.
Per questa sezione puoi anche fare riferimento alla guida ufficiale di AWS su Configurare Amazon Route 53 per instradare il traffico verso una distribuzione CloudFront
  1. Accedi a Route 53 dalla console AWS.
  2. Vai alla “Hosted zone” del tuo dominio principale.
  3. Seleziona Create record.
Pagina "Records" di Route 53 con il pulsante "Create record" evidenziato.
  1. Attiva Alias e quindi, in Route traffic to, seleziona l’opzione Alias to CloudFront distribution.
Pagina "Create record" di Route 53 con l'interruttore "Alias" e il menu "Route traffic to" evidenziati.
  1. Seleziona Create records.
Potresti dover rimuovere l’eventuale record A esistente.
La tua documentazione è ora attiva nel sottopercorso scelto del tuo dominio principale.
Dopo aver configurato il DNS, i sottodomini personalizzati sono solitamente disponibili entro pochi minuti. La propagazione del DNS può talvolta richiedere 1-4 ore e, in casi rari, fino a 48 ore. Se il tuo sottodominio non è subito disponibile, attendi prima di procedere con la diagnostica.