Điều kiện tiên quyết
Overleaf là một dự án mã nguồn mở điển hình theo kiến trúc microservice, với tất cả các dịch vụ đều chạy trong Docker.- Mã nguồn Community Edition chính thức có trên GitHub Overleaf Official.
- Mã nguồn của Overleaf-CEP có trên GitHub Yu-i-i/Overleaf.
- Ayakaleaf Pro có trên GitHub ayaka-notes/ayakaleaf-pro.
Vì các máy chủ có từ 8 lõi CPU trở lên thường khá đắt, chúng tôi đặc biệt khuyến nghị bạn sử dụng máy tính cục bộ để phát triển.
- Một máy chủ/máy tính mạnh để phát triển
- Một bản Ubuntu LTS mới và ổn định (ví dụ Ubuntu 24.04)
- Môi trường Docker và Git
Hướng dẫn cấu hình
Ở đây, chúng tôi dùng Ayakaleaf Pro để minh họa cách thiết lập môi trường phát triển Overleaf. Mọi lệnh bên dưới đều chạy trong thư mụcdevelop trừ khi có ghi chú khác.
1
Tải mã nguồn
Trước hết, hãy clone kho mã:
bash
2
Đồng bộ yarn.lock
Repository dùng Yarn 4 (
packageManager trong package.json ở thư mục gốc), và yarn.lock có thể không đồng bộ với các tệp package.json. Hãy đồng bộ sau lần clone đầu tiên và sau mỗi thay đổi package.json:bash
bin/sync chạy yarn install --mode=update-lockfile trong container node:24.18.1, nên bạn không cần Node.js trên máy chủ. Đừng commit yarn.lock đã thay đổi.3
Build image phát triển
Build các dịch vụ:
bash
Nếu Docker hết RAM khi build song song các dịch vụ, hãy tạo một tệp
.env trong thư mục này chứa COMPOSE_PARALLEL_LIMIT=1.4
Áp dụng bản dịch
Các mô-đun của Ayakaleaf Pro giữ bản dịch trong Lệnh này cần
services/web/locales/locales_patches/, vốn không có trong các tệp locale đã commit. Hãy áp dụng chúng một lần trước lần khởi động đầu tiên, nếu không các trang của những mô-đun này sẽ hiển thị khóa như about_to_permanently_delete_accounts thay vì văn bản:bash
jq trên máy chủ. Chạy lại sau khi thêm bản dịch hoặc đổi nhánh, xem Cập nhật bản dịch i18n.5
Khởi động tất cả microservice
Sau đó khởi động các dịch vụ:Khi các dịch vụ đã chạy, hãy mở http://localhost/launchpad để tạo tài khoản quản trị viên đầu tiên. Thêm cổng nếu bạn đã thay đổi
bash
OVERLEAF_PORT (xem bên dưới).LDAP được bật theo mặc định (
LDAP_ENABLED=true trong dev.rc). Khi đó launchpad hiển thị biểu mẫu quản trị viên LDAP: nó chỉ hỏi email, và quản trị viên đó sau này đăng nhập qua LDAP, ví dụ với professor / professor (professor@planetexpress.com). Danh sách người dùng thử nằm trong develop/authentication/README.md. Đặt LDAP_ENABLED=false và SAML_ENABLED=false để tạo một quản trị viên cục bộ có mật khẩu thay thế.develop/dev.env đã đặt sẵn ADMIN_PRIVILEGE_AVAILABLE=true, nên quản trị viên có thể mở bảng quản trị mà không cần thiết lập thêm.Cấu hình (dev.rc)
develop/dev.rc, nằm cạnh dev.env, chứa các công tắc của môi trường phát triển, giống overleaf.rc trong Overleaf Toolkit. Thay đổi một giá trị rồi chạy lại bin/dev để áp dụng; tính năng bị tắt cũng dừng các container của nó.
Mỗi tính năng giữ
docker-compose.yml và các tệp khác trong thư mục riêng: authentication/ldap, authentication/saml, mail, s3, hoppscotch và grafana. Tính năng nào cần một cài đặt của web không có biến môi trường sẽ gắn một tệp vào /etc/overleaf/settings.d/, và develop/settings.dev-env.cjs hợp nhất tất cả. Mọi script bin/* đều đi qua bin/docker-compose, công cụ thêm các tệp của những tính năng đang bật. Hãy gọi bin/docker-compose thay vì docker compose khi bạn tự cần một lệnh compose.
Cổng
Trang web, bảng điều khiển RustFS và Hoppscotch lắng nghe trên127.0.0.1 của máy chủ; trên máy từ xa, hãy chuyển tiếp cổng của chúng trước, ví dụ ssh -L 9001:localhost:9001 <host>. Trang web dùng OVERLEAF_PORT từ dev.rc, vì vậy hãy thêm cổng vào các địa chỉ bên dưới nếu bạn đã thay đổi nó.
Mailpit, Grafana, Mongo Express và RedisInsight được trang web phục vụ trên đường dẫn riêng thông qua webpack-dev-server, nên không cần cổng riêng. Khi bạn đã đăng nhập, menu Dev tools trên thanh điều hướng của trang web liên kết tới chúng; trang nào có tính năng bị tắt trong
dev.rc sẽ bị bỏ qua. Thiết lập công cụ phát triển cho biết mỗi công cụ làm gì.
S3 API (cổng 9000) và SMTP (cổng 1025) chỉ truy cập được bên trong mạng Docker. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540) và git-bridge (8000) chỉ được công bố trên 127.0.0.1 của máy chủ.
TeX Live
Biên dịch trong sandbox được bật theo mặc định:develop/dev.env đặt SANDBOXED_COMPILES=true cùng các image ghcr.io/ayaka-notes/texlive-full:2026.1 và ghcr.io/ayaka-notes/texlive-full:2025.1. clsi không tự kéo image, vì vậy hãy kéo chúng một lần:
dev.env cũng bật chuyển đổi Pandoc với PANDOC_IMAGE=overleaf-pandoc:local. Hãy build image đó một lần từ thư mục gốc của repository:
.env trong thư mục develop chứa DOCKER_SOCKET_PATH=/var/run/docker.sock.raw
Phát triển
Để tránh phải chạybin/build && bin/up sau mỗi lần thay đổi mã, bạn có thể chạy Overleaf Community Edition ở chế độ phát triển, trong đó các dịch vụ sẽ tự động cập nhật khi mã thay đổi.
Để làm điều này, hãy dùng script bin/dev đi kèm:
node --watch, tự động theo dõi mã và khởi động lại các dịch vụ khi cần. Chạy lại lệnh này sau khi thay đổi dev.rc.
Để cải thiện hiệu năng, bạn có thể chỉ khởi động một số dịch vụ ở chế độ phát triển bằng cách truyền danh sách tên dịch vụ, phân tách bằng dấu cách, cho script bin/dev:
Khởi động dịch vụ
web ở chế độ phát triển sẽ chỉ cập nhật dịch vụ web khi mã backend thay đổi. Để tự động cập nhật cả mã frontend, hãy đảm bảo cũng khởi động dịch vụ webpack ở chế độ phát triển.bin/i18n, xem Cập nhật bản dịch i18n.
Gỡ lỗi
Khi chạy ở chế độ phát triển, hầu hết các dịch vụ mở một cổng gỡ lỗi để bạn gắn trình gỡ lỗi, chẳng hạn trình kiểm tra trong Chrome Dev Tools hoặc trình gỡ lỗi tích hợp trong IDE. Bảng sau cho biết cổng được mở trên127.0.0.1 của máy chủ cho từng dịch vụ:
Để gắn vào một dịch vụ bằng tính năng remote debugging của Chrome, hãy truy cập chrome://inspect/ và đảm bảo đã chọn Discover network targets. Tiếp theo, nhấp Configure… và thêm mục
localhost:[service port] cho mỗi dịch vụ mà bạn muốn gắn trình gỡ lỗi.
Sau khi thêm mục, dịch vụ sẽ xuất hiện dưới dạng Remote Target để bạn có thể kiểm tra và gỡ lỗi.
Ghi log
Scriptbin/logs theo dõi nhật ký và định dạng chúng bằng bunyan. Nó cũng cần ggrep, là tên của GNU grep khi cài bằng Homebrew trên macOS; Ubuntu không có lệnh ggrep.
bin/docker-compose thay vì docker compose, để các dịch vụ của những tính năng trong dev.rc (mailpit, rustfs, ldap, saml, hoppscotch và grafana cùng Prometheus, Loki và các exporter) cũng được tìm thấy.
Với GRAFANA_ENABLED=true, nhật ký của mọi container cũng có trong Grafana, nơi có thể lọc theo dịch vụ, mức độ và văn bản, xem Thiết lập công cụ phát triển.

