Chuyển đến nội dung chính

Đ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. Để thiết lập môi trường phát triển Overleaf, bạn sẽ cần một máy chủ mạnh; khuyến nghị cấu hình tối thiểu 8 lõi và 16GB RAM, vì bạn sẽ cần chạy đồng thời hơn 20 container.
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.
Đồng thời, với tư cách là nhà phát triển, chúng tôi tin rằng bạn đã quen thuộc với việc cài đặt Docker. Chúng tôi đặc biệt khuyên bạn nên sử dụng một bản Ubuntu LTS mới và ổn định (ví dụ Ubuntu 24.04 trong giai đoạn 2025–2026) cùng phiên bản Docker mới nhất để phát triển, vì điều này giúp giảm khả năng gặp phải các lỗi không mong muốn. Tóm lại, bạn sẽ cầ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ục develop 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 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
Lệnh này cần 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ụ:
bash
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 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.
Volume cục bộ và RustFS là hai kho lưu trữ riêng biệt: một dự án tạo với S3_ENABLED=true sẽ không có lịch sử hay tệp nhị phân sau khi chuyển sang false, và ngược lại. Để sao chép tệp của một môi trường đã chạy trước khi có S3_ENABLED vào RustFS, hãy làm theo “Moving existing data into RustFS” trong develop/README.md.

Cổng

Trang web, bảng điều khiển RustFS và Hoppscotch lắng nghe trên 127.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:
Xem Thiết lập Sandbox Compiles để biết chi tiết.
Một dự án được tạo khi SANDBOXED_COMPILES đang tắt sẽ không có image TeX Live. Dự án vẫn biên dịch bằng image mặc định, nhưng việc nhảy giữa mã và PDF thất bại với thông báo “That didn’t work. Recompile and try again.” Hãy gán cho các dự án đó image của TEX_LIVE_DOCKER_IMAGE một lần; nếu không có --commit, script chỉ hiển thị những gì nó sẽ thay đổi:
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:
Để biên dịch trên máy chủ macOS, bạn có thể cần ghi đè đường dẫn tới socket Docker bằng cách tạo tệp .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ạy bin/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:
Lệnh này sẽ khởi động tất cả các dịch vụ bằng 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.
Nếu không chỉ định dịch vụ nào, tất cả các dịch vụ sẽ khởi động ở chế độ phát triển. Sau khi thêm bản dịch hoặc đổi nhánh, hãy chạy 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ên 127.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

Script bin/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.
Hoặc, bạn có thể chạy trực tiếp:
Hãy dùng 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.

Công cụ khác

Khi đã hoàn tất mọi thứ, bạn có thể tham khảo phần tiếp theo để bổ sung một số công cụ gỡ lỗi cho quá trình phát triển Overleaf của mình.
Lần sửa đổi cuối 20 tháng 11, 2026