(Migratie v3.5.13) Migratie naar volledige projectgeschiedenis

​

Migratie naar volledige projectgeschiedenis

De release 3.5.x van de Community Edition bevat de functie Full Project History die al beschikbaar is in ons SaaS-aanbod, overleaf.com

Na het upgraden van je instantie naar Overleaf CE 3.5.13 gebruiken alle nieuwe projecten standaard Full Project History. Bestaande projecten blijven het verouderde geschiedenissysteem gebruiken totdat ze zijn gemigreerd.

Als je upgradet naar 3.5.13 en besluit terug te gaan naar een eerdere versie, moet je herstellen vanaf een volledige systeemback-up. De geschiedenis van projecten die in 3.5.13 zijn aangemaakt, is niet compatibel met eerdere versies van Overleaf CE.

De nieuwe Full Project History biedt gebruikers verschillende verbeteringen:

• Het houdt wijzigingen in binaire bestanden bij, wat in het verouderde systeem niet wordt ondersteund.
• Er is ondersteuning voor gelabelde versies.
• Het systeem is over het algemeen robuuster; er is minder kans op gegevensverlies.

Raadpleeg de documentatie van Full Project History voor meer informatie over de volledige projectgeschiedenis.

​

Bestaande projecten migreren

1. Maak een back-up

   Maak een volledige back-up van je instantie met een consistente momentopname van de mappen mongo, redis en sharelatex.

2. Bijwerken

   Werk de versie van de image sharelatex/sharelatex bij naar 3.5.13.

   Toolkit: gebruik het script $ bin/upgrade om de toolkit naar de nieuwste versie te upgraden en stel config/version in op 3.5.13.

3. Start de instantie

   Idealiter voorkom je dat gebruikers toegang hebben tot je instantie terwijl de migratie plaatsvindt, om gegevensverlies te voorkomen als je je back-up moet terugzetten. Zie Offline migratie voor meer informatie over hoe je dit doet.

4. Wacht tot alle services actief zijn

   Wacht tot alle services actief zijn (zie de onderstaande opdracht)

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. Voer het migratiescript uit

   # 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 wist gedeeltelijk gemigreerde projectgeschiedenisgegevens in het nieuwe systeem; hiermee kun je de migratie opnieuw proberen voor afzonderlijke projecten die bij eerdere pogingen zijn mislukt;

   --fix-invalid-characters vervangt niet-afdrukbare tekens die niet door het nieuwe geschiedenissysteem worden ondersteund;

   --convert-large-docs-to-file zet documenten die boven de drempel van 2 MB voor bewerkbare grootte liggen om naar een niet-bewerkbaar bestand)

   De uitvoer zou er zo uit moeten zien:

   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.
   

   Als de migratie is geslaagd, krijg je exitcode 0 en geven de laatste regels aan dat er geen fouten zijn opgetreden:

   Projects failed:  0
   Done.
   

   Je kunt de toegang voor je gebruikers weer openstellen (zie de volgende stap). Als er fouten zijn, raadpleeg dan de sectie Probleemoplossing hieronder. Je kunt de site nog steeds heropenen als de problemen niet direct zijn opgelost; de niet-gemigreerde projecten blijven dan op het verouderde geschiedenissysteem.

6. Heropen de site

   Als je hebt gekozen voor een offline migratie, moet je de site heropenen. Als je nog bent ingelogd, moet je:

   1. Op de knop Admin klikken en Manage Site kiezen
   2. Op het tabblad Open/Close Editor klikken
   3. Op de knop Reopen Editor klikken

   Als je je browser hebt gesloten, moet je de site opnieuw starten met $ bin/up.

​

Offline migratie

Volg deze stappen om te voorkomen dat gebruikers kunnen inloggen terwijl het migratiescript voor de geschiedenis wordt uitgevoerd:

• Log in bij je Overleaf-instantie met een beheerdersaccount
• Klik op de knop Admin en kies Manage Site
• Klik op het tabblad Open/Close Editor
• Klik op de knop Close Editor
• Klik op de knop Disconnect all users

Zodra dit is gedaan, worden ingelogde gebruikers doorgestuurd naar de onderhoudspagina, en zien nieuwe gebruikers die de inlogpagina bezoeken de onderhoudspagina en kunnen ze niet inloggen.

​

Online migratie

Het is mogelijk om de migratiescripts uit te voeren terwijl de applicatie nog draait. Er zijn een paar aandachtspunten:

• Het migratieproces is CPU-intensief; je moet het resourcegebruik in de gaten houden terwijl het script draait.
• Met een hoge waarde voor --concurrency kan de event loop in sommige services (met name track-changes) enige blokkering ondervinden, wat tot een verslechterde gebruikerservaring kan leiden. We raden aan te beginnen met de standaardwaarde --concurrency=1.
• Je kunt het script op elk moment stoppen. Als je het opnieuw start, wordt de migratie hervat waar je was gebleven. Dit is handig als je de migratie liever tijdens rustigere uren uitvoert (bijv. ’s nachts).

We raden aan de site te sluiten en de migratie offline uit te voeren in een onderhoudsvenster wanneer je minder dan 1000 projecten hebt (db.projects.count()). Als het aantal projecten groot is, kun je het script uitvoeren en de voortgang volgen, en vervolgens op basis van je specifieke situatie beslissen of je het online of offline verder uitvoert.

​

Verouderde geschiedenisgegevens opschonen

Een script om verouderde geschiedenisgegevens op te schonen is toegevoegd in Server Pro 3.5.6, 4.0.6 en 4.1.0.

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

Het script kan worden uitgevoerd nadat alle projecten zijn gemigreerd. Het kan ook worden gebruikt om ruimte vrij te maken tijdens een online migratie.

In Server Pro vóór versie 3.5.13 verwijdert het script de inhoud van de collecties docHistory en docHistoryIndex. MongoDB geeft geen schijfruimte vrij nadat je documenten hebt verwijderd; in plaats daarvan wordt die ruimte hergebruikt voor toekomstige documenten in dezelfde collectie. Na de geschiedenismigratie wordt er niets meer naar deze collecties geschreven, dus de schijfruimte blijft ongebruikt.

Als je de schijfruimte weer beschikbaar wilt maken, kun je upgraden naar Server Pro 3.5.13 (als je nog de 3.x-release gebruikt) of Server Pro 4.2.5 (als je de 4.x-release gebruikt) en het opschoonscript opnieuw uitvoeren.

Het opschoonscript zoals opgenomen in de nieuwste patchreleases van 3.5.x en de nieuwste 4.x.x van Server Pro verwijdert de collecties als laatste stap.

Het is veilig om het opschoonscript opnieuw uit te voeren.

​

Probleemoplossing

We zullen hier advies voor probleemoplossing toevoegen. Houd er rekening mee dat we normaal gesproken alleen ondersteuning bieden aan Server Pro-klanten, maar gezien de aard van deze migratie zullen we ook ons best doen om CE-klanten te ondersteunen die problemen ondervinden die specifiek zijn voor de migratie naar de volledige projectgeschiedenis.

Als het migratiescript voor de volledige projectgeschiedenis mislukt (d.w.z. afsluit met een fout of een aantal mislukte projecten groter dan nul weergeeft), stuur dan de volgende gegevens per e-mail naar ons supportteam via [e-mail], met daarin:

Onderwerp: Full project history migration problem

• Type instantie: CE of Server Pro (doorhalen wat niet van toepassing is)
• Type installatie: Overleaf toolkit, docker-compose.yml of anders (doorhalen wat niet van toepassing is)
• Versie: 3.5.x (toolkit: $ cat config/version)
• Uitvoer van het migratiescript (die zich in de container onder /overleaf/services/web zou moeten bevinden)
• Migrated Projects: (volgens de uitvoer van het migratiescript)
• Total Projects: (volgens de uitvoer van het migratiescript)
• Remaining Projects: (volgens de uitvoer van het migratiescript)
• Duur van de migratie:
• Uitvoer van bin/doctor (bij gebruik van de toolkit)
• Toolkit-versie: $ git rev-parse HEAD (bij gebruik van de Toolkit)

Overweeg de logbestanden van de services history-v1, project-history en track-changes als bijlage aan de e-mail toe te voegen. Je vindt deze in /var/log/sharelatex in de sharelatex-container en kunt ze als volgt exporteren:

$ 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

Verwijder alle gevoelige informatie uit de logbestanden voordat je ze bijvoegt.

​

Beschadigde bestandsstructuren vinden

De migratie kan mislukken voor projecten met een misvormde bestandsstructuur (bijvoorbeeld waarin bestandsnamen leeg zijn). Je kunt een lijst van deze problemen opvragen met het script find_malformed_filetrees, dat alle projecten in de database controleert:

$ 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
...

Gebruik het script fix_malformed_filetree om de ongeldige paden te herstellen, waarbij je de opdracht voor elk ongeldig pad één keer uitvoert:

$ 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"
...

​

Projecten terugzetten van volledige projectgeschiedenis naar de verouderde geschiedenis

Als een project naar de volledige projectgeschiedenis is gemigreerd, maar je wilt terug naar de verouderde geschiedenis, gebruik dan het script downgrade_project als volgt:

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