Перейти до основного вмісту

Передумови

Overleaf — типовий проєкт з відкритим кодом із мікросервісною архітектурою, усі служби якого працюють у Docker. Для налаштування середовища розробки Overleaf вам знадобиться потужний сервер; рекомендовано конфігурацію щонайменше з 8 ядрами та 16 ГБ оперативної пам’яті, оскільки одночасно потрібно запускати понад 20 контейнерів.
Оскільки сервери з 8 і більше ядрами CPU зазвичай дорогі, наполегливо рекомендуємо використовувати для розробки свій локальний комп’ютер.
Водночас ми вважаємо, що як розробник ви вже знайомі з установленням Docker. Наполегливо радимо використовувати для розробки свіжу та стабільну Ubuntu LTS (наприклад, Ubuntu 24.04 у 2025–2026 роках) і найновішу версію Docker, оскільки це зменшує ймовірність несподіваних помилок. Отже, вам знадобиться:
  • Потужний сервер/настільний комп’ютер для розробки
  • Свіжа та стабільна Ubuntu LTS (наприклад, Ubuntu 24.04)
  • Середовище Docker і Git

Інструкція з налаштування

Тут ми на прикладі Ayakaleaf Pro показуємо, як налаштувати середовище розробки Overleaf. Усі наведені нижче команди виконуються в каталозі develop, якщо не зазначено інше.
1

Отримайте вихідний код

Насамперед клонуймо репозиторій:
bash
2

Синхронізація yarn.lock

Репозиторій використовує Yarn 4 (packageManager у кореневому package.json), і його yarn.lock може розходитися з файлами package.json. Синхронізуйте його після першого клонування та після будь-якої зміни package.json:
bash
bin/sync виконує yarn install --mode=update-lockfile у контейнері node:24.18.1, тож Node.js на хості не потрібен. Не комітьте змінений yarn.lock.
3

Зберіть образ для розробки

Зберіть сервіси:
bash
Якщо Docker вичерпує оперативну пам’ять під час паралельного збирання служб, створіть у цьому каталозі файл .env, що містить COMPOSE_PARALLEL_LIMIT=1.
4

Застосування перекладів

Модулі Ayakaleaf Pro зберігають свої переклади в services/web/locales/locales_patches/, яких немає в закомічених файлах локалей. Застосуйте їх один раз перед першим запуском, інакше сторінки цих модулів показуватимуть замість тексту ключі на кшталт about_to_permanently_delete_accounts:
bash
Потрібен jq на хості. Запустіть його знову після додавання перекладу або зміни гілки, див. Оновлення перекладів i18n.
5

Запустіть усі мікросервіси

Потім запустіть служби:
bash
Коли служби запрацюють, відкрийте http://localhost/launchpad, щоб створити перший обліковий запис адміністратора. Додайте порт, якщо ви змінили OVERLEAF_PORT (див. нижче).
LDAP увімкнено за замовчуванням (LDAP_ENABLED=true у dev.rc). Тоді launchpad показує форму адміністратора LDAP: вона запитує лише email, а потім цей адміністратор входить через LDAP, наприклад як professor / professor (professor@planetexpress.com). Тестових користувачів перелічено в develop/authentication/README.md. Задайте LDAP_ENABLED=false і SAML_ENABLED=false, щоб натомість створити локального адміністратора з паролем.
develop/dev.env уже задає ADMIN_PRIVILEGE_AVAILABLE=true, тож адміністратори можуть відкрити панель адміністратора без додаткового налаштування.

Конфігурація (dev.rc)

develop/dev.rc поруч із dev.env містить перемикачі середовища розробки, як overleaf.rc в Overleaf Toolkit. Змініть значення й знову запустіть bin/dev, щоб застосувати його; вимкнена функція також зупиняє свої контейнери. Кожна функція зберігає свій docker-compose.yml та інші файли в окремій теці: authentication/ldap, authentication/saml, mail, s3, hoppscotch і grafana. Функція, якій потрібне налаштування web без змінної середовища, монтує файл у /etc/overleaf/settings.d/, а develop/settings.dev-env.cjs об’єднує їх усі. Усі скрипти bin/* працюють через bin/docker-compose, який додає файли увімкнених функцій. Викликайте bin/docker-compose замість docker compose, коли вам самим потрібна команда compose.
Локальні томи й RustFS — окремі сховища: у проєкту, створеного з S3_ENABLED=true, після перемикання на false немає історії та двійкових файлів, і навпаки. Щоб скопіювати до RustFS файли середовища, яке працювало до появи S3_ENABLED, виконайте розділ «Moving existing data into RustFS» у develop/README.md.

Порти

Сайт, консоль RustFS і Hoppscotch слухають 127.0.0.1 хоста; на віддаленій машині спершу перенаправте їхні порти, наприклад ssh -L 9001:localhost:9001 <host>. Сайт використовує OVERLEAF_PORT із dev.rc, тож додайте порт до адрес нижче, якщо ви його змінили. Mailpit, Grafana, Mongo Express і RedisInsight віддаються сайтом за власними шляхами через webpack-dev-server, тому їм не потрібні власні порти. Після входу меню Dev tools на панелі навігації сайту посилається на них; сторінку, функцію якої вимкнено в dev.rc, не показано. Налаштування інструментів розробки описує, що робить кожен із них. API S3 (порт 9000) і SMTP (порт 1025) доступні лише всередині мережі Docker. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540) і git-bridge (8000) публікуються лише на 127.0.0.1 хоста.

TeX Live

Компіляцію в пісочниці ввімкнено за замовчуванням: develop/dev.env задає SANDBOXED_COMPILES=true та образи ghcr.io/ayaka-notes/texlive-full:2026.1 і ghcr.io/ayaka-notes/texlive-full:2025.1. clsi не завантажує образи сам, тож завантажте їх один раз:
Подробиці див. у розділі Налаштування ізольованої компіляції.
Проєкт, створений, коли SANDBOXED_COMPILES було вимкнено, не має образу TeX Live. Він і далі компілюється образом за замовчуванням, але перехід між кодом і PDF завершується помилкою «That didn’t work. Recompile and try again.» Призначте таким проєктам один раз образ із TEX_LIVE_DOCKER_IMAGE; без --commit скрипт лише показує, що змінив би:
dev.env також вмикає конвертацію Pandoc з PANDOC_IMAGE=overleaf-pandoc:local. Зберіть цей образ один раз із кореня репозиторію:
Щоб компілювати на хості macOS, може знадобитися перевизначити шлях до сокета Docker, створивши в каталозі develop файл .env із вмістом DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Розробка

Щоб не виконувати bin/build && bin/up після кожної зміни коду, можна запустити Overleaf Community Edition у режимі розробки, у якому служби автоматично оновлюються при змінах коду. Для цього скористайтеся вбудованим скриптом bin/dev:
Це запустить усі служби за допомогою node --watch, який автоматично відстежує код і за потреби перезапускає служби. Запустіть його знову після зміни dev.rc. Для підвищення продуктивності можна запустити в режимі розробки лише частину служб, передавши скрипту bin/dev їхній список, розділений пробілами:
Запуск служби web у режимі розробки оновлюватиме службу web лише при зміні коду бекенду. Щоб автоматично оновлювався й код фронтенду, обов’язково також запустіть у режимі розробки службу webpack.
Якщо служби не вказано, у режимі розробки буде запущено всі служби. Після додавання перекладу або зміни гілки виконайте bin/i18n, див. Оновлення перекладів i18n.

Налагодження

У режимі розробки більшість сервісів відкривають порт налагодження, до якого можна під’єднати налагоджувач, наприклад інспектор у Chrome Dev Tools або налагоджувач, вбудований в IDE. У таблиці нижче наведено порт, відкритий на 127.0.0.1 хост-машини для кожного сервісу: Щоб під’єднатися до служби за допомогою віддаленого налагодження Chrome, перейдіть на chrome://inspect/ і переконайтеся, що позначено Discover network targets. Далі натисніть Configure… і додайте запис localhost:[service port] для кожної служби, до якої хочете під’єднати налагоджувач. Після додавання запису служба з’явиться як Remote Target, яку можна інспектувати та налагоджувати.

Журналювання

Скрипт bin/logs стежить за логами й форматує їх за допомогою bunyan. Йому також потрібен ggrep — так називається GNU grep у разі встановлення через Homebrew у macOS; в Ubuntu команди ggrep немає.
Або можна виконати безпосередньо:
Використовуйте bin/docker-compose замість docker compose, щоб знаходилися й сервіси функцій із dev.rc (mailpit, rustfs, ldap, saml, hoppscotch і grafana з Prometheus, Loki та експортерами). За GRAFANA_ENABLED=true логи кожного контейнера також є в Grafana, де їх можна фільтрувати за сервісом, рівнем і текстом, див. Налаштування інструментів розробки.

Інші інструменти

Коли все буде готово, перегляньте наступний розділ, щоб додати інструменти налагодження до вашого середовища розробки Overleaf.
Останнє оновлення 20 листопада 2026 р.