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.
- Ayakaleaf Pro jest dostępny na GitHub ayaka-notes/ayakaleaf-pro.
Ponieważ serwery z 8 lub więcej rdzeniami CPU są zazwyczaj drogie, zdecydowanie zalecamy prowadzenie prac deweloperskich na komputerze lokalnym.
- Wydajnego serwera/komputera stacjonarnego do prac deweloperskich
- Aktualnej i stabilnej wersji Ubuntu LTS (np. Ubuntu 24.04)
- Środowiska Docker i Git
Samouczek konfiguracji
Tutaj na przykładzie Ayakaleaf Pro pokazujemy, jak skonfigurować środowisko deweloperskie Overleaf. Wszystkie poniższe polecenia są uruchamiane w katalogudevelop, chyba że zaznaczono inaczej.
1
Pobierz kod źródłowy
Najpierw sklonuj repozytorium:
bash
2
Synchronizacja yarn.lock
Repozytorium używa Yarn 4 (
packageManager w głównym package.json), a jego yarn.lock może być niezsynchronizowany z plikami package.json. Zsynchronizuj go po pierwszym sklonowaniu i po każdej zmianie w package.json:bash
bin/sync uruchamia yarn install --mode=update-lockfile w kontenerze node:24.18.1, więc nie potrzebujesz Node.js na hoście. Nie commituj zmienionego yarn.lock.3
Zbuduj obraz deweloperski
Zbuduj usługi:
bash
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
Nałożenie tłumaczeń
Moduły Ayakaleaf Pro przechowują swoje tłumaczenia w Wymaga
services/web/locales/locales_patches/, których nie zawierają zatwierdzone pliki lokalizacji. Nałóż je raz przed pierwszym uruchomieniem, w przeciwnym razie strony tych modułów pokażą klucze takie jak about_to_permanently_delete_accounts zamiast tekstu:bash
jq na hoście. Uruchom go ponownie po dodaniu tłumaczenia lub zmianie gałęzi, zobacz Aktualizacja tłumaczeń i18n.5
Uruchom wszystkie mikroserwisy
Następnie uruchom usługi:Gdy usługi będą działać, otwórz http://localhost/launchpad, aby utworzyć pierwsze konto administratora. Dodaj port, jeśli zmieniłeś
bash
OVERLEAF_PORT (zobacz niżej).LDAP jest domyślnie włączony (
LDAP_ENABLED=true w dev.rc). Launchpad pokazuje wtedy formularz administratora LDAP: pyta tylko o adres e-mail, a ten administrator loguje się potem przez LDAP, na przykład jako professor / professor (professor@planetexpress.com). Użytkownicy testowi są wymienieni w develop/authentication/README.md. Ustaw LDAP_ENABLED=false i SAML_ENABLED=false, aby zamiast tego utworzyć lokalnego administratora z hasłem.develop/dev.env ustawia już ADMIN_PRIVILEGE_AVAILABLE=true, więc administratorzy mogą otworzyć panel administracyjny bez dodatkowej konfiguracji.Konfiguracja (dev.rc)
develop/dev.rc, obok dev.env, zawiera przełączniki środowiska deweloperskiego, podobnie jak overleaf.rc w Overleaf Toolkit. Zmień wartość i ponownie uruchom bin/dev, aby ją zastosować; wyłączona funkcja zatrzymuje też swoje kontenery.
Każda funkcja trzyma swój
docker-compose.yml i inne pliki we własnym folderze: authentication/ldap, authentication/saml, mail, s3, hoppscotch i grafana. Funkcja, która potrzebuje ustawienia web bez zmiennej środowiskowej, montuje plik w /etc/overleaf/settings.d/, a develop/settings.dev-env.cjs scala je wszystkie. Wszystkie skrypty bin/* działają przez bin/docker-compose, który dodaje pliki włączonych funkcji. Używaj bin/docker-compose zamiast docker compose, gdy potrzebujesz własnego polecenia compose.
Porty
Witryna, konsola RustFS i Hoppscotch nasłuchują na127.0.0.1 hosta; na zdalnej maszynie najpierw przekieruj ich porty, na przykład ssh -L 9001:localhost:9001 <host>. Witryna używa OVERLEAF_PORT z dev.rc, więc dodaj port do poniższych adresów, jeśli go zmieniłeś.
Mailpit, Grafana, Mongo Express i RedisInsight są udostępniane przez witrynę pod własnymi ścieżkami przez webpack-dev-server, więc nie potrzebują własnych portów. Po zalogowaniu menu Dev tools na pasku nawigacji witryny prowadzi do nich; strona, której funkcja jest wyłączona w
dev.rc, jest pomijana. Konfiguracja narzędzi deweloperskich pokazuje, do czego służy każde z nich.
API S3 (port 9000) i SMTP (port 1025) są dostępne tylko w sieci Dockera. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540) i git-bridge (8000) są publikowane tylko na 127.0.0.1 hosta.
TeX Live
Kompilacje w piaskownicy są domyślnie włączone:develop/dev.env ustawia SANDBOXED_COMPILES=true oraz obrazy ghcr.io/ayaka-notes/texlive-full:2026.1 i ghcr.io/ayaka-notes/texlive-full:2025.1. clsi nie pobiera obrazów samodzielnie, więc pobierz je raz:
dev.env włącza też konwersje Pandoc z PANDOC_IMAGE=overleaf-pandoc:local. Zbuduj ten obraz raz, z katalogu głównego repozytorium:
develop pliku .env zawierającego DOCKER_SOCKET_PATH=/var/run/docker.sock.raw
Rozwój
Aby uniknąć uruchamianiabin/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:
node --watch, który automatycznie monitoruje kod i w razie potrzeby restartuje usługi. Uruchom go ponownie po zmianie dev.rc.
Aby poprawić wydajność, możesz uruchomić w trybie deweloperskim tylko część usług, przekazując do skryptu bin/dev listę rozdzieloną spacjami:
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.bin/i18n, zobacz Aktualizacja tłumaczeń i18n.
Debugowanie
W trybie deweloperskim większość usług udostępnia port debugowania, do którego możesz podłączyć debuger, na przykład inspektor w Chrome Dev Tools lub debuger zintegrowany z IDE. Poniższa tabela pokazuje port udostępniony na127.0.0.1 maszyny hosta dla każdej usługi:
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
Skryptbin/logs śledzi logi i formatuje je za pomocą bunyan. Potrzebuje też ggrep, czyli nazwy GNU grep zainstalowanego przez Homebrew w macOS; Ubuntu nie ma polecenia ggrep.
bin/docker-compose zamiast docker compose, aby znajdowane były także usługi funkcji z dev.rc (mailpit, rustfs, ldap, saml, hoppscotch oraz grafana z Prometheusem, Loki i eksporterami).
Przy GRAFANA_ENABLED=true logi każdego kontenera są też w Grafanie, gdzie można je filtrować według usługi, poziomu i tekstu, zobacz Konfiguracja narzędzi deweloperskich.

