Dropbox-synchronisatie

Laat gebruikers hun projecten synchroniseren met een map in hun Dropbox.

Deze functie is ontwikkeld door ayaka-notes/ayakaleaf-pro. Ze is geïntroduceerd in v6.3.1 als vroege preview en wordt officieel uitgebracht in v6.4.0, dus de configuratie en het gedrag kunnen nog veranderen. We horen graag je feedback als je problemen hebt.

Dropbox-synchronisatie houdt de projecten van een gebruiker gesynchroniseerd met zijn Dropbox, zoals op Overleaf Cloud: zodra een gebruiker zijn Dropbox-account koppelt, verschijnt elk van zijn projecten als map in Apps/<your Dropbox app>/, worden wijzigingen in Overleaf naar Dropbox gestuurd en komen wijzigingen in Dropbox terug in Overleaf.

​

Dropbox-synchronisatie instellen

Je moet eerst git-bridge inschakelen: zonder git-bridge verbergen de accountinstellingen het onderdeel voor projectsynchronisatie.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Maak een app aan in de Dropbox App Console, aangemeld met het Dropbox-account dat eigenaar van de app wordt:

1. Klik op Create app en vul de pagina in:
   • 1. Choose an API: selecteer Scoped access.
   • 2. Choose the type of access you need: selecteer App folder, niet Full Dropbox. Overleaf synchroniseert alleen binnen de map van de app.
   • 3. Name your app: voer een naam in, bijvoorbeeld Overleaf. Deze moet uniek zijn op Dropbox. De projecten van elke gebruiker verschijnen in Apps/<name of your app>/ in zijn Dropbox, en deze naam is DROPBOX_APP_NAME hieronder.
   • Klik op Create app. De app opent op het tabblad Settings.
2. Vink op het tabblad Permissions onder Files and folders files.metadata.write, files.content.write en files.content.read aan. account_info.read en files.metadata.read worden daarmee ook aangevinkt en kunnen niet worden uitgevinkt. Vink geen andere rechten aan.
3. Klik op Submit in de balk onderaan het tabblad Permissions. Zonder Submit worden de rechten niet opgeslagen, en weigert Dropbox bestanden te synchroniseren voor de gebruikers die hun account koppelen.

Dropbox App Console: de aan te vinken rechten, opgeslagen met Submit

4. Voer op het tabblad Settings onder OAuth 2 ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback in bij Redirect URIs en klik op Add. Alleen de URI typen is niet genoeg: deze wordt pas opgeslagen zodra hij in de lijst boven het veld verschijnt.

Dropbox App Console: voer de redirect-URI in en klik op Add

5. Voer op het tabblad Settings onder Webhooks ${OVERLEAF_SITE_URL}/dropbox/webhook in bij Webhook URIs en klik ook hier op Add. Dropbox roept de URI meteen aan om hem te controleren, dus Overleaf moet al draaien met de onderstaande instellingen en bereikbaar zijn vanaf het internet (zie Webhook). De status toont Enabled zodra de controle is geslaagd.

Kopieer de App key en het App secret (klik op Show) van het tabblad Settings en voeg vervolgens de volgende instellingen toe aan je Overleaf-omgevingsvariabelenbestanden. Je kunt de webhook (stap 5) toevoegen nadat Overleaf met deze instellingen draait.

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

• Zorg ervoor dat OVERLEAF_SITE_URL correct is ingesteld voordat je de redirect-URI en de webhook configureert.
• Dropbox legt de rechten van een token vast wanneer de gebruiker zijn account koppelt: het indienen van rechten wijzigt bestaande tokens niet. Gebruikers die hun account hebben gekoppeld voordat de rechten werden ingediend, of voordat je ze hebt gewijzigd, moeten de koppeling van hun Dropbox-account verbreken en het opnieuw koppelen.
• Een nieuwe app heeft de status Development. Als Development users op het tabblad Settings Only you toont, kan alleen jouw Dropbox-account worden gekoppeld: klik op Enable additional users zodat andere gebruikers hun account kunnen koppelen. Daarna wordt getoond hoeveel gebruikers hebben gekoppeld, bijvoorbeeld 1 / 500: een Development-app staat maximaal 500 gebruikers toe. Klik voor meer gebruikers op Apply for production, waarna Dropbox de app beoordeelt.

Als je je in een regio met beperkte netwerktoegang bevindt, moet je mogelijk een proxy configureren om Dropbox te bereiken. Stel de volgende omgevingsvariabele in: DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808. Dit moet een standaard HTTP/HTTPS-forwardproxy zijn en mag geen 127.0.0.1 gebruiken.

​

De database-indexen aanmaken

Voer dit eenmalig uit, voordat gebruikers hun Dropbox-account koppelen. De indexen die Dropbox-synchronisatie gebruikt, worden niet automatisch aangemaakt, dus zonder deze indexen doorzoekt elke synchronisatie-opzoeking de hele collectie.

Toolkit-gebruikers: voer bin/mongo uit. Docker Compose-gebruikers: voer docker compose exec mongo mongosh sharelatex uit. Plak daarna:

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

Het opnieuw uitvoeren is onschadelijk: MongoDB slaat indexen over die al bestaan.

Voer in plaats daarvan niet de dropboxEntities-migraties van tools/migrations uit: 20220825160708_recreate_dropboxEntities verwijdert de collectie, waardoor de synchronisatiestatus van elke gebruiker wordt gewist.

​

Webhook

Dropbox meldt wijzigingen in Dropbox aan Overleaf via een webhook, zodat ze binnen enkele seconden in Overleaf verschijnen. De webhook gaat naar het adres van je site, ${OVERLEAF_SITE_URL}/dropbox/webhook. Er is geen extra poort nodig, maar Dropbox moet hem vanaf het internet kunnen bereiken. Wanneer je hem toevoegt in de App Console, controleert Dropbox hem meteen.

Zonder webhook, bijvoorbeeld op een server die Dropbox niet kan bereiken, worden wijzigingen in Overleaf nog steeds naar Dropbox gestuurd, maar komen wijzigingen in Dropbox pas terug wanneer een gebruiker op sync this project now klikt in het Dropbox-dialoogvenster van de editor.

​

Hoe synchroniseren werkt

• Koppelen: wanneer een gebruiker zijn Dropbox-account koppelt, worden de projecten waarvan hij eigenaar is naar Dropbox gestuurd. Projecten die met hem zijn gedeeld, verschijnen in Dropbox bij hun volgende wijziging.
• Overleaf naar Dropbox: nieuwe bestanden, hernoemingen, verplaatsingen, verwijderingen en hernoemde projecten worden meteen verstuurd. Bewerkingen in de editor worden verstuurd zodra Overleaf ze in zijn opslag bewaart, enkele minuten nadat iedereen het project heeft verlaten. Om ze eerder te versturen, klik je op sync this project now in het Dropbox-dialoogvenster van de editor (eenmaal per minuut).
• Dropbox naar Overleaf: nieuwe en gewijzigde bestanden, nieuwe mappen en verwijderingen in een projectmap worden op het project toegepast. Een nieuwe map op het hoogste niveau van de app-map wordt een nieuw project. Als je een projectmap in Dropbox verwijdert, wordt het project in Overleaf als verwijderd gemarkeerd.
• Conflicten: wanneer een bestand op beide plaatsen tegelijk wordt gewijzigd, wint de laatste wijziging. Dropbox kan de andere versie bewaren als conflicted copy.
• Medewerkers: medewerkers die hun Dropbox koppelen, krijgen de projecten die met hen zijn gedeeld. Kijkers met alleen leesrechten en reviewers krijgen het project, maar hun wijzigingen in Dropbox worden niet teruggesynchroniseerd naar Overleaf.
• Genegeerde bestanden: bestanden die Overleaf niet synchroniseert, zoals build-uitvoer (.aux, .log, …), .DS_Store of virtuele Python-omgevingen, blijven alleen in Dropbox.

​

Q&A

Waarom kan een gebruiker zijn Dropbox-account niet koppelen?

• Een Dropbox-map die Overleaf nog niet kent, wordt op naam aan een project gekoppeld, dus een gebruiker van wie projecten dezelfde naam hebben, wordt gevraagd ze eerst te hernoemen. Namen worden zonder onderscheid tussen hoofdletters en kleine letters vergeleken, en gearchiveerde projecten en projecten in de prullenbak tellen ook mee.
• Een Dropbox-account kan maar aan één Overleaf-account worden gekoppeld.

Waarom is de koppeling van een Dropbox-account verbroken?

Antwoord: Overleaf verbreekt de koppeling van een Dropbox-account wanneer Dropbox het token weigert (bijvoorbeeld nadat de gebruiker de app in Dropbox heeft verwijderd), wanneer de Dropbox vol is of wanneer Dropbox het account heeft opgeschort. Een melding in de projectlijst vertelt de gebruiker welke van deze situaties zich heeft voorgedaan, totdat hij het account opnieuw koppelt. De gebruiker kan het account opnieuw koppelen zodra het probleem is opgelost.

Kan ik een projectmap in Dropbox hernoemen?

Antwoord: Hernoem het project liever in Overleaf: de map in Dropbox wordt dan ook hernoemd. Voor Overleaf betekent het hernoemen van de map in Dropbox dat de projectmap wordt verwijderd en een nieuwe wordt aangemaakt. Het oude project wordt dus als verwijderd gemarkeerd en er wordt een nieuw project gemaakt op basis van de bestanden.

Waarom zijn sommige projectmappen genummerd, zoals ‘Thesis (1)’?

Antwoord: Elk project heeft een eigen map, ook wanneer twee projecten dezelfde naam hebben. Dropbox kan geen twee mappen met dezelfde naam bevatten, dus voegt het een nummer toe aan de map die later is gemaakt. Het nummer hangt af van welke namen op dat moment vrij waren in Dropbox, niet van welk project ouder is. Overleaf weet welke map bij elk project hoort, dus wijzigingen gaan nooit naar de map van een ander project met dezelfde naam.

Een geüpload project waarvan de naam al in gebruik is, krijgt ook in Overleaf een naam met een nummer, bijvoorbeeld “Thesis (1)”.

Wat gebeurt er als ik een projectmap in Dropbox verwijder?

• Als geen ander project de naam van de map heeft, wordt het project in Overleaf als verwijderd gemarkeerd. De bestanden en de geschiedenis blijven bewaard.
• Als meerdere projecten die naam hebben, kan Overleaf niet bepalen bij welk project de map hoorde. Het verbreekt de koppeling van het Dropbox-account en toont een melding met het verzoek de projecten te hernoemen. Geef projecten verschillende namen voordat je hun mappen in Dropbox verwijdert.
• Een genummerde map, zoals “Thesis (1)”, komt met geen enkele projectnaam overeen, dus het verwijderen ervan verandert niets aan het project in Overleaf. Klik op sync this project now in het Dropbox-dialoogvenster van de editor om het project opnieuw naar Dropbox te sturen.

Wat gebeurt er in Dropbox als ik een project in Overleaf verwijder?

Antwoord: Niets, de map blijft in Dropbox staan. Verwijder de map in Dropbox als je hem niet meer nodig hebt.

Wat gebeurt er met wijzigingen in Dropbox terwijl een project is gearchiveerd of in de prullenbak staat?

Antwoord: Ze worden niet op het project toegepast, en het herstellen van het project haalt ze ook niet binnen. Na het herstellen stopt Overleaf met het versturen van zijn wijzigingen aan de bestanden die in de tussentijd in Dropbox zijn gewijzigd, zodat de twee kanten van elkaar verschillen.

Om zo’n bestand weer te synchroniseren, sla je het nog een keer op in Dropbox. Overleaf neemt dan de Dropbox-versie over: wijzigingen die sinds het herstellen in Overleaf aan het bestand zijn gemaakt, worden vervangen en blijven in de projectgeschiedenis bewaard. Herstel een project voordat je het in Dropbox wijzigt.

Waarom opent de Dropbox-link van de editor de startpagina van Dropbox?

Antwoord: De link gaat naar Apps/<app folder>/<project> op dropbox.com, zoals op Overleaf Cloud. Wanneer Dropbox de map Apps onder een vertaalde naam toont, bijvoorbeeld 应用 in het Chinees, vindt de link de map niet en opent Dropbox in plaats daarvan de startpagina. Open de projectmap vanuit de vertaalde map Apps in Dropbox.

Waarom ontbreken sommige bestanden van een project in Dropbox?

Antwoord: Wijzigingen die zijn gemaakt terwijl de synchronisatiedienst niet draaide, bijvoorbeeld tijdens een herstart, worden later niet naar Dropbox gestuurd. Klik op sync this project now in het Dropbox-dialoogvenster van de editor: dan wordt het hele project opnieuw verstuurd.