Передумови
Overleaf — типовий проєкт з відкритим кодом із мікросервісною архітектурою, усі служби якого працюють у Docker.- Вихідний код офіційної Community Edition доступний на GitHub Overleaf Official.
- Вихідний код Overleaf-CEP доступний на GitHub Yu-i-i/Overleaf.
- Ayakaleaf Pro доступний на GitHub ayaka-notes/ayakaleaf-pro.
Оскільки сервери з 8 і більше ядрами CPU зазвичай дорогі, наполегливо рекомендуємо використовувати для розробки свій локальний комп’ютер.
- Потужний сервер/настільний комп’ютер для розробки
- Свіжа та стабільна 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
Запустіть усі мікросервіси
Потім запустіть служби:Коли служби запрацюють, відкрийте http://localhost/launchpad, щоб створити перший обліковий запис адміністратора. Додайте порт, якщо ви змінили
bash
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 і 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 не завантажує образи сам, тож завантажте їх один раз:
dev.env також вмикає конвертацію Pandoc з PANDOC_IMAGE=overleaf-pandoc:local. Зберіть цей образ один раз із кореня репозиторію:
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, де їх можна фільтрувати за сервісом, рівнем і текстом, див. Налаштування інструментів розробки.

