Konfiguracja środowiska deweloperskiego (lokalnie)

Skonfiguruj środowisko deweloperskie na lokalnym serwerze lub komputerze stacjonarnym.

​

Wymagania wstępne

Overleaf to typowy projekt open source oparty na architekturze mikroserwisów, w którym wszystkie usługi działają w Dockerze.

• Kod źródłowy oficjalnej edycji Community Edition znajduje się na GitHub Overleaf Official.
• Kod źródłowy Overleaf-CEP jest dostępny na GitHub Yu-i-i/Overleaf.
• Overleaf Pro Edition jest dostępna na GitHub Ayaka-notes/overleaf-pro.

Do skonfigurowania środowiska deweloperskiego Overleaf potrzebny jest wydajny serwer; zalecana jest konfiguracja z co najmniej 8 rdzeniami i 16 GB RAM, ponieważ jednocześnie trzeba uruchomić ponad 20 kontenerów.

Ponieważ serwery z 8 lub więcej rdzeniami CPU są zazwyczaj drogie, zdecydowanie zalecamy prowadzenie prac deweloperskich na komputerze lokalnym.

Zakładamy też, że jako programista znasz już instalację Dockera. Do prac deweloperskich zdecydowanie zalecamy używanie aktualnej i stabilnej wersji Ubuntu LTS (np. Ubuntu 24.04 w latach 2025–2026) oraz najnowszej wersji Dockera, co zmniejsza ryzyko wystąpienia nieoczekiwanych błędów.

Podsumowując, będziesz potrzebować:

• Wydajnego serwera/komputera stacjonarnego do prac deweloperskich
• Aktualnej i stabilnej wersji Ubuntu LTS (np. Ubuntu 24.04)
• Środowiska Docker i Git

​

Samouczek konfiguracji

Jako przykładu użyjemy tutaj overleaf-cep, aby pokazać, jak skonfigurować środowisko deweloperskie Overleaf.

1. Pobierz kod źródłowy

   Najpierw sklonuj repozytorium:

   bash

   git clone https://github.com/ayaka-notes/overleaf-pro.git
   cd overleaf-pro
   
2. Zsynchronizuj package-lock.json

   Ponieważ Overleaf jest rozwijany w wewnętrznym repozytorium, plik package-lock.json bardzo często traci synchronizację z powodu różnych kwestii związanych z procesem rozwoju. Aby go zsynchronizować, należy uruchomić poniższe polecenie (jeśli masz lokalne środowisko nodejs).

   bash

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

   Jeśli nie masz zainstalowanego nodejs, nie martw się — możesz użyć bezpośrednio docker, aby uruchomić to samo polecenie. Uruchom je z katalogu głównego repozytorium Overleaf:

   bash

   docker run --rm \
     -v "$(pwd)":/workspace \
     -w /workspace \
     node:22.18.0 \
     npm install --package-lock-only --ignore-scripts
   
3. Zbuduj obraz deweloperski

   Overleaf udostępnia dedykowany katalog /develop na skrypty deweloperskie. Wystarczy zbudować usługi:

   bash

   cd ./develop
   bin/build
   

   Jeśli Dockerowi zabraknie pamięci RAM podczas równoległego budowania usług, utwórz w tym katalogu plik .env zawierający COMPOSE_PARALLEL_LIMIT=1.

4. Uruchom wszystkie mikroserwisy

   Następnie uruchom usługi:

   bash

   bin/up
   

   Gdy usługi będą działać, otwórz http://localhost/launchpad, aby utworzyć pierwsze konto administratora.

   Musisz uruchomić bin/up przed uruchomieniem polecenia bin/dev. W przeciwnym razie możesz napotkać szereg problemów z uprawnieniami.

Domyślnie uprawnienia administratora nie są dostępne. Musisz dodać poniższy wpis do develop/dev.env. Następnie uzyskasz dostęp do panelu administratora.

ADMIN_PRIVILEGE_AVAILABLE=true

​

TeX Live

Kompilacja PDF wymaga zbudowania obrazu TeX Live, który obsługuje kompilację wewnątrz Dockera:

docker build texlive -t texlive-full

Aby kompilować na hoście macOS, może być konieczne nadpisanie ścieżki do gniazda Dockera przez utworzenie w tym katalogu pliku .env zawierającego DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Możesz także użyć ayaka-notes/texlive-full, wybierając tag base, który jest minimalną wersją texlive.

​

Rozwój

Aby uniknąć uruchamiania bin/build && bin/up po każdej zmianie kodu, możesz uruchomić Overleaf Community Edition w trybie deweloperskim, w którym usługi automatycznie aktualizują się po zmianach w kodzie.

W tym celu użyj dołączonego skryptu bin/dev:

bin/dev

Spowoduje to uruchomienie wszystkich usług za pomocą node --watch, który automatycznie monitoruje kod i w razie potrzeby restartuje usługi.

Aby poprawić wydajność, możesz uruchomić w trybie deweloperskim tylko część usług, przekazując do skryptu bin/dev listę rozdzieloną spacjami:

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

Uruchomienie usługi web w trybie deweloperskim spowoduje aktualizację usługi web tylko przy zmianach kodu backendu. Aby automatycznie aktualizować również kod frontendu, uruchom także usługę webpack w trybie deweloperskim.

Jeśli nie podasz nazw usług, wszystkie usługi zostaną uruchomione w trybie deweloperskim.

​

Debugowanie

W trybie deweloperskim większość usług udostępnia port debugowania, do którego można podłączyć debugger, np. inspektor w Chrome Dev Tools lub debugger zintegrowany z IDE. Poniższa tabela przedstawia porty udostępniane na maszynie hosta dla poszczególnych usług:

Usługa	Port
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

Aby podłączyć się do usługi za pomocą zdalnego debugowania Chrome, przejdź do chrome://inspect/ i upewnij się, że opcja Discover network targets jest zaznaczona. Następnie kliknij Configure… i dodaj wpis localhost:[service port] dla każdej usługi, do której chcesz podłączyć debugger.

Po dodaniu wpisu usługa pojawi się jako Remote Target, który można inspekcjonować i debugować.

​

Logowanie

W środowisku deweloperskim Overleaf udostępnia skrypt bin/logs, jednak wymaga on zainstalowania pewnej zależności:

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

Możesz też uruchomić bezpośrednio:

docker compose logs -f [service name]

​

Inne narzędzia

Po wykonaniu wszystkich kroków możesz zajrzeć do następnej sekcji, aby dodać narzędzia do debugowania do swojego środowiska deweloperskiego Overleaf.