Синхронізація з Dropbox

Дозвольте користувачам синхронізувати свої проєкти з папкою у їхньому Dropbox.

Цю функцію розроблено в ayaka-notes/ayakaleaf-pro. Вона з’явилася у v6.3.1 як рання попередня версія й буде офіційно випущена у v6.4.0, тож її конфігурація та поведінка ще можуть змінитися. Якщо у вас виникнуть проблеми, будемо вдячні за відгук.

Синхронізація з Dropbox підтримує проєкти користувача синхронізованими з його Dropbox, як в Overleaf Cloud: щойно користувач прив’яже свій обліковий запис Dropbox, кожен його проєкт з’явиться як папка в Apps/<your Dropbox app>/, зміни в Overleaf надсилаються в Dropbox, а зміни, внесені в Dropbox, повертаються в Overleaf.

​

Налаштування синхронізації з Dropbox

Спершу потрібно ввімкнути git-bridge: без нього налаштування облікового запису приховують розділ синхронізації проєктів.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Створіть застосунок у Dropbox App Console, увійшовши в обліковий запис Dropbox, якому належатиме застосунок:

1. Натисніть Create app, а потім заповніть сторінку:
   • 1. Choose an API: виберіть Scoped access.
   • 2. Choose the type of access you need: виберіть App folder, а не Full Dropbox. Overleaf синхронізує лише вміст папки застосунку.
   • 3. Name your app: введіть назву, наприклад Overleaf. Вона має бути унікальною в Dropbox. Проєкти кожного користувача з’являються в Apps/<name of your app>/ у його Dropbox, і саме ця назва є значенням DROPBOX_APP_NAME нижче.
   • Натисніть Create app. Застосунок відкриється на вкладці Settings.
2. На вкладці Permissions у розділі Files and folders позначте files.metadata.write, files.content.write і files.content.read. account_info.read і files.metadata.read позначаються разом із ними, і зняти з них позначку не можна. Не позначайте інших дозволів.
3. Натисніть Submit на панелі внизу вкладки Permissions. Без Submit дозволи не зберігаються, і Dropbox відмовлятиметься синхронізувати файли для користувачів, які прив’язують свій обліковий запис.

Dropbox App Console: дозволи, які потрібно позначити й зберегти кнопкою Submit

4. На вкладці Settings у розділі OAuth 2 введіть ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback у полі Redirect URIs, а потім натисніть Add. Просто ввести URI недостатньо: його буде збережено лише тоді, коли він з’явиться в списку над полем.

Dropbox App Console: введіть redirect URI, а потім натисніть Add

5. На вкладці Settings у розділі Webhooks введіть ${OVERLEAF_SITE_URL}/dropbox/webhook у полі Webhook URIs, а потім так само натисніть Add. Dropbox одразу звертається до нього для перевірки, тож Overleaf уже має працювати з наведеними нижче налаштуваннями та бути доступним з інтернету (див. Вебхук). Після успішної перевірки його стан зміниться на Enabled.

Скопіюйте App key та App secret (натисніть Show) на вкладці Settings, а потім додайте наведені нижче налаштування до файлів змінних середовища Overleaf. Вебхук (крок 5) можна додати після того, як Overleaf запуститься з цими налаштуваннями.

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

• Перш ніж налаштовувати redirect URI та вебхук, переконайтеся, що OVERLEAF_SITE_URL задано правильно.
• Dropbox фіксує дозволи токена в момент, коли користувач прив’язує свій обліковий запис: збереження дозволів не змінює наявних токенів. Користувачі, які прив’язали обліковий запис до збереження дозволів або до того, як ви їх змінили, мають скасувати прив’язку свого облікового запису Dropbox і прив’язати його знову.
• Новий застосунок має стан Development. Якщо в полі Development users на вкладці Settings указано Only you, прив’язати можна лише ваш обліковий запис Dropbox: натисніть Enable additional users, щоб інші користувачі могли прив’язати свої. Після цього там відображатиметься кількість прив’язаних користувачів, наприклад 1 / 500: застосунок у стані Development підтримує щонайбільше 500 користувачів. Щоб підтримувати більше користувачів, натисніть Apply for production, і Dropbox перевірить застосунок.

Якщо ви перебуваєте в регіоні з обмеженим доступом до мережі, вам може знадобитися налаштувати проксі для доступу до Dropbox. Встановіть таку змінну середовища: DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808. Це має бути стандартний прямий HTTP/HTTPS-проксі, і він не повинен використовувати 127.0.0.1.

​

Створення індексів бази даних

Виконайте це один раз, перш ніж користувачі прив’яжуть свої облікові записи Dropbox. Індекси, які використовує синхронізація з Dropbox, не створюються автоматично, тож без них кожен пошук під час синхронізації сканує всю колекцію.

Користувачі Toolkit: виконайте bin/mongo. Користувачі Docker Compose: виконайте docker compose exec mongo mongosh sharelatex. Потім вставте:

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

Повторний запуск нешкідливий: MongoDB пропускає індекси, які вже існують.

Не запускайте натомість міграції dropboxEntities з tools/migrations: 20220825160708_recreate_dropboxEntities видаляє колекцію, а разом із нею й стан синхронізації всіх користувачів.

​

Webhook

Dropbox повідомляє Overleaf про зміни в Dropbox через вебхук, тож вони з’являються в Overleaf за лічені секунди. Вебхук надходить на адресу вашого сайту, ${OVERLEAF_SITE_URL}/dropbox/webhook, додатковий порт не потрібен, але Dropbox має бути здатен звернутися до нього з інтернету. Коли ви додаєте його в App Console, Dropbox одразу його перевіряє.

Без вебхука, наприклад на сервері, до якого Dropbox не може звернутися, зміни в Overleaf і далі надсилаються в Dropbox, але зміни в Dropbox повертаються лише тоді, коли користувач натискає sync this project now у діалозі Dropbox у редакторі.

​

Як працює синхронізація

• Прив’язка: коли користувач прив’язує свій обліковий запис Dropbox, проєкти, якими він володіє, надсилаються в Dropbox. Проєкти, до яких йому надано спільний доступ, з’являються в Dropbox після їхньої наступної зміни.
• З Overleaf у Dropbox: нові файли, перейменування, переміщення, видалення та перейменування проєктів надсилаються одразу. Зміни, внесені в редакторі, надсилаються, щойно Overleaf збереже їх у своєму сховищі, через кілька хвилин після того, як усі вийдуть із проєкту. Щоб надіслати їх раніше, натисніть sync this project now у діалозі Dropbox у редакторі (не частіше одного разу на хвилину).
• З Dropbox в Overleaf: нові та змінені файли, нові папки й видалення в папці проєкту застосовуються до проєкту. Нова папка на верхньому рівні папки застосунку стає новим проєктом. Видалення папки проєкту в Dropbox позначає проєкт як видалений в Overleaf.
• Конфлікти: коли файл змінюється в обох місцях одночасно, перемагає остання зміна. Dropbox може зберегти іншу версію як conflicted copy.
• Співавтори: співавтори, які прив’язують свій Dropbox, отримують проєкти, до яких їм надано спільний доступ. Читачі з правом лише на перегляд і рецензенти отримують проєкт, але їхні зміни в Dropbox не синхронізуються назад в Overleaf.
• Ігноровані файли: файли, які Overleaf не синхронізує, як-от результати збирання (.aux, .log, …), .DS_Store або віртуальні середовища Python, залишаються лише в Dropbox.

​

Q&A

Чому користувач не може прив'язати свій обліковий запис Dropbox?

• Папка Dropbox, яка ще невідома Overleaf, зіставляється з проєктом за назвою, тому користувачеві, проєкти якого мають однакові назви, буде запропоновано спершу їх перейменувати. Назви порівнюються без урахування регістру, і заархівовані проєкти та проєкти в кошику теж враховуються.
• Обліковий запис Dropbox можна прив’язати лише до одного облікового запису Overleaf.

Чому прив'язку облікового запису Dropbox було скасовано?

Відповідь: Overleaf скасовує прив’язку облікового запису Dropbox, коли Dropbox відхиляє його токен (наприклад, після того як користувач видалив застосунок у Dropbox), коли Dropbox заповнено або коли Dropbox призупинив обліковий запис. Сповіщення у списку проєктів повідомляє користувачеві, що саме сталося, доки він знову не прив’яже обліковий запис. Користувач може прив’язати його знову, щойно проблему буде розв’язано.

Чи можна перейменувати папку проєкту в Dropbox?

Відповідь: Будь ласка, натомість перейменуйте проєкт в Overleaf: його папку в Dropbox теж буде перейменовано. Для Overleaf перейменування папки в Dropbox означає видалення папки проєкту та створення нової, тож старий проєкт позначається як видалений, а з файлів створюється новий проєкт.

Чому деякі папки проєктів пронумеровано, наприклад «Thesis (1)»?

Відповідь: Кожен проєкт має власну папку, навіть коли два проєкти мають однакову назву. Dropbox не може зберігати дві папки з однаковою назвою, тому додає номер до папки, створеної пізніше. Номер залежить від того, які назви були вільні в Dropbox у той момент, а не від того, який проєкт старший. Overleaf знає папку кожного проєкту, тож зміни ніколи не потрапляють до папки іншого проєкту з тією самою назвою.

Завантажений проєкт, назву якого вже зайнято, в Overleaf також отримує назву з номером, наприклад «Thesis (1)».

Що станеться, якщо видалити папку проєкту в Dropbox?

• Якщо жоден інший проєкт не має назви цієї папки, проєкт позначається як видалений в Overleaf. Його файли та історія зберігаються.
• Якщо цю назву мають кілька проєктів, Overleaf не може визначити, якому з них належала папка. Він скасовує прив’язку облікового запису Dropbox і показує сповіщення з проханням перейменувати проєкти. Дайте проєктам різні назви, перш ніж видаляти їхні папки в Dropbox.
• Пронумерована папка, наприклад «Thesis (1)», не збігається з жодною назвою проєкту, тож її видалення не змінює проєкт в Overleaf. Натисніть sync this project now у діалозі Dropbox у редакторі, щоб знову надіслати проєкт у Dropbox.

Що станеться в Dropbox, якщо видалити проєкт в Overleaf?

Відповідь: Нічого, його папка залишається в Dropbox. Видаліть папку в Dropbox, якщо вона вам більше не потрібна.

Що відбувається зі змінами в Dropbox, поки проєкт заархівовано або переміщено до кошика?

Відповідь: Вони не застосовуються до проєкту, і відновлення проєкту їх теж не переносить. Після відновлення Overleaf перестає надсилати свої зміни тих файлів, які тим часом було змінено в Dropbox, тож дві сторони розходяться.

Щоб знову синхронізувати такий файл, збережіть його ще раз у Dropbox. Тоді Overleaf прийме версію з Dropbox: зміни, внесені у файл в Overleaf після відновлення, буде замінено, але вони залишаться в історії проєкту. Відновлюйте проєкт, перш ніж змінювати його в Dropbox.

Чому посилання на Dropbox у редакторі відкриває головну сторінку Dropbox?

Відповідь: Посилання веде на Apps/<app folder>/<project> на dropbox.com, як в Overleaf Cloud. Коли Dropbox показує свою папку Apps під перекладеною назвою, наприклад 应用 китайською, посилання не знаходить папку, і Dropbox натомість відкриває свою головну сторінку. Відкрийте папку проєкту з перекладеної папки Apps у Dropbox.

Чому деяких файлів проєкту немає в Dropbox?

Відповідь: Зміни, внесені, поки служба синхронізації не працювала, наприклад під час її перезапуску, пізніше в Dropbox не надсилаються. Натисніть sync this project now у діалозі Dropbox у редакторі: він знову надішле весь проєкт.