L’attività di documentazione può essere piuttosto “energivora” in termini di spazio disco, soprattutto se si offrono manuali copiosi in termini di immagini, video, e materiale multimediale.

Proprio per questo abbiamo deciso di sfruttare i bucket di AWS, già in buona parte integrati in Genropy, per ospitare anche tutti i manuali e i relativi file. Questo aggiornamento, rilasciato il 31/08/2022 sul branch develop e nell’imminente futuro anche sul branch master, richiederà all’utente che faceva uso del documentatore sulle proprie istanze di effettuare qualche breve procedura di aggiornamento per continuare a pubblicare correttamente la documentazione precedente, sia che si desideri usufruire della nuova opportunità offerta dai bucket di AWS, sia che si desideri continuare con la configurazione pre-esistente.

Vediamo quindi innanzitutto che cosa è cambiato se desideriamo pubblicare i nostri manuali nella cartella site.

Upgrade di una documentazione esistente senza passare ad S3

Innanzitutto sarà necessario spostare i file allegati sul server in produzione dalla cartella docu_documentation alla cartella documentation/attachments.

Non sarà necessario ricopiare i manuali per intero, in quanto sarà sufficiente rigenerarli. Sarà però necessario eseguire una gnrdbsetup dell’istanza con l’attributo -U per eseguire un’apposita procedura di upgrade che si occuperà delle dovute sostituzioni a livello di database.

Infine, dovremo aggiornare la configurazione di Nginx. Se prima era indicato:

location ~ ^/docs/(?[^/]+)(?(/.*)?)$ {
alias /home/ubuntu/gitrepos/genropy_projects/nomeprogetto/instances/nomeistanza/site/handbooks/$prefix/sphinx/build;
try_files $oth $oth/ /index.html;
}

ora dovremo sostituire l’ultima parte /handbooks/$prefix/sphinx/build con /documentation/handbooks/$prefix/, in quanto i file html finali verranno pubblicati direttamente nella cartella del manuale (corrispondente a $prefix).

Si noti che il path è ancora personalizzabile a piacere nelle preferenze.

Migrare dalla configurazione legacy ad S3

Qualora invece si desiderasse migrare la documentazione su un bucket S3, ecco i passaggi da seguire.

Innanzitutto è necessario creare un apposito bucket in AWS S3 e una distribuzione Cloudfront che si occuperanno rispettivamente dell’hosting di allegati, immagini di anteprima e manuali pubblicati il primo, e della distribuzione degli stessi il secondo. Si rimanda pertanto alla sezione di documentazione dedicata per la Configurazione di S3 e Cloudfront.

Secondariamente sarà necessario copiare i file allegati dal server in produzione al bucket S3. In particolare:

• copiare il contenuto di /site/docu_documentation in attachments
• copiare il contenuto di handbooks_images in handbook_images

Anche in questo caso non sarà necessario ricopiare i manuali per intero, in quanto sarà sufficiente rigenerarli, bensì sarà necessario eseguire una gnrdbsetup dell’istanza con l’attributo -U per eseguire un’apposita procedura di upgrade che si occuperà delle dovute sostituzioni a livello di database.

L’uso di questi strumenti ci permetterà o di utilizzare un sottodominio per la distribuzione della documentazione (es: https://docs.genropy.org, scenario consigliato) oppure, come in precedenza, di usare una directory del dominio (es: https://genropy.org/docs/).

Nel primo caso ci limiteremo a impostare i DNS per puntare verso la distribuzione di Cloudfront. Nel secondo caso, invece, la configurazione di Nginx sarà semplicemente:

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

Hai problemi nell’aggiornamento o semplicemente delle curiosità sull’hosting di documentazione con S3? Chiedi pure alla community sul gruppo Telegram AskGenropy!