(Migrazione v3.5.13) Migrazione della cronologia completa dei progetti

​

Migrazione della cronologia completa dei progetti

La release 3.5.x della Community Edition include la funzionalità Full Project History, già disponibile nella nostra offerta SaaS, overleaf.com

Dopo aver aggiornato la tua istanza a Overleaf CE 3.5.13, tutti i nuovi progetti utilizzeranno la Full Project History per impostazione predefinita. I progetti esistenti continueranno a utilizzare il sistema di cronologia legacy finché non verranno migrati.

Se effettui l’aggiornamento alla 3.5.13 e decidi di tornare a una versione precedente, dovrai eseguire il ripristino da un backup completo del sistema. La cronologia dei progetti creati nella 3.5.13 non è compatibile con le versioni precedenti di Overleaf CE.

La nuova Full Project History porta diversi miglioramenti per gli utenti:

• Traccia le modifiche nei file binari, cosa non supportata dal sistema legacy.
• Supporta le versioni etichettate.
• Il sistema è in generale più robusto e il rischio di perdita di dati è minore.

Consulta la documentazione della Full Project History per ulteriori informazioni sulla cronologia completa dei progetti.

​

Migrare i progetti esistenti

1. Creare un backup

   Crea un backup completo della tua istanza con uno snapshot coerente delle directory mongo, redis e sharelatex.

2. Aggiornare

   Aggiorna la versione dell’immagine sharelatex/sharelatex alla 3.5.13.

   Toolkit: usa lo script $ bin/upgrade per aggiornare il toolkit all’ultima versione e modifica config/version impostandolo su 3.5.13.

3. Avviare l'istanza

   Idealmente, dovresti impedire agli utenti di accedere alla tua istanza durante la migrazione, per evitare perdite di dati nel caso in cui tu debba ripristinare il backup. Consulta Migrazione offline per ulteriori informazioni su come farlo.

4. Attendere che tutti i servizi siano attivi e funzionanti

   Attendi che tutti i servizi siano attivi e funzionanti (vedi il comando seguente)

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. Eseguire lo script di migrazione

   # Overleaf Toolkit users:
   $ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
   
   # legacy docker-compose.yml users:
   $ docker exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
   

   --force-clean elimina i dati della cronologia dei progetti parzialmente migrati nel nuovo sistema; ciò consente di ritentare la migrazione dei singoli progetti non riuscita nei tentativi precedenti;

   --fix-invalid-characters sostituisce i caratteri non stampabili non supportati dal nuovo sistema di cronologia;

   --convert-large-docs-to-file converte i documenti che superano la soglia di dimensione modificabile di 2MB in file non modificabili)

   L’output dovrebbe essere simile a questo:

   Migrated Projects  :  1
   Total Projects     :  51
   Remaining Projects :  51
   Total history records to migrate: 98
   Starting migration...
   Migrating project: 63d29b5772dd80015a81bffe
   migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
   Migrating project: 63d29c2e72dd80015a81c0a2
   migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
   
   // …
   
   Migration complete
   ==================
   Projects migrated:  51
   Projects failed:  0
   Done.
   

   Se la migrazione va a buon fine, otterrai un codice di uscita 0 e le ultime righe indicheranno che non ci sono stati errori:

   Projects failed:  0
   Done.
   

   Puoi riaprire l’accesso ai tuoi utenti (vedi il passaggio successivo). In caso di errori, consulta la sezione sulla risoluzione dei problemi più avanti. Puoi comunque riaprire il sito anche se i problemi non vengono risolti immediatamente: i progetti non migrati resteranno sul sistema di cronologia legacy.

6. Riaprire il sito

   Se hai scelto di eseguire una migrazione offline, dovrai riaprire il sito. Se hai ancora effettuato l’accesso, dovrai:

   1. Fare clic sul pulsante Admin e scegliere Manage Site
   2. Fare clic sulla scheda Open/Close Editor
   3. Fare clic sul pulsante Reopen Editor

   Se hai chiuso il browser, dovrai riavviare il sito con $ bin/up.

​

Migrazione offline

Per impedire agli utenti di accedere mentre lo script di migrazione della cronologia è in esecuzione, segui questi passaggi:

• Accedi alla tua istanza Overleaf con un account amministratore
• Fai clic sul pulsante Admin e scegli Manage Site
• Fai clic sulla scheda Open/Close Editor
• Fai clic sul pulsante Close Editor
• Fai clic sul pulsante Disconnect all users

Fatto ciò, gli utenti eventualmente connessi verranno reindirizzati alla pagina di manutenzione, e i nuovi utenti che visitano la pagina di accesso vedranno la pagina di manutenzione e non potranno accedere.

​

Migrazione online

È possibile eseguire gli script di migrazione mentre l’applicazione è ancora in esecuzione. Ci sono alcune considerazioni da tenere presenti:

• Il processo di migrazione è intensivo per la CPU: dovresti monitorare l’utilizzo delle risorse mentre lo script è in esecuzione.
• Con un valore di --concurrency elevato, l’event loop di alcuni servizi (in particolare track-changes) potrebbe subire dei blocchi, con un conseguente peggioramento dell’esperienza utente. Consigliamo di iniziare con il valore predefinito --concurrency=1.
• Puoi interrompere lo script in qualsiasi momento. Riavviandolo, la migrazione riprenderà dal punto in cui l’avevi lasciata. Ciò è utile se preferisci eseguire la migrazione nelle ore meno trafficate (ad es. di notte).

Ti consigliamo di chiudere il sito ed eseguire la migrazione offline in una finestra di manutenzione quando il numero di progetti è inferiore a 1000 (db.projects.count()). Se il numero di progetti è elevato, puoi eseguire lo script e monitorarne l’avanzamento, quindi decidere se continuare l’esecuzione online o offline in base al tuo caso specifico.

​

Ripulire i dati della cronologia legacy

Uno script per ripulire i dati della cronologia legacy è stato aggiunto in Server Pro 3.5.6, 4.0.6 e 4.1.0.

bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/history/clean_sl_history_data.js"

Lo script può essere eseguito dopo che tutti i progetti sono stati migrati. Può anche essere utilizzato per liberare spazio durante una migrazione online.

In Server Pro prima della versione 3.5.13, lo script elimina il contenuto delle collezioni docHistory e docHistoryIndex. MongoDB non rilascia lo spazio su disco dopo l’eliminazione dei documenti, ma lo riutilizza per i futuri documenti della stessa collezione. Dopo la migrazione della cronologia nulla scriverà più in queste collezioni, quindi lo spazio su disco resterà inutilizzato.

Se vuoi rendere nuovamente disponibile lo spazio su disco, puoi aggiornare a Server Pro 3.5.13 (se usi ancora la release 3.x) o a Server Pro 4.2.5 (se usi la release 4.x) ed eseguire di nuovo lo script di pulizia.

Lo script di pulizia incluso nelle ultime patch release di Server Pro 3.5.x e nell’ultima 4.x.x elimina le collezioni come passaggio finale.

Puoi eseguire di nuovo lo script di pulizia in tutta sicurezza.

​

Risoluzione dei problemi

Aggiungeremo qui dei consigli per la risoluzione dei problemi. Tieni presente che, sebbene normalmente offriamo supporto solo ai clienti Server Pro, data la natura di questa migrazione faremo del nostro meglio per supportare anche i clienti CE che riscontrano problemi specifici della migrazione della cronologia completa dei progetti.

Se lo script di migrazione della cronologia completa dei progetti non va a buon fine (ovvero termina con un errore o riporta un numero di progetti non riusciti diverso da zero), invia i seguenti dettagli al nostro team di supporto via email a [e-mail], specificando:

Oggetto: Full project history migration problem

• Tipo di istanza: CE o Server Pro (elimina la voce non pertinente)
• Tipo di installazione: Overleaf toolkit, docker-compose.yml o altro (elimina le voci non pertinenti)
• Versione: 3.5.x (toolkit: $ cat config/version)
• Output dello script di migrazione (che dovrebbe trovarsi nel container in /overleaf/services/web)
• Migrated Projects: (secondo l’output dello script di migrazione)
• Total Projects: (secondo l’output dello script di migrazione)
• Remaining Projects: (secondo l’output dello script di migrazione)
• Durata della migrazione:
• Output di bin/doctor (se usi il toolkit)
• Versione del Toolkit: $ git rev-parse HEAD (se usi il Toolkit)

Valuta la possibilità di allegare all’email i file di log dei servizi history-v1, project-history e track-changes. Li trovi in /var/log/sharelatex all’interno del container sharelatex e puoi esportarli in questo modo:

$ docker cp sharelatex:/var/log/sharelatex/history-v1.log history-v1.log
$ docker cp sharelatex:/var/log/sharelatex/project-history.log project-history.log
$ docker cp sharelatex:/var/log/sharelatex/track-changes.log track-changes.log

Rimuovi eventuali informazioni sensibili dai file di log prima di allegarli.

​

Individuare alberi di file danneggiati

La migrazione potrebbe non riuscire per i progetti con un albero di file malformato (ad esempio, con nomi di file vuoti). Puoi trovare un elenco di questi problemi usando lo script find_malformed_filetrees, che controlla tutti i progetti nel database:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/find_malformed_filetrees.js"
BAD PATH: 123456789012345678901234 rootFolder.0.1.2.3
BAD PATH: 123456789012345678901234 rootFolder.0.4.5.6
...

Per correggere i percorsi non validi, usa lo script fix_malformed_filetree, eseguendo il comando una volta per ogni percorso errato:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.1.2.3"
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.4.5.6"
...

​

Riportare i progetti dalla cronologia completa alla cronologia legacy

Se un progetto è stato migrato alla cronologia completa ma vuoi tornare alla cronologia legacy, usa lo script downgrade_project come segue:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; PROJECT_ID=YOUR