.. _package/docu/configurazione_docu/docu_s3: 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``. .. hint:: 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". .. image:: /_static/images/docu/configurazione_docu/s3-accesso-pubblico.png :width: 200px :align: center Si rimanda alla guida precedentemente segnalata di AWS per una configurazione aggiornata della policy. .. Si noti che c'è un problema in come i manuali vengono uploadati sul bucket S3, che assegna come metadati sempre binary/octet-stream e non text/html, text/css ecc. Questo costringe ad effettuare una configurazione particolare con Cloudfront. Forse si potrebbe evitare, ma è da approfondire... 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 .. image:: /_static/images/docu/configurazione_docu/cloudfront-origin-path.png :width: 500px :align: center - 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 `_ .. image:: /_static/images/docu/configurazione_docu/function-lambda.png :width: 600px :align: center - 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: .. list-table:: Response headers policy :widths: 33 33 33 :align: center :header-rows: 1 * - 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: .. image:: /_static/images/docu/configurazione_docu/behaviours-policies.png :width: 100% :align: center - 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 :ref:`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. .. hint:: 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; .. sectionauthor:: Davide Paci