Налаштування середовища розробки (локально)

Налаштуйте середовище розробки на локальному сервері або настільному комп’ютері.

​

Передумови

Overleaf — типовий проєкт з відкритим кодом із мікросервісною архітектурою, усі служби якого працюють у Docker.

• Вихідний код офіційної Community Edition доступний на GitHub Overleaf Official.
• Вихідний код Overleaf-CEP доступний на GitHub Yu-i-i/Overleaf.
• Overleaf Pro Edition доступна на GitHub Ayaka-notes/overleaf-pro.

Для налаштування середовища розробки Overleaf вам знадобиться потужний сервер; рекомендовано конфігурацію щонайменше з 8 ядрами та 16 ГБ оперативної пам’яті, оскільки одночасно потрібно запускати понад 20 контейнерів.

Оскільки сервери з 8 і більше ядрами CPU зазвичай дорогі, наполегливо рекомендуємо використовувати для розробки свій локальний комп’ютер.

Водночас ми вважаємо, що як розробник ви вже знайомі з установленням Docker. Наполегливо радимо використовувати для розробки свіжу та стабільну Ubuntu LTS (наприклад, Ubuntu 24.04 у 2025–2026 роках) і найновішу версію Docker, оскільки це зменшує ймовірність несподіваних помилок.

Отже, вам знадобиться:

• Потужний сервер/настільний комп’ютер для розробки
• Свіжа та стабільна Ubuntu LTS (наприклад, Ubuntu 24.04)
• Середовище Docker і Git

​

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

Тут ми використаємо overleaf-cep як приклад, щоб показати, як налаштувати середовище розробки Overleaf.

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

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

   bash

   git clone https://github.com/ayaka-notes/overleaf-pro.git
   cd overleaf-pro
   
2. Синхронізуйте package-lock.json

   Оскільки Overleaf розробляється у внутрішньому репозиторії, файл package-lock.json дуже ймовірно розсинхронізується через певні особливості розробки. Щоб синхронізувати його, потрібно виконати наведену нижче команду (якщо у вас є локальне середовище nodejs).

   bash

   npm install --package-lock-only --ignore-scripts
   

   Якщо nodejs не встановлено, не хвилюйтеся: ту саму команду можна виконати безпосередньо за допомогою docker. Запускайте її з кореня репозиторію Overleaf:

   bash

   docker run --rm \
     -v "$(pwd)":/workspace \
     -w /workspace \
     node:22.18.0 \
     npm install --package-lock-only --ignore-scripts
   
3. Зберіть образ для розробки

   Overleaf надає окремий каталог /develop для скриптів розробки. Просто зберіть служби:

   bash

   cd ./develop
   bin/build
   

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

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

   Потім запустіть служби:

   bash

   bin/up
   

   Коли служби запрацюють, відкрийте http://localhost/launchpad, щоб створити перший обліковий запис адміністратора.

   Ви повинні виконати bin/up перед командою bin/dev. Інакше можуть виникнути різноманітні проблеми з правами доступу.

За замовчуванням права адміністратора недоступні. Потрібно додати наведений нижче рядок до develop/dev.env. Після цього ви матимете доступ до панелі адміністратора.

ADMIN_PRIVILEGE_AVAILABLE=true

​

TeX Live

Для компіляції PDF потрібно зібрати образ TeX Live, який виконуватиме компіляцію всередині Docker:

docker build texlive -t texlive-full

Для компіляції на хості macOS може знадобитися перевизначити шлях до сокета Docker, створивши в цьому каталозі файл .env, що містить DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Також ви можете використовувати ayaka-notes/texlive-full, зокрема тег base, який є мінімальною версією texlive.

​

Розробка

Щоб не виконувати bin/build && bin/up після кожної зміни коду, можна запустити Overleaf Community Edition у режимі розробки, у якому служби автоматично оновлюються при змінах коду.

Для цього скористайтеся вбудованим скриптом bin/dev:

bin/dev

Це запустить усі служби за допомогою node --watch, який автоматично відстежує код і за потреби перезапускає служби.

Для підвищення продуктивності можна запустити в режимі розробки лише частину служб, передавши скрипту bin/dev їхній список, розділений пробілами:

bin/dev [service1] [service2] ... [serviceN]

Запуск служби web у режимі розробки оновлюватиме службу web лише при зміні коду бекенду. Щоб автоматично оновлювався й код фронтенду, обов’язково також запустіть у режимі розробки службу webpack.

Якщо служби не вказано, у режимі розробки буде запущено всі служби.

​

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

У режимі розробки більшість служб відкривають порт налагодження, до якого можна під’єднати налагоджувач, наприклад інспектор у Chrome Dev Tools або вбудований в IDE. У таблиці нижче наведено порт, відкритий на хост-машині для кожної служби:

Служба	Порт
web	9229
clsi	9230
chat	9231
contacts	9232
docstore	9233
document-updater	9234
filestore	9235
notifications	9236
real-time	9237
references	9238
history-v1	9239
project-history	9240
linked-url-proxy	9241

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

Після додавання запису служба з’явиться як Remote Target, яку можна інспектувати та налагоджувати.

​

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

У середовищі розробки Overleaf надає скрипт bin/logs, однак для нього потрібно встановити деякі залежності:

sudo npm install -g bunyan
# Or sudo apt install node-bunyan 

Або можна виконати безпосередньо:

docker compose logs -f [service name]

​

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

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