> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/overleaf/overleaf/tree).
* Mã nguồn của Overleaf-CEP có trên [GitHub Yu-i-i/Overleaf](https://github.com/yu-i-i/overleaf-cep).
* Overleaf Pro Edition có trên [GitHub Ayaka-notes/overleaf-pro](https://github.com/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.

<Info>
  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.
</Info>

Đồ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](https://docs.docker.com/engine/install/ubuntu/). 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:

* [x] Một máy chủ/máy tính mạnh để phát triển
* [x] Một bản Ubuntu LTS mới và ổn định (ví dụ Ubuntu 24.04)
* [x] 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.

<Steps>
  <Step title="Tải mã nguồn">
    Trước hết, hãy clone kho mã:

    ```bash title="bash" theme={null}
    git clone https://github.com/ayaka-notes/overleaf-pro.git
    cd overleaf-pro
    ```
  </Step>

  <Step title="Đồng bộ `package-lock.json`">
    Vì Overleaf được phát triển trong một [kho mã nội bộ](http://github.com/overleaf/internal), 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 title="bash" theme={null}
    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 <strong>từ thư mục gốc của kho mã Overleaf:</strong>

    ```bash title="bash" theme={null}
    docker run --rm \
      -v "$(pwd)":/workspace \
      -w /workspace \
      node:22.18.0 \
      npm install --package-lock-only --ignore-scripts
    ```
  </Step>

  <Step title="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 title="bash" theme={null}
    cd ./develop
    bin/build
    ```

    <Info>
      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`.
    </Info>
  </Step>

  <Step title="Khởi động tất cả microservice">
    Sau đó khởi động các dịch vụ:

    ```bash title="bash" theme={null}
    bin/up
    ```

    Khi các dịch vụ đã chạy, hãy mở [http://localhost/launchpad](http://localhost/launchpad) để tạo tài khoản quản trị viên đầu tiên.

    <Danger>
      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.
    </Danger>
  </Step>
</Steps>

<Info>
  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).

  ```text theme={null}
  ADMIN_PRIVILEGE_AVAILABLE=true
  ```
</Info>

### 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:

```text theme={null}
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](https://github.com/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:

```text theme={null}
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`:

```text theme={null}
bin/dev [service1] [service2] ... [serviceN]
```

<Info>
  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*.
</Info>

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:

```bash theme={null}
sudo npm install -g bunyan
# Or sudo apt install node-bunyan 
```

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

```text theme={null}
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](/vi/dev/environment/setup-develop-tools) để bổ sung một số công cụ gỡ lỗi cho quá trình phát triển Overleaf của mình.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.