Synchronizace s Dropboxem

Umožněte uživatelům synchronizovat jejich projekty se složkou v jejich Dropboxu.

Tuto funkci vyvinul projekt ayaka-notes/ayakaleaf-pro. Je k dispozici ve verzi v6.3.1 jako předběžná verze (early preview) a oficiálně bude vydána ve verzi v6.4.0, takže se její konfigurace a chování ještě mohou změnit. Pokud narazíte na jakýkoli problém, uvítáme vaši zpětnou vazbu.

Synchronizace s Dropboxem udržuje projekty uživatele synchronizované s jeho Dropboxem, stejně jako v Overleaf Cloud: jakmile uživatel propojí svůj účet Dropbox, každý jeho projekt se objeví jako složka v Apps/<your Dropbox app>/, změny v Overleafu se odesílají do Dropboxu a změny provedené v Dropboxu se vracejí do Overleafu.

​

Nastavení synchronizace s Dropboxem

Nejprve musíte povolit git-bridge: bez něj nastavení účtu skryje sekci synchronizace projektů.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Vytvořte aplikaci v Dropbox App Console, přihlášeni účtem Dropbox, který bude aplikaci vlastnit:

1. Klikněte na Create app a poté vyplňte stránku:
   • 1. Choose an API: zvolte Scoped access.
   • 2. Choose the type of access you need: zvolte App folder, nikoli Full Dropbox. Overleaf synchronizuje pouze uvnitř složky aplikace.
   • 3. Name your app: zadejte název, např. Overleaf. Musí být v rámci Dropboxu jedinečný. Projekty každého uživatele se objeví v jeho Dropboxu v Apps/<name of your app>/ a tento název je níže uvedená hodnota DROPBOX_APP_NAME.
   • Klikněte na Create app. Aplikace se otevře na kartě Settings.
2. Na kartě Permissions v části Files and folders zaškrtněte files.metadata.write, files.content.write a files.content.read. Oprávnění account_info.read a files.metadata.read se zaškrtnou spolu s nimi a nelze je odškrtnout. Žádná další oprávnění nezaškrtávejte.
3. Klikněte na Submit v liště v dolní části karty Permissions. Bez kliknutí na Submit se oprávnění neuloží a Dropbox odmítne synchronizovat soubory uživatelům, kteří svůj účet propojí.

Dropbox App Console: oprávnění, která je třeba zaškrtnout a uložit pomocí Submit

4. Na kartě Settings v části OAuth 2 zadejte do pole Redirect URIs hodnotu ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback a poté klikněte na Add. Pouhé napsání URI nestačí: uloží se teprve ve chvíli, kdy se zobrazí v seznamu nad polem.

Dropbox App Console: zadejte redirect URI a poté klikněte na Add

5. Na kartě Settings v části Webhooks zadejte do pole Webhook URIs hodnotu ${OVERLEAF_SITE_URL}/dropbox/webhook a poté rovněž klikněte na Add. Dropbox ji okamžitě zavolá, aby ji ověřil, takže Overleaf už musí běžet s níže uvedeným nastavením a musí být dostupný z internetu (viz Webhook). Po úspěšném ověření se zobrazí stav Enabled.

Zkopírujte App key a App secret (klikněte na Show) z karty Settings a poté přidejte následující nastavení do souborů s proměnnými prostředí Overleafu. Webhook (krok 5) můžete přidat, až bude Overleaf s tímto nastavením spuštěný.

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

• Před konfigurací redirect URI a webhooku se ujistěte, že je OVERLEAF_SITE_URL nastaveno správně.
• Dropbox stanoví oprávnění tokenu ve chvíli, kdy uživatel propojí svůj účet: odeslání oprávnění nemění již existující tokeny. Uživatelé, kteří účet propojili dříve, než byla oprávnění odeslána nebo než jste je změnili, musí propojení svého účtu Dropbox zrušit a propojit jej znovu.
• Nová aplikace je ve stavu Development. Pokud je u položky Development users na kartě Settings uvedeno Only you, lze propojit pouze váš účet Dropbox: kliknutím na Enable additional users umožníte propojení i ostatním uživatelům. Poté se zobrazuje, kolik uživatelů je propojeno, např. 1 / 500: aplikace ve stavu Development pojme nejvýše 500 uživatelů. Pro více uživatelů klikněte na Apply for production a Dropbox aplikaci posoudí.

Pokud se nacházíte v regionu s omezeným přístupem k síti, možná budete muset pro přístup k Dropboxu nakonfigurovat proxy. Nastavte následující proměnnou prostředí: DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808. Musí jít o standardní dopřednou HTTP/HTTPS proxy a nesmí používat 127.0.0.1.

​

Vytvoření databázových indexů

Spusťte to jednou, ještě než uživatelé propojí své účty Dropbox. Indexy, které synchronizace s Dropboxem používá, se nevytvářejí automaticky, takže bez nich každé vyhledávání při synchronizaci prochází celou kolekci.

Uživatelé Toolkitu: spusťte bin/mongo. Uživatelé Docker Compose: spusťte docker compose exec mongo mongosh sharelatex. Poté vložte:

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

Opakované spuštění neuškodí: MongoDB indexy, které již existují, přeskočí.

Nespouštějte místo toho migrace dropboxEntities z tools/migrations: 20220825160708_recreate_dropboxEntities kolekci zahodí, čímž smaže stav synchronizace všech uživatelů.

​

Webhook

Dropbox informuje Overleaf o změnách v Dropboxu pomocí webhooku, takže se v Overleafu projeví během několika sekund. Webhook směřuje na adresu vašeho webu, ${OVERLEAF_SITE_URL}/dropbox/webhook, a není potřeba žádný další port, ale Dropbox se k němu musí dostat z internetu. Když jej přidáte v App Console, Dropbox jej okamžitě ověří.

Bez webhooku, například na serveru, ke kterému se Dropbox nedostane, se změny v Overleafu do Dropboxu stále odesílají, ale změny v Dropboxu se vrátí pouze tehdy, když uživatel klikne na sync this project now v dialogu Dropboxu v editoru.

​

Jak synchronizace funguje

• Propojení: když uživatel propojí svůj účet Dropbox, projekty, které vlastní, se odešlou do Dropboxu. Projekty s ním sdílené se v Dropboxu objeví při své další změně.
• Z Overleafu do Dropboxu: nové soubory, přejmenování, přesuny, smazání a přejmenování projektů se odesílají okamžitě. Úpravy v editoru se odešlou, jakmile je Overleaf uloží do svého úložiště, tedy několik minut poté, co všichni projekt opustí. Chcete-li je odeslat dříve, klikněte na sync this project now v dialogu Dropboxu v editoru (jednou za minutu).
• Z Dropboxu do Overleafu: nové a změněné soubory, nové složky a smazání ve složce projektu se v projektu použijí. Nová složka v nejvyšší úrovni složky aplikace se stane novým projektem. Smazání složky projektu v Dropboxu označí projekt v Overleafu jako smazaný.
• Konflikty: když se soubor změní na obou místech současně, platí poslední změna. Dropbox může druhou verzi ponechat jako conflicted copy.
• Spolupracovníci: spolupracovníci, kteří propojí svůj Dropbox, získají projekty, které s nimi byly sdíleny. Čtenáři s oprávněním pouze ke čtení a recenzenti projekt získají, ale jejich změny v Dropboxu se do Overleafu nesynchronizují.
• Ignorované soubory: soubory, které Overleaf nesynchronizuje, jako výstupy sestavení (.aux, .log, …), .DS_Store nebo virtuální prostředí Pythonu, zůstávají pouze v Dropboxu.

​

Q&A

Proč uživatel nemůže propojit svůj účet Dropbox?

• Složka v Dropboxu, kterou Overleaf ještě nezná, se s projektem páruje podle názvu, takže uživatel, jehož projekty mají stejný název, je vyzván, aby je nejprve přejmenoval. Názvy se porovnávají bez ohledu na velikost písmen a započítávají se i archivované projekty a projekty v koši.
• Účet Dropbox lze propojit pouze s jedním účtem Overleaf.

Proč bylo propojení účtu Dropbox zrušeno?

Odpověď: Overleaf zruší propojení účtu Dropbox, když Dropbox odmítne jeho token (například poté, co uživatel aplikaci v Dropboxu odebral), když je Dropbox plný nebo když Dropbox účet pozastavil. Oznámení v seznamu projektů uživateli sděluje, která z těchto situací nastala, dokud účet znovu nepropojí. Po vyřešení problému může uživatel účet znovu propojit.

Mohu v Dropboxu přejmenovat složku projektu?

Odpověď: Přejmenujte prosím místo toho projekt v Overleafu: přejmenuje se i jeho složka v Dropboxu. Pro Overleaf znamená přejmenování složky v Dropboxu smazání složky projektu a vytvoření nové, takže starý projekt se označí jako smazaný a ze souborů se vytvoří nový projekt.

Proč jsou některé složky projektů očíslované, například „Thesis (1)“?

Odpověď: Každý projekt má vlastní složku, i když mají dva projekty stejný název. Dropbox nemůže obsahovat dvě složky se stejným názvem, a proto ke složce vytvořené později přidá číslo. Číslo závisí na tom, které názvy byly v Dropboxu v danou chvíli volné, nikoli na tom, který projekt je starší. Overleaf zná složku každého projektu, takže změny nikdy neputují do složky jiného projektu se stejným názvem.

Nahraný projekt, jehož název je již obsazen, dostane číslo i v Overleafu, například „Thesis (1)“.

Co se stane, když v Dropboxu smažu složku projektu?

• Pokud žádný jiný projekt nemá název této složky, projekt se v Overleafu označí jako smazaný. Jeho soubory a historie zůstanou zachovány.
• Pokud má tento název více projektů, Overleaf nedokáže určit, ke kterému z nich složka patřila. Zruší propojení účtu Dropbox a zobrazí oznámení s výzvou k přejmenování projektů. Než budete mazat jejich složky v Dropboxu, dejte projektům odlišné názvy.
• Očíslovaná složka, například „Thesis (1)“, neodpovídá názvu žádného projektu, takže její smazání projekt v Overleafu nezmění. Chcete-li projekt znovu odeslat do Dropboxu, klikněte na sync this project now v dialogu Dropboxu v editoru.

Co se stane v Dropboxu, když smažu projekt v Overleafu?

Odpověď: Nic, jeho složka v Dropboxu zůstane. Pokud ji již nepotřebujete, smažte ji v Dropboxu.

Co se stane se změnami v Dropboxu, když je projekt archivovaný nebo v koši?

Odpověď: Do projektu se nepoužijí a neprojeví se ani po obnovení projektu. Po obnovení Overleaf přestane odesílat své změny souborů, které se mezitím změnily v Dropboxu, takže se obě strany liší.

Chcete-li takový soubor znovu synchronizovat, uložte jej ještě jednou v Dropboxu. Overleaf pak převezme verzi z Dropboxu: změny provedené v souboru v Overleafu od obnovení se nahradí a zůstanou v historii projektu. Projekt obnovte dříve, než jej v Dropboxu změníte.

Proč odkaz na Dropbox v editoru otevírá domovskou stránku Dropboxu?

Odpověď: Odkaz vede na Apps/<app folder>/<project> na dropbox.com, stejně jako v Overleaf Cloud. Když Dropbox zobrazuje svou složku Apps pod přeloženým názvem, například 应用 v čínštině, odkaz složku nenajde a Dropbox místo toho otevře svou domovskou stránku. Otevřete složku projektu z přeložené složky Apps v Dropboxu.

Proč v Dropboxu chybí některé soubory projektu?

Odpověď: Změny provedené v době, kdy služba synchronizace neběžela, například během jejího restartu, se do Dropboxu dodatečně neodešlou. Klikněte na sync this project now v dialogu Dropboxu v editoru: odešle znovu celý projekt.