Thiết lập môi trường phát triển (cục bộ)

Thiết lập môi trường phát triển trên máy chủ hoặc máy tính cá nhân của bạn.

​

Đ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.
• Overleaf Pro Edition có trên GitHub Ayaka-notes/overleaf-pro.

Để 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 sẽ dùng overleaf-cep làm ví dụ để minh họa cách cấu hình môi trường phát triển Overleaf.

1. Tải mã nguồn

   Trước hết, hãy clone kho mã:

   bash

   git clone https://github.com/ayaka-notes/overleaf-pro.git
   cd overleaf-pro
   
2. Đồng bộ package-lock.json

   Vì Overleaf được phát triển trong một kho mã nội bộ, tệp package-lock.json rất có thể bị mất đồng bộ do một số vấn đề trong quá trình phát triển. Chúng ta cần chạy lệnh sau để đồng bộ nó (nếu bạn có môi trường nodejs cục bộ).

   bash

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

   Nếu bạn chưa cài nodejs, đừng lo, bạn có thể dùng trực tiếp docker để chạy cùng lệnh đó. Hãy chạy từ thư mục gốc của kho mã Overleaf:

   bash

   docker run --rm \
     -v "$(pwd)":/workspace \
     -w /workspace \
     node:22.18.0 \
     npm install --package-lock-only --ignore-scripts
   
3. Build image phát triển

   Overleaf cung cấp một thư mục riêng /develop để chứa các script phát triển. Chỉ cần build các dịch vụ:

   bash

   cd ./develop
   bin/build
   

   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. Khởi động tất cả microservice

   Sau đó khởi động các dịch vụ:

   bash

   bin/up
   

   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.

   Bạn phải chạy bin/up trước khi chạy lệnh bin/dev. Nếu không, bạn có thể gặp hàng loạt vấn đề về quyền truy cập.

Theo mặc định, quyền quản trị không khả dụng. Bạn cần thêm dòng sau vào develop/dev.env. Sau đó, bạn có thể truy cập bảng quản trị (Admin panel).

ADMIN_PRIVILEGE_AVAILABLE=true

​

TeX Live

Để biên dịch PDF, bạn cần build một image TeX Live để xử lý việc biên dịch bên trong Docker:

docker build texlive -t texlive-full

Để biên dịch trên máy chủ macOS, bạn có thể cần ghi đè đường dẫn tới Docker socket bằng cách tạo một tệp .env trong thư mục này, chứa DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Ngoài ra, bạn cũng có thể sử dụng ayaka-notes/texlive-full, và có thể dùng tag base, đây là phiên bản texlive tối giản.

​

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:

bin/dev

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.

Để 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:

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

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.

​

Gỡ lỗi

Khi chạy ở chế độ phát triển, hầu hết các dịch vụ đều mở một cổng gỡ lỗi để bạn có thể gắn trình gỡ lỗi, chẳng hạn như inspector trong Chrome Dev Tools hoặc trình gỡ lỗi tích hợp trong IDE. Bảng sau liệt kê cổng được mở trên máy chủ host cho từng dịch vụ:

Dịch vụ	Cổng
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

Để 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

Trong môi trường phát triển, Overleaf cung cấp script bin/logs, tuy nhiên bạn cần cài đặt một số phụ thuộc:

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

Hoặc, bạn có thể chạy trực tiếp:

docker compose logs -f [service name]

​

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.