Sincronização com Dropbox

Permita que os usuários sincronizem seus projetos com uma pasta no Dropbox deles.

Este recurso foi desenvolvido por ayaka-notes/ayakaleaf-pro. Ele foi introduzido na v6.3.1 como prévia antecipada e será lançado oficialmente na v6.4.0, portanto sua configuração e seu comportamento ainda podem mudar. Precisamos do seu feedback caso encontre algum problema.

A sincronização com Dropbox mantém os projetos de um usuário sincronizados com o Dropbox dele, como no Overleaf Cloud: depois que um usuário vincula sua conta do Dropbox, cada um de seus projetos aparece como uma pasta em Apps/<your Dropbox app>/, as alterações feitas no Overleaf são enviadas ao Dropbox, e as alterações feitas no Dropbox voltam para o Overleaf.

​

Configurar a sincronização com Dropbox

Você precisa habilitar o git-bridge primeiro: sem ele, as configurações da conta ocultam a seção de sincronização de projetos.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Crie um aplicativo no Dropbox App Console, conectado com a conta do Dropbox que será a proprietária do aplicativo:

1. Clique em Create app e preencha a página:
   • 1. Choose an API: selecione Scoped access.
   • 2. Choose the type of access you need: selecione App folder, e não Full Dropbox. O Overleaf só sincroniza dentro da pasta do aplicativo.
   • 3. Name your app: insira um nome, por exemplo, Overleaf. Ele deve ser único no Dropbox. Os projetos de cada usuário aparecem em Apps/<name of your app>/ no Dropbox dele, e esse nome é o DROPBOX_APP_NAME abaixo.
   • Clique em Create app. O aplicativo abre na aba Settings.
2. Na aba Permissions, em Files and folders, marque files.metadata.write, files.content.write e files.content.read. account_info.read e files.metadata.read são marcados junto com elas e não podem ser desmarcados. Não marque outras permissões.
3. Clique em Submit na barra na parte inferior da aba Permissions. Sem o Submit, as permissões não são salvas, e o Dropbox se recusa a sincronizar arquivos para os usuários que vincularem sua conta.

Dropbox App Console: as permissões a marcar, salvas com Submit

4. Na aba Settings, em OAuth 2, insira ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback em Redirect URIs e, em seguida, clique em Add. Digitar a URI não é suficiente: ela só é salva quando aparece na lista acima do campo.

Dropbox App Console: insira a URI de redirecionamento e clique em Add

5. Na aba Settings, em Webhooks, insira ${OVERLEAF_SITE_URL}/dropbox/webhook em Webhook URIs e, em seguida, clique em Add também. O Dropbox a chama imediatamente para verificá-la, então o Overleaf já deve estar em execução com as configurações abaixo e acessível pela internet (consulte Webhook). O status mostra Enabled quando a verificação é concluída com sucesso.

Copie a App key e o App secret (clique em Show) da aba Settings e, em seguida, adicione as seguintes configurações aos seus arquivos de variáveis de ambiente do Overleaf. Você pode adicionar o webhook (etapa 5) depois que o Overleaf estiver em execução com elas.

config/variables.env

# used to encrypt the user's Dropbox refresh token.
# How to generate: `openssl rand -hex 32`
DROPBOX_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Dropbox Sync Settings
DROPBOX_ENABLED=true
DROPBOX_APP_KEY=
DROPBOX_APP_SECRET=
# the name of your Dropbox app (step 1), which is the folder name in Apps/
DROPBOX_APP_NAME=Overleaf

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback
# Webhook is: ${OVERLEAF_SITE_URL}/dropbox/webhook
# (Optional) DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808

• Antes de configurar a URI de redirecionamento e o webhook, certifique-se de que OVERLEAF_SITE_URL esteja definido corretamente.
• O Dropbox fixa as permissões de um token quando o usuário vincula sua conta: enviar permissões não altera os tokens existentes. Os usuários que vincularam a conta antes de as permissões serem enviadas, ou antes de você alterá-las, precisam desvincular e vincular novamente sua conta do Dropbox.
• Um novo aplicativo fica no status Development. Se Development users na aba Settings mostrar Only you, apenas a sua conta do Dropbox pode ser vinculada: clique em Enable additional users para permitir que outros usuários vinculem as deles. Em seguida, é exibido quantos usuários vincularam a conta, por exemplo, 1 / 500: um aplicativo em Development aceita no máximo 500 usuários. Para mais usuários, clique em Apply for production, e o Dropbox analisará o aplicativo.

Se você estiver em uma região com acesso restrito à rede, talvez precise configurar um proxy para acessar o Dropbox. Defina a seguinte variável de ambiente: DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808. Ele deve ser um proxy de encaminhamento HTTP/HTTPS padrão e não deve usar 127.0.0.1.

​

Criar os índices do banco de dados

Execute isto uma única vez, antes que os usuários vinculem suas contas do Dropbox. Os índices que a sincronização com Dropbox usa não são criados automaticamente; sem eles, cada consulta da sincronização percorre a coleção inteira.

Usuários do Toolkit: executem bin/mongo. Usuários do Docker Compose: executem docker compose exec mongo mongosh sharelatex. Em seguida, colem:

db.dropboxEntities.createIndex(
  { 'overleaf.userId': 1, 'dropbox.id': 1 },
  { name: 'overleaf.userId_1_dropbox.id_1', unique: true,
    partialFilterExpression: { 'dropbox.id': { $exists: true } } })
db.dropboxEntities.createIndex(
  { 'overleaf.userId': 1, 'overleaf.id': 1 },
  { name: 'overleaf.userId_1_overleaf.id_1', unique: true,
    partialFilterExpression: { 'overleaf.id': { $exists: true } } })
db.dropboxEntities.createIndex({ 'overleaf.userId': 1, 'dropbox.pathLower': 'hashed' })
db.dropboxProjects.createIndex({ userId: 1, projectId: 1 }, { name: 'projectId_userId_1', unique: true })
db.dropboxProjects.createIndex({ userId: 1, dropboxId: 1 }, { name: 'userId_dropboxId_1', unique: true })

Executar novamente não causa problemas: o MongoDB ignora os índices que já existem.

Não execute, em vez disso, as migrações de dropboxEntities de tools/migrations: 20220825160708_recreate_dropboxEntities remove a coleção, o que apaga o estado de sincronização de todos os usuários.

​

Webhook

O Dropbox informa o Overleaf sobre alterações no Dropbox por meio de um webhook, para que elas apareçam no Overleaf em poucos segundos. O webhook aponta para o endereço do seu site, ${OVERLEAF_SITE_URL}/dropbox/webhook, e nenhuma porta extra é necessária, mas o Dropbox precisa conseguir acessá-lo pela internet. Quando você o adiciona no App Console, o Dropbox o verifica imediatamente.

Sem um webhook, por exemplo, em um servidor que o Dropbox não consegue acessar, as alterações feitas no Overleaf continuam sendo enviadas ao Dropbox, mas as alterações feitas no Dropbox só voltam quando um usuário clica em sync this project now na caixa de diálogo do Dropbox no editor.

​

Como a sincronização funciona

• Vinculação: quando um usuário vincula sua conta do Dropbox, os projetos dos quais ele é proprietário são enviados ao Dropbox. Os projetos compartilhados com ele aparecem no Dropbox na próxima alteração.
• Do Overleaf para o Dropbox: novos arquivos, renomeações, movimentações, exclusões e renomeações de projetos são enviados imediatamente. As edições feitas no editor são enviadas quando o Overleaf as salva em seu armazenamento, alguns minutos depois que todos saem do projeto. Para enviá-las antes, clique em sync this project now na caixa de diálogo do Dropbox no editor (uma vez por minuto).
• Do Dropbox para o Overleaf: arquivos novos e alterados, novas pastas e exclusões em uma pasta de projeto são aplicados ao projeto. Uma nova pasta no nível superior da pasta do aplicativo se torna um novo projeto. Excluir uma pasta de projeto no Dropbox marca o projeto como excluído no Overleaf.
• Conflitos: quando um arquivo é alterado nos dois lugares ao mesmo tempo, a última alteração prevalece. O Dropbox pode manter a outra versão como uma cópia em conflito.
• Colaboradores: os colaboradores que vinculam seu Dropbox recebem os projetos compartilhados com eles. Visualizadores somente leitura e revisores recebem o projeto, mas suas alterações no Dropbox não são sincronizadas de volta para o Overleaf.
• Arquivos ignorados: os arquivos que o Overleaf não sincroniza, como os resultados da compilação (.aux, .log, …), .DS_Store ou ambientes virtuais Python, permanecem apenas no Dropbox.

​

Q&A

Por que um usuário não consegue vincular sua conta do Dropbox?

• Uma pasta do Dropbox que o Overleaf ainda não conhece é associada a um projeto pelo nome; portanto, um usuário cujos projetos têm o mesmo nome é solicitado a renomeá-los primeiro. Os nomes são comparados sem diferenciar maiúsculas de minúsculas, e projetos arquivados e na lixeira também contam.
• Uma conta do Dropbox só pode ser vinculada a uma conta do Overleaf.

Por que uma conta do Dropbox foi desvinculada?

Resposta: O Overleaf desvincula uma conta do Dropbox quando o Dropbox recusa seu token (por exemplo, depois que o usuário removeu o aplicativo no Dropbox), quando o Dropbox está cheio ou quando o Dropbox suspendeu a conta. Uma notificação na lista de projetos informa ao usuário qual desses casos ocorreu, até que ele vincule a conta novamente. O usuário pode vinculá-la novamente quando o problema for resolvido.

Posso renomear uma pasta de projeto no Dropbox?

Resposta: Em vez disso, renomeie o projeto no Overleaf: a pasta dele no Dropbox também é renomeada. Para o Overleaf, renomear a pasta no Dropbox exclui a pasta do projeto e cria uma nova; assim, o projeto antigo é marcado como excluído e um novo projeto é criado a partir dos arquivos.

Por que algumas pastas de projeto são numeradas, como “Thesis (1)”?

Resposta: Cada projeto tem sua própria pasta, mesmo quando dois projetos têm o mesmo nome. O Dropbox não pode ter duas pastas com o mesmo nome, então adiciona um número à pasta criada depois. O número depende de quais nomes estavam livres no Dropbox naquele momento, e não de qual projeto é mais antigo. O Overleaf sabe qual é a pasta de cada projeto, então as alterações nunca vão para a pasta de outro projeto com o mesmo nome.

Um projeto enviado cujo nome já está em uso também recebe um nome com número no Overleaf, por exemplo “Thesis (1)”.

O que acontece quando excluo uma pasta de projeto no Dropbox?

• Se nenhum outro projeto tiver o nome da pasta, o projeto é marcado como excluído no Overleaf. Seus arquivos e seu histórico são mantidos.
• Se vários projetos tiverem esse nome, o Overleaf não consegue saber a qual deles a pasta pertencia. Ele desvincula a conta do Dropbox e mostra uma notificação pedindo para renomear os projetos. Dê nomes distintos aos projetos antes de excluir as pastas deles no Dropbox.
• Uma pasta numerada, como “Thesis (1)”, não corresponde a nenhum nome de projeto; portanto, excluí-la não altera o projeto no Overleaf. Clique em sync this project now na caixa de diálogo do Dropbox no editor para enviar o projeto ao Dropbox novamente.

O que acontece no Dropbox quando excluo um projeto no Overleaf?

Resposta: Nada; a pasta dele permanece no Dropbox. Exclua a pasta no Dropbox se não precisar mais dela.

O que acontece com as alterações no Dropbox enquanto um projeto está arquivado ou na lixeira?

Resposta: Elas não são aplicadas ao projeto, e restaurar o projeto também não as traz. Após a restauração, o Overleaf deixa de enviar as próprias alterações dos arquivos que foram alterados no Dropbox nesse meio-tempo, de modo que os dois lados ficam diferentes.

Para sincronizar novamente um desses arquivos, salve-o mais uma vez no Dropbox. O Overleaf então adota a versão do Dropbox: as alterações feitas no arquivo no Overleaf desde a restauração são substituídas e permanecem no histórico do projeto. Restaure um projeto antes de alterá-lo no Dropbox.

Por que o link do Dropbox no editor abre a página inicial do Dropbox?

Resposta: O link aponta para Apps/<app folder>/<project> no dropbox.com, como no Overleaf Cloud. Quando o Dropbox mostra a pasta Apps com um nome traduzido, por exemplo 应用 em chinês, o link não encontra a pasta e o Dropbox abre a página inicial. Abra a pasta do projeto a partir da pasta Apps traduzida no Dropbox.

Por que alguns arquivos de um projeto estão faltando no Dropbox?

Resposta: As alterações feitas enquanto o serviço de sincronização não estava em execução, por exemplo durante uma reinicialização, não são enviadas ao Dropbox depois. Clique em sync this project now na caixa de diálogo do Dropbox no editor: isso envia o projeto inteiro novamente.