(Migración v3.5.13) Migración al historial completo de proyectos

​

Migración al historial completo de proyectos

La versión 3.5.x de la Community Edition incluye la funcionalidad de historial completo de proyectos (Full Project History), que ya está disponible en nuestra oferta SaaS, overleaf.com

Tras actualizar tu instancia a Overleaf CE 3.5.13, todos los proyectos nuevos usarán por defecto el historial completo de proyectos. Los proyectos existentes seguirán usando el sistema de historial heredado hasta que se migren.

Si actualizas a 3.5.13 y decides volver a una versión anterior, deberás restaurar a partir de una copia de seguridad completa del sistema. El historial de los proyectos creados en 3.5.13 no es compatible con versiones anteriores de Overleaf CE.

El nuevo historial completo de proyectos aporta varias mejoras para los usuarios:

• Registra los cambios en archivos binarios, algo que el sistema heredado no admite.
• Admite versiones etiquetadas.
• En general, el sistema es más robusto y hay menos riesgo de pérdida de datos.

Consulta la documentación del historial completo de proyectos para obtener más información.

​

Migrar los proyectos existentes

1. Crear una copia de seguridad

   Crea una copia de seguridad completa de tu instancia con una instantánea consistente de los directorios mongo, redis y sharelatex.

2. Actualizar

   Actualiza la versión de la imagen sharelatex/sharelatex a 3.5.13.

   Toolkit: usa el script $ bin/upgrade para actualizar el Toolkit a la última versión y edita config/version para establecer 3.5.13.

3. Iniciar la instancia

   Lo ideal es impedir que los usuarios accedan a tu instancia mientras se realiza la migración, para evitar pérdidas de datos en caso de que necesites restaurar la copia de seguridad. Consulta Migración sin conexión para obtener más información sobre cómo hacerlo.

4. Esperar a que todos los servicios estén en funcionamiento

   Espera a que todos los servicios estén en funcionamiento (consulta el comando de abajo)

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. Ejecutar el script de migración

   # 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 borra los datos del historial de proyectos migrados parcialmente en el nuevo sistema, lo que permite reintentar la migración de proyectos concretos que fallaron en intentos anteriores;

   --fix-invalid-characters sustituye los caracteres no imprimibles que el nuevo sistema de historial no admite;

   --convert-large-docs-to-file convierte los documentos que superan el umbral de tamaño editable de 2 MB en un archivo no editable)

   La salida debería tener este aspecto:

   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 migración se completa correctamente, obtendrás un código de salida 0 y las últimas líneas indicarán que no ha habido fallos:

   Projects failed:  0
   Done.
   

   Puedes volver a abrir el acceso a tus usuarios (consulta el paso siguiente). Si hay fallos, consulta la sección de solución de problemas más abajo. Aun así, puedes volver a abrir el sitio si los problemas no se corrigen de inmediato; los proyectos no migrados seguirán en el sistema de historial heredado.

6. Volver a abrir el sitio

   Si optaste por realizar una migración sin conexión, tendrás que volver a abrir el sitio. Si sigues con la sesión iniciada, debes:

   1. Hacer clic en el botón Admin y elegir Manage Site
   2. Hacer clic en la pestaña Open/Close Editor
   3. Hacer clic en el botón Reopen Editor

   Si has cerrado el navegador, tendrás que reiniciar el sitio con $ bin/up.

​

Migración sin conexión

Para impedir que los usuarios puedan iniciar sesión mientras se ejecuta el script de migración del historial, sigue estos pasos:

• Inicia sesión en tu instancia de Overleaf con una cuenta de administrador
• Haz clic en el botón Admin y elige Manage Site
• Haz clic en la pestaña Open/Close Editor
• Haz clic en el botón Close Editor
• Haz clic en el botón Disconnect all users

Una vez hecho esto, los usuarios que tengan la sesión iniciada serán redirigidos a la página de mantenimiento, y los nuevos usuarios que visiten la página de inicio de sesión verán la página de mantenimiento y no podrán iniciar sesión.

​

Migración en línea

Es posible ejecutar los scripts de migración mientras la aplicación sigue en funcionamiento. Hay algunas consideraciones que debes tener en cuenta:

• El proceso de migración hace un uso intensivo de la CPU; deberías supervisar el uso de recursos mientras se ejecuta el script.
• Con un valor alto de --concurrency, el bucle de eventos de algunos servicios (track-changes en particular) podría sufrir bloqueos, lo que degradaría la experiencia de usuario. Recomendamos empezar con el valor predeterminado --concurrency=1.
• Puedes detener el script en cualquier momento. Al volver a iniciarlo, la migración se reanudará donde la dejaste. Esto resulta útil si prefieres ejecutar la migración en horas de menor actividad (por ejemplo, por la noche).

Nuestra recomendación es cerrar el sitio y ejecutar la migración sin conexión en una ventana de mantenimiento cuando tengas menos de 1000 proyectos (db.projects.count()). Si el número de proyectos es elevado, puedes ejecutar el script, supervisar su progreso y, después, decidir si continuar ejecutándolo en línea o sin conexión según tu caso particular.

​

Limpiar los datos del historial heredado

En Server Pro 3.5.6, 4.0.6 y 4.1.0 se añadió un script para limpiar los datos del historial heredado.

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

El script puede ejecutarse una vez migrados todos los proyectos. También puede usarse para liberar espacio durante una migración en línea.

En las versiones de Server Pro anteriores a la 3.5.13, el script elimina el contenido de las colecciones docHistory y docHistoryIndex. MongoDB no libera espacio en disco al eliminar documentos; en su lugar, reutiliza ese espacio para futuros documentos de la misma colección. Tras la migración del historial, nada volverá a escribir en estas colecciones, por lo que ese espacio en disco quedará sin usar.

Si quieres volver a disponer de ese espacio en disco, puedes actualizar a Server Pro 3.5.13 (si sigues usando la versión 3.x) o a Server Pro 4.2.5 (si usas la versión 4.x) y volver a ejecutar el script de limpieza.

El script de limpieza incluido en las últimas versiones de parche de Server Pro 3.5.x y en la última 4.x.x elimina las colecciones como paso final.

Es seguro volver a ejecutar el script de limpieza.

​

Solución de problemas

Aquí añadiremos consejos para solucionar problemas. Ten en cuenta que, aunque normalmente solo ofrecemos soporte a los clientes de Server Pro, dada la naturaleza de esta migración, también haremos todo lo posible por ayudar a los clientes de CE que tengan problemas específicos de la migración al historial completo de proyectos.

Si el script de migración al historial completo de proyectos falla (es decir, termina con un error o muestra un número de proyectos fallidos distinto de cero), envía los siguientes datos a nuestro equipo de soporte por correo electrónico a [e-mail], indicando:

Asunto: Full project history migration problem

• Tipo de instancia: CE o Server Pro (elimina lo que no corresponda)
• Tipo de instalación: Overleaf toolkit, docker-compose.yml u otra (elimina lo que no corresponda)
• Versión: 3.5.x (toolkit: $ cat config/version)
• Salida del script de migración (que debería encontrarse en el contenedor en /overleaf/services/web)
• Proyectos migrados: (según la salida del script de migración)
• Proyectos totales: (según la salida del script de migración)
• Proyectos restantes: (según la salida del script de migración)
• Duración de la migración:
• Salida de bin/doctor (si usas el Toolkit)
• Versión del Toolkit: $ git rev-parse HEAD (si usas el Toolkit)

Considera adjuntar al correo los archivos de log de los servicios history-v1, project-history y track-changes. Puedes encontrarlos en /var/log/sharelatex dentro del contenedor sharelatex y exportarlos así:

$ 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

Elimina cualquier información sensible de los archivos de log antes de adjuntarlos.

​

Encontrar árboles de archivos dañados

La migración puede fallar en proyectos que tengan un árbol de archivos mal formado (por ejemplo, con nombres de archivo vacíos). Puedes obtener una lista de estos problemas con el script find_malformed_filetrees, que comprueba todos los proyectos de la base de datos:

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

Para corregir las rutas no válidas, usa el script fix_malformed_filetree, ejecutando el comando una vez por cada ruta incorrecta:

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

​

Revertir proyectos del historial completo al historial heredado

Si hay un proyecto que se ha migrado al historial completo de proyectos pero quieres volver al historial heredado, usa el script downgrade_project de la siguiente manera:

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