(Migration v3.5.13) Migration vers l'historique complet des projets

​

Migration vers l’historique complet des projets

La version 3.5.x de la Community Edition inclut la fonctionnalité d’historique complet des projets (Full Project History), déjà disponible dans notre offre SaaS, overleaf.com

Après la mise à niveau de votre instance vers Overleaf CE 3.5.13, tous les nouveaux projets utiliseront par défaut l’historique complet des projets. Les projets existants continueront d’utiliser l’ancien système d’historique jusqu’à leur migration.

Si vous passez à la version 3.5.13 puis décidez de revenir à une version antérieure, vous devez restaurer une sauvegarde complète du système. L’historique des projets créés en 3.5.13 n’est pas compatible avec les versions antérieures d’Overleaf CE.

Le nouvel historique complet des projets apporte plusieurs améliorations aux utilisateurs :

• Il suit les modifications des fichiers binaires, ce que l’ancien système ne prend pas en charge.
• Les versions étiquetées sont prises en charge.
• Le système est globalement plus robuste, avec moins de risques de perte de données.

Consultez la documentation sur l’historique complet des projets pour plus d’informations.

​

Migrer les projets existants

1. Créer une sauvegarde

   Créez une sauvegarde complète de votre instance avec un instantané cohérent des répertoires mongo, redis et sharelatex.

2. Mettre à jour

   Mettez à jour la version de l’image sharelatex/sharelatex vers 3.5.13.

   Toolkit : utilisez le script $ bin/upgrade pour mettre à niveau le toolkit vers la dernière version et modifiez config/version pour indiquer 3.5.13.

3. Démarrer l'instance

   Idéalement, empêchez les utilisateurs d’accéder à votre instance pendant la migration, afin d’éviter toute perte de données si vous deviez restaurer votre sauvegarde. Consultez Migration hors ligne pour savoir comment procéder.

4. Attendre que tous les services soient opérationnels

   Attendez que tous les services soient démarrés et opérationnels (voir la commande ci-dessous)

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. Exécuter le script de migration

   # 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 supprime les données d’historique partiellement migrées dans le nouveau système, ce qui permet de relancer la migration pour les projets individuels dont les tentatives précédentes ont échoué ;

   --fix-invalid-characters remplace les caractères non imprimables qui ne sont pas pris en charge par le nouveau système d’historique ;

   --convert-large-docs-to-file convertit les documents dépassant le seuil de taille modifiable de 2 Mo en fichiers non modifiables)

   La sortie devrait ressembler à ceci :

   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.
   

   Si la migration réussit, vous obtiendrez un code de sortie 0, et les dernières lignes indiqueront qu’il n’y a eu aucun échec :

   Projects failed:  0
   Done.
   

   Vous pouvez rouvrir l’accès à vos utilisateurs (voir l’étape suivante). En cas d’échecs, consultez la section de dépannage ci-dessous. Vous pouvez tout de même rouvrir le site si les problèmes ne sont pas immédiatement résolus ; les projets non migrés resteront sur l’ancien système d’historique.

6. Rouvrir le site

   Si vous avez choisi d’effectuer une migration hors ligne, vous devrez rouvrir le site. Si vous êtes toujours connecté, vous devrez :

   1. Cliquer sur le bouton Admin et choisir Manage Site
   2. Cliquer sur l’onglet Open/Close Editor
   3. Cliquer sur le bouton Reopen Editor

   Si vous avez fermé votre navigateur, vous devrez redémarrer le site avec $ bin/up.

​

Migration hors ligne

Pour empêcher les utilisateurs de se connecter pendant l’exécution du script de migration de l’historique, suivez ces étapes :

• Connectez-vous à votre instance Overleaf avec un compte administrateur
• Cliquez sur le bouton Admin et choisissez Manage Site
• Cliquez sur l’onglet Open/Close Editor
• Cliquez sur le bouton Close Editor
• Cliquez sur le bouton Disconnect all users

Une fois cela fait, les utilisateurs connectés seront redirigés vers la page de maintenance, et tout nouvel utilisateur visitant la page de connexion verra la page de maintenance et ne pourra pas se connecter.

​

Migration en ligne

Il est possible d’exécuter les scripts de migration pendant que l’application est toujours en cours d’exécution. Quelques points sont à prendre en compte :

• Le processus de migration sollicite fortement le CPU ; surveillez l’utilisation des ressources pendant l’exécution du script.
• Avec une valeur --concurrency élevée, la boucle d’événements de certains services (track-changes en particulier) peut subir des blocages, ce qui dégraderait l’expérience utilisateur. Nous recommandons de commencer avec la valeur par défaut --concurrency=1.
• Vous pouvez arrêter le script à tout moment. Le relancer reprendra la migration là où vous l’aviez laissée. C’est utile si vous préférez exécuter la migration pendant les heures creuses (par exemple la nuit).

Nous recommandons de fermer le site et d’exécuter la migration hors ligne pendant une fenêtre de maintenance lorsque votre nombre de projets est inférieur à 1000 (db.projects.count()). Si le nombre de projets est élevé, vous pouvez lancer le script et surveiller sa progression, puis décider de poursuivre en ligne ou hors ligne selon votre situation.

​

Nettoyer les anciennes données d’historique

Un script de nettoyage des anciennes données d’historique a été ajouté dans Server Pro 3.5.6, 4.0.6 et 4.1.0.

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

Le script peut être exécuté une fois que tous les projets ont été migrés. Il peut également servir à libérer de l’espace pendant une migration en ligne.

Dans Server Pro avant la version 3.5.13, le script supprime le contenu des collections docHistory et docHistoryIndex. MongoDB ne libère pas l’espace disque après la suppression de documents ; il réutilise cet espace pour de futurs documents de la même collection. Plus rien n’écrira dans ces collections après la migration de l’historique, l’espace disque restera donc inutilisé.

Si vous souhaitez récupérer cet espace disque, vous pouvez passer à Server Pro 3.5.13 (si vous êtes encore sur la version 3.x) ou à Server Pro 4.2.5 (si vous êtes sur la version 4.x) et relancer le script de nettoyage.

Le script de nettoyage inclus dans les dernières versions correctives de Server Pro 3.5.x et dans les dernières versions 4.x.x supprime les collections en dernière étape.

Le script de nettoyage peut être relancé sans risque.

​

Dépannage

Nous ajouterons ici des conseils de dépannage. Notez que, bien que nous ne fournissions normalement du support qu’aux clients Server Pro, étant donné la nature de cette migration, nous ferons également de notre mieux pour aider les utilisateurs CE rencontrant des problèmes spécifiques à la migration vers l’historique complet des projets.

Si le script de migration vers l’historique complet des projets échoue (c’est-à-dire s’il se termine avec une erreur ou affiche un nombre de projets en échec différent de zéro), envoyez les informations suivantes à notre équipe de support par e-mail à [e-mail], en précisant :

Objet : Full project history migration problem

• Type d’instance : CE ou Server Pro (rayez la mention inutile)
• Type d’installation : Overleaf toolkit, docker-compose.yml ou autre (rayez la mention inutile)
• Version : 3.5.x (toolkit : $ cat config/version)
• Sortie du script de migration (qui devrait se trouver dans le conteneur sous /overleaf/services/web)
• Migrated Projects : (d’après la sortie du script de migration)
• Total Projects : (d’après la sortie du script de migration)
• Remaining Projects : (d’après la sortie du script de migration)
• Durée de la migration :
• Sortie de bin/doctor (si vous utilisez le toolkit)
• Version du Toolkit : $ git rev-parse HEAD (si vous utilisez le Toolkit)

Pensez à joindre à l’e-mail les fichiers journaux des services history-v1, project-history et track-changes. Vous les trouverez dans /var/log/sharelatex à l’intérieur du conteneur sharelatex et pouvez les exporter ainsi :

$ 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

Veuillez supprimer toute information sensible des fichiers journaux avant de les joindre.

​

Trouver les arborescences de fichiers corrompues

La migration peut échouer pour les projets dont l’arborescence de fichiers est malformée (par exemple, lorsque des noms de fichiers sont vides). Vous pouvez obtenir la liste de ces problèmes avec le script find_malformed_filetrees, qui vérifie tous les projets de la base de données :

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

Pour corriger les chemins invalides, utilisez le script fix_malformed_filetree, en exécutant la commande une fois pour chaque chemin incorrect :

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

​

Rétrograder des projets de l’historique complet vers l’ancien historique

Si un projet a été migré vers l’historique complet mais que vous souhaitez revenir à l’ancien historique, utilisez le script downgrade_project comme suit :

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