Synchronisation Dropbox

Permettez aux utilisateurs de synchroniser leurs projets avec un dossier de leur Dropbox.

Cette fonctionnalité est développée par ayaka-notes/ayakaleaf-pro. Elle est introduite dans la v6.3.1 en avant-première et sera officiellement publiée dans la v6.4.0 : sa configuration et son comportement peuvent donc encore évoluer. Vos retours nous sont précieux si vous rencontrez un problème.

La synchronisation Dropbox maintient les projets d’un utilisateur synchronisés avec sa Dropbox, comme sur Overleaf Cloud : dès qu’un utilisateur lie son compte Dropbox, chacun de ses projets apparaît sous forme de dossier dans Apps/<your Dropbox app>/, les modifications effectuées dans Overleaf sont envoyées vers Dropbox, et celles effectuées dans Dropbox reviennent dans Overleaf.

​

Configurer la synchronisation Dropbox

Vous devez d’abord activer git-bridge : sans lui, les paramètres du compte masquent la section de synchronisation des projets.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Créez une application dans la Dropbox App Console, en étant connecté avec le compte Dropbox qui sera propriétaire de l’application :

1. Cliquez sur Create app, puis remplissez la page :
   • 1. Choose an API : sélectionnez Scoped access.
   • 2. Choose the type of access you need : sélectionnez App folder, et non Full Dropbox. Overleaf ne synchronise qu’à l’intérieur du dossier de l’application.
   • 3. Name your app : saisissez un nom, par exemple Overleaf. Il doit être unique sur Dropbox. Les projets de chaque utilisateur apparaissent dans Apps/<name of your app>/ dans sa Dropbox, et ce nom correspond à DROPBOX_APP_NAME ci-dessous.
   • Cliquez sur Create app. L’application s’ouvre sur son onglet Settings.
2. Dans l’onglet Permissions, sous Files and folders, cochez files.metadata.write, files.content.write et files.content.read. account_info.read et files.metadata.read sont cochés en même temps et ne peuvent pas être décochés. Ne cochez aucune autre autorisation.
3. Cliquez sur Submit dans la barre en bas de l’onglet Permissions. Sans Submit, les autorisations ne sont pas enregistrées, et Dropbox refuse de synchroniser les fichiers des utilisateurs qui lient leur compte.

Dropbox App Console : les autorisations à cocher, enregistrées avec Submit

4. Dans l’onglet Settings, sous OAuth 2, saisissez ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback dans Redirect URIs, puis cliquez sur Add. Saisir l’URI ne suffit pas : elle n’est enregistrée qu’une fois affichée dans la liste au-dessus du champ.

Dropbox App Console : saisissez l'URI de redirection, puis cliquez sur Add

5. Dans l’onglet Settings, sous Webhooks, saisissez ${OVERLEAF_SITE_URL}/dropbox/webhook dans Webhook URIs, puis cliquez également sur Add. Dropbox l’appelle immédiatement pour la vérifier : Overleaf doit donc déjà fonctionner avec les paramètres ci-dessous et être accessible depuis Internet (voir Webhook). Son statut affiche Enabled une fois la vérification réussie.

Copiez l’App key et l’App secret (cliquez sur Show) depuis l’onglet Settings, puis ajoutez les paramètres suivants à vos fichiers de variables d’environnement Overleaf. Vous pouvez ajouter le webhook (étape 5) une fois qu’Overleaf fonctionne avec ces paramètres.

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

• Avant de configurer l’URI de redirection et le webhook, assurez-vous que OVERLEAF_SITE_URL est correctement défini.
• Dropbox fige les autorisations d’un jeton au moment où l’utilisateur lie son compte : soumettre des autorisations ne modifie pas les jetons existants. Les utilisateurs qui ont lié leur compte avant que les autorisations soient soumises, ou avant que vous les modifiiez, doivent délier puis lier à nouveau leur compte Dropbox.
• Une nouvelle application a le statut Development. Si Development users dans l’onglet Settings affiche Only you, seul votre compte Dropbox peut être lié : cliquez sur Enable additional users pour permettre aux autres utilisateurs de lier le leur. Le nombre d’utilisateurs liés s’affiche alors, par exemple 1 / 500 : une application en Development accepte au maximum 500 utilisateurs. Pour davantage d’utilisateurs, cliquez sur Apply for production, et Dropbox examinera l’application.

Si vous vous trouvez dans une région où l’accès au réseau est restreint, vous devrez peut-être configurer un proxy pour accéder à Dropbox. Définissez la variable d’environnement suivante : DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808. Il doit s’agir d’un proxy de transfert HTTP/HTTPS standard, qui ne doit pas utiliser 127.0.0.1.

​

Créer les index de la base de données

Exécutez ceci une seule fois, avant que les utilisateurs ne lient leurs comptes Dropbox. Les index utilisés par la synchronisation Dropbox ne sont pas créés automatiquement : sans eux, chaque recherche de synchronisation parcourt toute la collection.

Utilisateurs du Toolkit : exécutez bin/mongo. Utilisateurs de Docker Compose : exécutez docker compose exec mongo mongosh sharelatex. Collez ensuite :

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 })

L’exécuter à nouveau est sans danger : MongoDB ignore les index qui existent déjà.

N’exécutez pas à la place les migrations dropboxEntities de tools/migrations : 20220825160708_recreate_dropboxEntities supprime la collection, ce qui efface l’état de synchronisation de tous les utilisateurs.

​

Webhook

Dropbox informe Overleaf des modifications effectuées dans Dropbox au moyen d’un webhook, afin qu’elles apparaissent dans Overleaf en quelques secondes. Le webhook pointe vers l’adresse de votre site, ${OVERLEAF_SITE_URL}/dropbox/webhook, et ne nécessite aucun port supplémentaire, mais Dropbox doit pouvoir y accéder depuis Internet. Lorsque vous l’ajoutez dans l’App Console, Dropbox le vérifie immédiatement.

Sans webhook, par exemple sur un serveur que Dropbox ne peut pas joindre, les modifications effectuées dans Overleaf sont toujours envoyées vers Dropbox, mais celles effectuées dans Dropbox ne reviennent que lorsqu’un utilisateur clique sur sync this project now dans la boîte de dialogue Dropbox de l’éditeur.

​

Fonctionnement de la synchronisation

• Liaison : lorsqu’un utilisateur lie son compte Dropbox, les projets dont il est propriétaire sont envoyés vers Dropbox. Les projets partagés avec lui apparaissent dans Dropbox lors de leur prochaine modification.
• D’Overleaf vers Dropbox : les nouveaux fichiers, les renommages, les déplacements, les suppressions et les renommages de projets sont envoyés immédiatement. Les modifications faites dans l’éditeur sont envoyées une fois qu’Overleaf les a enregistrées dans son stockage, quelques minutes après que tout le monde a quitté le projet. Pour les envoyer plus tôt, cliquez sur sync this project now dans la boîte de dialogue Dropbox de l’éditeur (une fois par minute).
• De Dropbox vers Overleaf : les fichiers nouveaux et modifiés, les nouveaux dossiers et les suppressions dans un dossier de projet sont appliqués au projet. Un nouveau dossier à la racine du dossier de l’application devient un nouveau projet. Supprimer un dossier de projet dans Dropbox marque le projet comme supprimé dans Overleaf.
• Conflits : lorsqu’un fichier est modifié aux deux endroits en même temps, la dernière modification l’emporte. Dropbox peut conserver l’autre version sous forme de conflicted copy.
• Collaborateurs : les collaborateurs qui lient leur Dropbox reçoivent les projets partagés avec eux. Les utilisateurs en lecture seule et les relecteurs reçoivent le projet, mais leurs modifications dans Dropbox ne sont pas synchronisées vers Overleaf.
• Fichiers ignorés : les fichiers qu’Overleaf ne synchronise pas, comme les fichiers de compilation (.aux, .log, …), .DS_Store ou les environnements virtuels Python, restent uniquement dans Dropbox.

​

Q&A

Pourquoi un utilisateur ne peut-il pas lier son compte Dropbox ?

• Un dossier Dropbox qu’Overleaf ne connaît pas encore est associé à un projet par son nom : un utilisateur dont plusieurs projets portent le même nom est donc invité à les renommer au préalable. Les noms sont comparés sans tenir compte de la casse, et les projets archivés ou placés dans la corbeille sont également pris en compte.
• Un compte Dropbox ne peut être lié qu’à un seul compte Overleaf.

Pourquoi un compte Dropbox a-t-il été délié ?

Réponse : Overleaf délie un compte Dropbox lorsque Dropbox refuse son jeton (par exemple après que l’utilisateur a supprimé l’application dans Dropbox), lorsque la Dropbox est pleine, ou lorsque Dropbox a suspendu le compte. Une notification dans la liste des projets indique à l’utilisateur lequel de ces cas s’est produit, jusqu’à ce qu’il lie à nouveau le compte. L’utilisateur peut le lier à nouveau une fois le problème résolu.

Puis-je renommer un dossier de projet dans Dropbox ?

Réponse : Veuillez plutôt renommer le projet dans Overleaf : son dossier dans Dropbox est alors renommé lui aussi. Pour Overleaf, renommer le dossier dans Dropbox revient à supprimer le dossier du projet et à en créer un nouveau : l’ancien projet est donc marqué comme supprimé et un nouveau projet est créé à partir des fichiers.

Pourquoi certains dossiers de projet sont-ils numérotés, comme « Thesis (1) » ?

Réponse : Chaque projet possède son propre dossier, même lorsque deux projets portent le même nom. Dropbox ne pouvant pas contenir deux dossiers du même nom, il ajoute un numéro au dossier créé en dernier. Ce numéro dépend des noms qui étaient libres dans Dropbox à ce moment-là, et non de l’ancienneté des projets. Overleaf connaît le dossier de chaque projet : les modifications ne vont donc jamais dans le dossier d’un autre projet portant le même nom.

Un projet téléversé dont le nom est déjà pris reçoit lui aussi un nom numéroté dans Overleaf, par exemple « Thesis (1) ».

Que se passe-t-il lorsque je supprime un dossier de projet dans Dropbox ?

• Si aucun autre projet ne porte le nom du dossier, le projet est marqué comme supprimé dans Overleaf. Ses fichiers et son historique sont conservés.
• Si plusieurs projets portent ce nom, Overleaf ne peut pas déterminer à quel projet appartenait le dossier. Il délie le compte Dropbox et affiche une notification invitant à renommer les projets. Donnez des noms distincts aux projets avant de supprimer leurs dossiers dans Dropbox.
• Un dossier numéroté, comme « Thesis (1) », ne correspond à aucun nom de projet : le supprimer ne modifie donc pas le projet dans Overleaf. Cliquez sur sync this project now dans la boîte de dialogue Dropbox de l’éditeur pour envoyer à nouveau le projet vers Dropbox.

Que se passe-t-il dans Dropbox lorsque je supprime un projet dans Overleaf ?

Réponse : Rien, son dossier reste dans Dropbox. Supprimez le dossier dans Dropbox si vous n’en avez plus besoin.

Qu'advient-il des modifications effectuées dans Dropbox pendant qu'un projet est archivé ou dans la corbeille ?

Réponse : Elles ne sont pas appliquées au projet, et la restauration du projet ne les intègre pas non plus. Après la restauration, Overleaf cesse d’envoyer ses modifications des fichiers qui ont été modifiés entre-temps dans Dropbox : les deux côtés diffèrent alors.

Pour resynchroniser un tel fichier, enregistrez-le une nouvelle fois dans Dropbox. Overleaf reprend alors la version Dropbox : les modifications apportées au fichier dans Overleaf depuis la restauration sont remplacées et restent dans l’historique du projet. Restaurez un projet avant de le modifier dans Dropbox.

Pourquoi le lien Dropbox de l'éditeur ouvre-t-il la page d'accueil de Dropbox ?

Réponse : Le lien pointe vers Apps/<app folder>/<project> sur dropbox.com, comme sur Overleaf Cloud. Lorsque Dropbox affiche son dossier Apps sous un nom traduit, par exemple 应用 en chinois, le lien ne trouve pas le dossier et Dropbox ouvre sa page d’accueil à la place. Ouvrez le dossier du projet depuis le dossier Apps traduit dans Dropbox.

Pourquoi certains fichiers d'un projet manquent-ils dans Dropbox ?

Réponse : Les modifications effectuées pendant que le service de synchronisation ne fonctionnait pas, par exemple pendant son redémarrage, ne sont pas envoyées ultérieurement vers Dropbox. Cliquez sur sync this project now dans la boîte de dialogue Dropbox de l’éditeur : cela envoie à nouveau l’ensemble du projet.