Перейти к основному содержанию

Предварительные требования

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 г.