(Migração v3.5.13) Migração para o histórico completo de projetos

​

Migração para o histórico completo de projetos

A versão 3.5.x da Community Edition inclui o recurso Full Project History, que já está disponível na nossa oferta SaaS, o overleaf.com

Depois de atualizar a sua instância para o Overleaf CE 3.5.13, todos os novos projetos usarão o Full Project History por padrão. Os projetos existentes continuarão usando o sistema de histórico legado até serem migrados.

Se você atualizar para a 3.5.13 e decidir voltar para uma versão anterior, deverá restaurar a partir de um backup completo do sistema. O histórico dos projetos criados na 3.5.13 não é compatível com versões anteriores do Overleaf CE.

O novo Full Project History traz várias melhorias para os usuários:

• Rastreia alterações em arquivos binários, o que não é suportado no sistema legado.
• Há suporte para versões com rótulos.
• O sistema é, em geral, mais robusto, com menor risco de perda de dados.

Consulte a documentação do Full Project History para mais informações sobre o histórico completo de projetos.

​

Migrar projetos existentes

1. Criar um backup

   Crie um backup completo da sua instância, com um snapshot consistente dos diretórios mongo, redis e sharelatex.

2. Atualizar

   Atualize a versão da imagem sharelatex/sharelatex para 3.5.13.

   Toolkit: use o script $ bin/upgrade para atualizar o Toolkit para a versão mais recente e altere config/version para 3.5.13.

3. Iniciar a instância

   Idealmente, você deve impedir que os usuários acessem a sua instância durante a migração, para evitar perda de dados caso seja necessário restaurar o backup. Consulte Offline migration para mais informações sobre como fazer isso.

4. Aguardar até que todos os serviços estejam em execução

   Aguarde até que todos os serviços estejam em execução (veja o comando abaixo)

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. Executar o script de migração

   # 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 limpa os dados de histórico de projetos parcialmente migrados no novo sistema, o que permite repetir a migração de projetos individuais que falharam em tentativas anteriores;

   --fix-invalid-characters substitui caracteres não imprimíveis que não são suportados pelo novo sistema de histórico;

   --convert-large-docs-to-file converte documentos acima do limite de 2MB de tamanho editável em arquivos não editáveis)

   A saída deverá ser semelhante a esta:

   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 a migração for bem-sucedida, você obterá o código de saída 0, e as últimas linhas indicarão que não houve falhas:

   Projects failed:  0
   Done.
   

   Você pode reabrir o acesso aos seus usuários (veja a próxima etapa). Se houver falhas, consulte a seção de solução de problemas abaixo. Ainda é possível reabrir o site se os problemas não forem corrigidos imediatamente; os projetos não migrados continuarão no sistema de histórico legado.

6. Reabrir o site

   Se você optou por realizar uma migração offline, precisará reabrir o site. Se ainda estiver conectado, deverá:

   1. Clicar no botão Admin e escolher Manage Site
   2. Clicar na aba Open/Close Editor
   3. Clicar no botão Reopen Editor

   Se tiver fechado o navegador, precisará reiniciar o site com $ bin/up.

​

Migração offline

Para impedir que os usuários consigam entrar enquanto o script de migração do histórico estiver em execução, siga estas etapas:

• Entre na sua instância do Overleaf com uma conta de administrador
• Clique no botão Admin e escolha Manage Site
• Clique na aba Open/Close Editor
• Clique no botão Close Editor
• Clique no botão Disconnect all users

Depois disso, todos os usuários conectados serão redirecionados para a página de manutenção, e todos os novos usuários que acessarem a página de login verão a página de manutenção e não conseguirão entrar.

​

Migração online

É possível executar os scripts de migração enquanto a aplicação continua em execução. Há algumas considerações a ter em conta:

• O processo de migração usa muita CPU; você deve monitorar o uso de recursos enquanto o script estiver em execução.
• Com um valor alto de --concurrency, o event loop de alguns serviços (track-changes em particular) pode sofrer bloqueios, o que levaria a uma experiência de usuário degradada. Recomendamos começar com o valor padrão --concurrency=1.
• Você pode interromper o script a qualquer momento. Ao iniciá-lo novamente, a migração será retomada de onde parou. Isso é útil caso prefira executar a migração em horários de menor movimento (por exemplo, à noite).

A nossa recomendação é fechar o site e executar a migração offline numa janela de manutenção quando o número de projetos for inferior a 1000 (db.projects.count()). Se o número de projetos for grande, você pode executar o script e monitorar o seu progresso, e depois decidir se continua executando-o online ou offline, de acordo com o seu caso específico.

​

Limpar os dados do histórico legado

Um script para limpar os dados do histórico legado foi adicionado no 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"

O script pode ser executado depois de todos os projetos terem sido migrados. Também pode ser usado para liberar algum espaço durante uma migração online.

No Server Pro anterior à versão 3.5.13, o script exclui o conteúdo das coleções docHistory e docHistoryIndex. O MongoDB não libera espaço em disco depois de excluir documentos; em vez disso, reutiliza esse espaço para futuros documentos na mesma coleção. Nada voltará a escrever nestas coleções após a migração do histórico, por isso o espaço em disco permanecerá sem uso.

Se quiser disponibilizar novamente o espaço em disco, pode atualizar para o Server Pro 3.5.13 (se ainda estiver usando a versão 3.x) ou para o Server Pro 4.2.5 (se estiver usando a versão 4.x) e executar novamente o script de limpeza.

O script de limpeza incluído nas versões de patch mais recentes do Server Pro 3.5.x e na 4.x.x mais recente remove as coleções como etapa final.

É seguro executar novamente o script de limpeza.

​

Solução de problemas

Adicionaremos aqui conselhos de solução de problemas. Observe que, embora normalmente ofereçamos suporte apenas a clientes do Server Pro, dada a natureza desta migração, também faremos o possível para ajudar clientes da CE que tenham problemas específicos da migração para o histórico completo de projetos.

Se o script de migração para o histórico completo de projetos falhar (ou seja, terminar com um erro ou indicar um número de projetos com falha diferente de zero), envie os seguintes detalhes à nossa equipe de suporte por e-mail para [e-mail], indicando:

Assunto: Full project history migration problem

• Tipo de instância: CE ou Server Pro (apague conforme o caso)
• Tipo de instalação: Overleaf Toolkit, docker-compose.yml ou outro (apague conforme o caso)
• Versão: 3.5.x (Toolkit: $ cat config/version)
• Saída do script de migração (que deve estar localizada no contêiner em /overleaf/services/web)
• Projetos migrados: (conforme a saída do script de migração)
• Total de projetos: (conforme a saída do script de migração)
• Projetos restantes: (conforme a saída do script de migração)
• Duração da migração:
• Saída do bin/doctor (ao usar o Toolkit)
• Versão do Toolkit: $ git rev-parse HEAD (ao usar o Toolkit)

Considere anexar ao e-mail os arquivos de log dos serviços history-v1, project-history e track-changes. Você pode encontrá-los em /var/log/sharelatex dentro do contêiner sharelatex e exportá-los assim:

$ 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

Remova quaisquer informações sensíveis dos arquivos de log antes de anexá-los.

​

Encontrar árvores de arquivos corrompidas

A migração pode falhar em projetos que têm uma árvore de arquivos malformada (por exemplo, com nomes de arquivo vazios). Você pode obter uma lista destes problemas usando o script find_malformed_filetrees, que verifica todos os projetos no banco de dados:

$ 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 corrigir os caminhos inválidos, use o script fix_malformed_filetree, executando o comando uma vez para cada caminho inválido:

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

​

Reverter projetos do histórico completo para o histórico legado

Se houver um projeto que foi migrado para o histórico completo de projetos, mas você quiser voltar ao histórico legado, use o script downgrade_project da seguinte forma:

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