Przejdź do głównej treści

Wymagania wstępne

Overleaf to typowy projekt open source oparty na architekturze mikroserwisów, w którym wszystkie usługi działają w Dockerze. 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

Tutaj na przykładzie Ayakaleaf Pro pokazujemy, jak skonfigurować środowisko deweloperskie Overleaf. Wszystkie poniższe polecenia są uruchamiane w katalogu develop, 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 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
Wymaga 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:
bash
Gdy usługi będą działać, otwórz http://localhost/launchpad, aby utworzyć pierwsze konto administratora. Dodaj port, jeśli zmieniłeś 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.
Lokalne woluminy i RustFS to osobne magazyny: projekt utworzony przy S3_ENABLED=true nie ma historii ani plików binarnych po przełączeniu na false, i odwrotnie. Aby skopiować do RustFS pliki środowiska działającego przed pojawieniem się S3_ENABLED, postępuj zgodnie z „Moving existing data into RustFS” w develop/README.md.

Porty

Witryna, konsola RustFS i Hoppscotch nasłuchują na 127.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:
Szczegóły znajdziesz w Konfiguracja Sandbox Compiles.
Projekt utworzony, gdy SANDBOXED_COMPILES był wyłączony, nie ma obrazu TeX Live. Nadal kompiluje się z domyślnym obrazem, ale przechodzenie między kodem a PDF kończy się błędem „That didn’t work. Recompile and try again.” Przypisz takim projektom raz obraz z TEX_LIVE_DOCKER_IMAGE; bez --commit skrypt tylko pokazuje, co by zmienił:
dev.env włącza też konwersje Pandoc z PANDOC_IMAGE=overleaf-pandoc:local. Zbuduj ten obraz raz, z katalogu głównego repozytorium:
Aby kompilować na hoście macOS, może być konieczne nadpisanie ścieżki do gniazda Dockera przez utworzenie w katalogu develop pliku .env zawierającego DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

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:
Spowoduje to uruchomienie wszystkich usług za pomocą 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.
Jeśli nie podasz nazw usług, wszystkie usługi zostaną uruchomione w trybie deweloperskim. Po dodaniu tłumaczenia lub zmianie gałęzi uruchom 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 na 127.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

Skrypt bin/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.
Możesz też uruchomić bezpośrednio:
Używaj 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.

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.
Ostatnia modyfikacja 20 listopada 2026