S3 e Cloudfront

È possibile configurare un servizio di storage S3 per effettuare lo stoccaggio dei file multimediali della documentazione nonché i file zip dei manuali locali, oltre all’hosting di tutta la documentazione in formato html.

Seppur si rimanda alla documentazione ufficiale di AWS per gli aspetti più tecnici legati alla configurazione dei servizi, si riporta in questa sede una serie di best practices e accorgimenti necessari per la corretta integrazione dei servizi in Genropy.

Come prima cosa andrà creato un bucket S3, andrà innanzitutto creato un bucket S3 come indicato nel manuale, conferendogli accesso pubblico e abilitando l’hosting dei siti web statici come indicato in questa guida ufficiale di AWS. Secondariamente creeremo un service che chiameremo obbligatoriamente documentation.

Suggerimento

Si noti che oltre a configurare un accesso pubblico al bucket sarà necessario assegnargli una policy per l’accesso pubblico. Solo allora verrà riportata sotto il nome del bucket la dicitura in rosso «Accessibile pubblicamente».

Si rimanda alla guida precedentemente segnalata di AWS per una configurazione aggiornata della policy.

A questo punto andremo a gestire la distribuzione del bucket così creato con AWS Cloudfront, il sistema di caching di AWS. Si noti che questo non è un passaggio obbligato ma è vivamente consigliato per ottimizzare le prestazioni e la gestione delle configurazioni della manualistica pubblicata online (i manuali locali, invece, essendo semplici file .zip, verranno distribuiti direttamente dal bucket senza necessità di ulteriori passaggi).

Configurazione di AWS Cloudfront

Per distribuire il bucket della documentazione sinora creato con Cloudfront, sarà necessario innanzitutto creare una distribuzione Cloudfront seguendo questa Guida ufficiale di AWS.

Nella creazione della distribuzione si raccomanda quanto segue:

• specificare nel campo Origin path la cartella /handbooks, o la cartella definita nel path per la pubblicazione dei manuali di Sphinx

• al fine di reindirizzare sul file index.html tutte le chiamate provenienti alle root, sarà necessario anche definire una funzione Lambda, e assegnarla alla distribuzione che abbiamo creato. Troveremo dettagli su come creare questa funzione a questo link su Github

• al fine di gestire correttamente gli header delle chiamate (assegnando il corretto Content-Type), andremo anche a specificare una serie behaviours a cui assegneremo delle policies. Per ogni policy specificheremo il tipo di file, e l’header da aggiungere:

Response headers policy

File	Header name	Header value
*.js	Content-Type	text/javascript
*.css	Content-Type	text/css+
*.png	Content-Type	image/png
*.gif	Content-Type	image/gif
*.jpg	Content-Type	image/jpeg
*.jpeg	Content-Type	image/jpeg
Default(*)	Content-Type	text/html

Il risultato di questo passaggio saranno i behaviour seguenti:

• a questo punto dovremo sempre istruire Nginx, modificando però il file .conf come segue:

  location /docs/ {
      proxy_pass https://your-distribution-domain-name.cloudfront.net/;
      }
  

dove sostituiremo docs con la baseurl indicata nelle Preferenze e your-distribution-domain-name con l’indirizzo della distribuzione proposto da Cloudfront. L’istruzione inserità basterà a indirizzare le richieste a Cloudfront, che poi grazie alle regole che abbiamo inserito si occuperà del resto.

Suggerimento

Alternativamente all’uso di una directory interna al dominio è possibile usare un sottodominio o un altro dominio dedicato (es. https://docs.genropy.org/). In quel caso sarà sufficiente indicare il sottodominio come baseurl nelle preferenze, impostare l’indirizzamento del dominio a Cloudfront (con Aws Route53 o altro servizio di gestione DNS), risparmiandoci l’onere di modificare la configurazione di Nginx.

Ulteriori accorgimenti

La procedura di esportazione di un manuale su bucket S3 sarà ovviamente più lenta dell’analoga procedura direttamente sul server. Di conseguenza, potrebbero verificarsi dei rallentamenti che manderanno in timeout la procedura. Per ovviare a questo inconveniente è possibile fornire queste istruzioni a Nginx, direttamente nel file nginx.conf:

proxy_connect_timeout       6000;
proxy_send_timeout          6000;
proxy_read_timeout          6000;
send_timeout                6000;

Autore della sezione: Davide Paci