Предварительные требования
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, где их можно фильтровать по сервису, уровню и тексту, см. Настройка инструментов разработки.

