# Chạy một máy chủ cộng tác

Oleafly Server lưu trữ những gì, cần những gì, cách cài đặt nó bằng một lệnh hoặc chạy nó với Docker Compose, Coolify, Render, Railway hay một dịch vụ Linux thông thường, rồi trở thành quản trị viên đầu tiên của nó.

Oleafly Server là máy chủ cộng tác đứng sau tính năng cộng tác trực tiếp. Phòng thí nghiệm, bộ phận hay tổ chức của bạn tự chạy nó trên máy của mình hoặc trong tài khoản đám mây riêng của mình. Mọi người thêm nó trong Oleafly và đăng nhập bằng một tài khoản họ đã có, chẳng hạn GitHub hoặc đăng nhập của trường đại học. Khi ai đó chia sẻ một dự án trên máy chủ, những người họ thêm vào sẽ nhận được một bản sao đầy đủ luôn được đồng bộ trong khi họ chỉnh sửa. Khi bật [quyền truy cập qua trình duyệt](/docs/collaboration/server-access/#browser-access), họ cũng có thể mở dự án trong trình duyệt web.

Tài liệu này dành cho người vận hành máy chủ cho một phòng thí nghiệm, một khóa học hoặc một nhóm đồng tác giả. Bạn cần thành thạo việc dùng terminal. Một số cách thiết lập còn yêu cầu bạn chỉnh sửa một tệp cấu hình. Bạn không cần viết mã.

Để rà soát bảo mật, hãy đọc [Bảo mật máy chủ](/security/). Tài liệu đó đề cập việc tự triển khai, đăng nhập, khóa thiết bị, các thay đổi có chữ ký, nhật ký bảo mật và truy cập, cùng image container kèm danh mục phần mềm của nó.

## Máy chủ lưu trữ những gì

Máy chủ lưu mọi thứ trong một thư mục dữ liệu, do `OLEAFLY_DATA_DIR` chỉ định:

- **Tài khoản**: tên hiển thị của từng thành viên, địa chỉ ảnh đại diện, các địa chỉ email đã xác minh, cùng ID người dùng và tên đăng nhập của họ tại nhà cung cấp đăng nhập. Máy chủ không bao giờ nhìn thấy hay lưu trữ mật khẩu.
- **Thiết bị**: từng máy tính đã đăng nhập, kèm tên, hệ điều hành, khóa công khai và thời điểm nó được nhìn thấy lần cuối. Mã thông báo đăng nhập chỉ được lưu dưới dạng băm.
- **Nhật ký bảo mật**: các lần đăng nhập và đăng nhập bị từ chối, thiết bị được thêm vào và đăng xuất, các thay đổi về thành viên, vai trò và cài đặt, dự án được chia sẻ, lưu trữ và khôi phục, thay đổi về việc ai có thể mở một dự án, và các lời mời khách. Mỗi mục ghi có thời gian và địa chỉ IP.
- **Cài đặt máy chủ** mà các quản trị viên thay đổi trong Oleafly.
- **Nhật ký truy cập dự án**, cho những dự án mà chủ sở hữu bật nó lên: ai đã mở dự án, tham gia vào nó hay tải xuống một bản sao, kèm tên thiết bị và thời gian. Chỉ chủ sở hữu của dự án mới đọc được nó.
- **Lời mời khách**: địa chỉ email được mời, dự án, vai trò và người gửi lời mời.
- **Dự án dùng chung**: mọi tệp và toàn bộ lịch sử thay đổi, cùng các bình luận, đề xuất, tin nhắn trò chuyện và tên phiên bản thuộc về chúng.
- **PDF đã biên dịch**: với mỗi dự án dùng chung, PDF mới nhất và tệp SyncTeX của nó mà ứng dụng của một chủ sở hữu hoặc người chỉnh sửa đã gửi lên sau một lần biên dịch thành công, kèm người biên dịch và thời điểm biên dịch.

Các mục trong nhật ký bảo mật và nhật ký truy cập, cùng các lời mời khách đã được trả lời hoặc đã hết hạn, bị xóa sau `OLEAFLY_SECURITY_LOG_DAYS` ngày, mặc định là 365 ngày. Những tệp mà một dự án không còn dùng, chẳng hạn bản sao cũ của một hình ảnh đã bị thay thế, bị xóa 30 ngày sau lần cuối dự án dùng đến chúng. Mỗi PDF đã biên dịch thay thế bản trước nó. Khi một chủ sở hữu ngừng chia sẻ một dự án, máy chủ giữ nó ở chế độ chỉ đọc trong `OLEAFLY_ARCHIVE_DAYS` ngày, mặc định là 30 ngày, rồi xóa nó. Trong khoảng thời gian đó, chỉ chủ sở hữu và các quản trị viên trong dự án mới tải xuống được.

### Ai có thể đọc các dự án

Các dự án không được mã hóa trên máy chủ. Bất kỳ ai đọc được thư mục dữ liệu, đĩa của máy hoặc bản sao lưu của bạn đều đọc được mọi dự án được lưu ở đó. Điều đó bao gồm cả người vận hành máy và công ty lưu trữ nó.

Bên trong Oleafly, các quy tắc chặt chẽ hơn. Không vai trò nào trên máy chủ, kể cả quản trị viên, có thể mở một dự án, trừ khi chủ sở hữu của dự án đó thêm họ vào. Nếu một dự án phải tránh xa những người vận hành máy chủ, hãy chạy một máy chủ riêng cho nó.

Máy của từng thành viên cũng giữ một bản sao đầy đủ của mỗi dự án được chia sẻ với họ. Hãy yêu cầu các thành viên bật mã hóa đĩa, chẳng hạn FileVault trên macOS, BitLocker trên Windows hoặc LUKS trên Linux.

## Những gì bạn cần

- **Một máy luôn bật.** Bất kỳ máy Linux nào cũng được, hoặc một tài khoản với dịch vụ lưu trữ như Render hay Railway. Một máy ảo nhỏ là đủ để bắt đầu. Hãy theo dõi bộ nhớ và đĩa của nó khi các dự án lớn dần. Máy chủ chạy trên x86-64 và ARM.
- **Một tên miền** cho máy chủ, chẳng hạn `collab.example.org`, với bản ghi DNS trỏ đến máy. Render và Railway cấp cho bạn một địa chỉ nếu bạn chưa có. Nếu máy không có địa chỉ công khai, hãy đọc [Khi không có địa chỉ công khai](#without-a-public-address).
- **Một cách để mọi người đăng nhập**: ít nhất một nhà cung cấp đăng nhập, chẳng hạn một ứng dụng GitHub OAuth hoặc đăng nhập của tổ chức bạn. Máy chủ sẽ không khởi động nếu thiếu nó. Một tài khoản email mà máy chủ có thể dùng để gửi thư là tùy chọn. Có nó, quản trị viên còn có thể cho phép mọi người đăng nhập bằng liên kết gửi qua email. Đọc [Đăng nhập và truy cập](/docs/collaboration/server-access/).

Mỗi bản phát hành được xuất bản dưới dạng một image container, `ghcr.io/oleafly/oleafly-server`. Trình cài đặt và các tệp Compose của nó nằm trên [trang phát hành Oleafly Server](https://github.com/Oleafly/oleafly-server/releases). Máy chủ dưới dạng một chương trình Linux đơn lẻ nằm trên [trang phát hành Oleafly](https://github.com/Oleafly/Oleafly/releases).

## Chọn cách chạy

| Tùy chọn | Khi nào dùng |
| --- | --- |
| [Một lệnh](#install-with-one-command) | Một máy Linux do bạn tự quản lý. Trình cài đặt dựng sẵn Docker, Caddy và HTTPS, và hỏi vài câu hỏi. Hãy bắt đầu từ đây nếu bạn chưa chắc chắn. |
| [Docker Compose thủ công](#docker-compose-by-hand) | Bạn muốn tự đặt và tự chỉnh từng tệp. |
| [Coolify](#coolify) | Bạn đã chạy một máy chủ Coolify. |
| [Render](#render) hoặc [Railway](#railway) | Bạn muốn trả tiền cho một dịch vụ lưu trữ hơn là tự quản lý một máy. |
| [Linux không dùng Docker](#linux-without-docker) | Một máy ảo của trường đại học nơi bạn không thể dùng Docker. |

Máy chủ đọc cài đặt của nó từ các biến môi trường. [Lưu trữ, sao lưu và giới hạn](/docs/collaboration/server-operations/#settings) liệt kê tất cả chúng.

## Cài đặt bằng một lệnh

Trên một máy Linux do bạn tự quản lý, trình cài đặt dựng mọi thứ và chỉ hỏi những gì nó cần biết.

Trước khi chạy, hãy kiểm tra rằng:

- Máy chạy Linux trên x86-64 hoặc ARM, chẳng hạn Ubuntu 24.04 hoặc Debian 13, và bạn có thể dùng `sudo` trên đó.
- Không có gì khác trên máy dùng cổng 80 và 443. Mở cổng TCP 80 và 443 cùng cổng UDP 443 trong bất kỳ tường lửa nào đứng trước nó.
- Bản ghi DNS của tên miền bạn trỏ đến máy. Nếu chưa trỏ, việc cài đặt vẫn hoàn tất, và Caddy tiếp tục thử lấy chứng chỉ cho đến khi bản ghi sẵn sàng.
- Bạn có thông tin của ít nhất một [nhà cung cấp đăng nhập](/docs/collaboration/server-access/#sign-in-providers), chẳng hạn client ID và secret của một ứng dụng GitHub OAuth. Với GitHub, địa chỉ callback là `https://` cùng tên miền của bạn, theo sau là `/auth/callback/github`.

:::note[Trong giai đoạn beta]
Hãy cài bản ứng viên phát hành, Oleafly Server 0.1.1-rc, để máy chủ khớp với Oleafly 0.4.7-rc:

```sh
curl -fsSL https://github.com/Oleafly/oleafly-server/releases/download/server-v0.1.1-rc/install.sh | sudo sh
```

Lệnh bên dưới cài bản 0.1.0, đã cũ hơn. Nếu bạn chạy image theo cách khác, chẳng hạn với Compose, Coolify, Render hay Railway, hãy dùng `ghcr.io/oleafly/oleafly-server:0.1.1-rc`.
:::

Sau đó chạy:

```sh
curl -fsSL https://oleafly.com/server/install.sh | sudo sh
```

Trình cài đặt sẽ:

1. Kiểm tra máy, và rằng cổng 80 và 443 còn trống.
2. Kiểm tra Docker. Nếu thiếu, trình cài đặt hỏi trước khi cài nó bằng chính script của Docker.
3. Tải các tệp của bản phát hành mới nhất từ [các bản phát hành Oleafly Server](https://github.com/Oleafly/oleafly-server/releases) và kiểm tra từng tệp với `SHA256SUMS` của bản phát hành. Nếu một tệp không khớp, nó dừng lại mà không thay đổi gì.
4. Hỏi tên miền của bạn, tên của máy chủ và cách mọi người đăng nhập. Nó cũng đề nghị thiết lập email và giữ các tệp trong một S3 bucket. Cả hai đều là tùy chọn.
5. Hiện một bản tóm tắt và hỏi trước khi thay đổi bất cứ điều gì. Rồi nó ghi các tệp của mình vào `/opt/oleafly-server`, với cài đặt của bạn trong `.env`, mà chỉ root mới đọc được.
6. Khởi động máy chủ với Caddy đứng trước, chờ cho đến khi tên miền của bạn trả lời qua HTTPS, và in ra địa chỉ cùng mã thiết lập.

Sau đó [trở thành quản trị viên đầu tiên](#become-the-first-admin).

Bạn có thể chạy trình cài đặt lại bất kỳ lúc nào. Khi nó tìm thấy một máy chủ trong `/opt/oleafly-server`, nó giữ nguyên `.env`, đặt lại các tệp khác và khởi động lại máy chủ. Điều đó sửa được phần lớn các thiết lập hỏng.

Dữ liệu của bạn nằm trong Docker volume `oleafly-server_oleafly-data`. Để cài ở nơi khác ngoài `/opt/oleafly-server`, hãy đặt `OLEAFLY_DIR`, ví dụ `curl -fsSL https://oleafly.com/server/install.sh | sudo OLEAFLY_DIR=/srv/oleafly sh`, và dùng thư mục đó trong các lệnh bên dưới.

### Đọc trình cài đặt trước

Nếu tổ chức của bạn không cho phép đưa một script thẳng vào shell, hãy tải `install.sh` và `SHA256SUMS` từ [bản phát hành mới nhất](https://github.com/Oleafly/oleafly-server/releases/latest) vào một thư mục. Kiểm tra script, đọc nó, rồi chạy:

```sh
sha256sum --check --ignore-missing SHA256SUMS
sudo sh install.sh
```

### Cài đặt không cần câu hỏi

Để dùng trong một script hoặc công cụ provisioning, thêm `--yes` và truyền các câu trả lời qua biến môi trường. `OLEAFLY_INSTALL_DOCKER=yes` cho phép trình cài đặt thêm Docker nếu nó còn thiếu.

```sh
curl -fsSL https://oleafly.com/server/install.sh | sudo \
  OLEAFLY_DOMAIN=collab.example.org \
  OLEAFLY_SERVER_NAME='Smith Lab' \
  OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId \
  OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret \
  OLEAFLY_INSTALL_DOCKER=yes \
  sh -s -- --yes
```

Trình cài đặt dùng mọi cài đặt nó tìm thấy trong môi trường mà không hỏi, có hoặc không có `--yes`. `sudo sh /opt/oleafly-server/install.sh --help` liệt kê tất cả, gồm OpenID Connect, email và S3. Các giá trị gõ trên dòng lệnh có thể rơi vào lịch sử shell của bạn, nên một công cụ provisioning cần truyền các secret từ kho secret riêng của nó.

### Trạng thái, cập nhật và gỡ cài đặt

- **Trạng thái**: `sudo sh /opt/oleafly-server/install.sh status` cho biết máy chủ có đang chạy hay không và tên miền của bạn có trả lời qua HTTPS với một chứng chỉ hợp lệ hay không.
- **Cập nhật**: sao lưu trước, như phần [Cập nhật](/docs/collaboration/server-operations/#updating) giải thích. Rồi chạy lệnh bên dưới. Nó tải các tệp và image của bản phát hành mới nhất, giữ nguyên `.env`, khởi động lại máy chủ và chờ cho đến khi nó trả lời. Những người đang kết nối sẽ tự kết nối lại. Trình cài đặt không bao giờ hạ máy chủ xuống một bản phát hành cũ hơn.

  ```sh
  curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update
  ```

- **Gỡ cài đặt**: `sudo sh /opt/oleafly-server/install.sh uninstall` dừng và xóa các container. Dữ liệu và `.env` của bạn vẫn còn, trừ khi bạn gõ `delete` khi nó hỏi. Việc xóa chúng sẽ xóa mọi dự án dùng chung trên máy chủ, mọi tài khoản và nhật ký bảo mật. Mọi người vẫn giữ các bản sao dự án của riêng họ trên máy tính của mình.

Nếu trình cài đặt dừng lại với một vấn đề bạn không sửa được, hãy [báo cáo nó](https://github.com/Oleafly/oleafly-server/issues/new/choose) kèm những gì nó in ra.

## Docker Compose thủ công

Cách thiết lập này chạy hai container. `oleafly-server` là máy chủ, và chỉ các container khác mới tiếp cận được nó. `caddy` lấy chứng chỉ từ Let's Encrypt, phục vụ HTTPS trên cổng 80 và 443, và chuyển các yêu cầu đến máy chủ, kể cả các kết nối thời gian thực.

1. Cài Docker Engine và plugin Compose theo [hướng dẫn của Docker](https://docs.docker.com/engine/install/).
2. Trỏ bản ghi DNS của tên miền bạn đến máy. Mở cổng TCP 80 và 443 cùng cổng UDP 443 trong bất kỳ tường lửa nào đứng trước nó. Caddy cần cổng 80 để lấy chứng chỉ.
3. Tạo một thư mục cho máy chủ, tải các tệp của bản phát hành mới nhất vào đó, kiểm tra chúng, và tạo tệp cài đặt của bạn:

   ```sh
   sudo mkdir -p /opt/oleafly-server && cd /opt/oleafly-server
   base=https://github.com/Oleafly/oleafly-server/releases/latest/download
   for f in docker-compose.yml Caddyfile env.example litestream.yml SHA256SUMS; do sudo curl -fsSLO "$base/$f"; done
   sha256sum --check --ignore-missing SHA256SUMS
   sudo install -m 600 env.example .env
   ```

4. Chỉnh sửa `.env` bằng `sudoedit .env`. Đặt `OLEAFLY_DOMAIN` thành tên miền của bạn, không kèm `https://`, đặt `OLEAFLY_SERVER_NAME`, và điền ít nhất một [nhà cung cấp đăng nhập](/docs/collaboration/server-access/#sign-in-providers). Để trống các dòng nhà cung cấp mà bạn không dùng. Đặt một giá trị trong dấu nháy đơn nếu nó chứa `$` hoặc `#`.
5. Khởi động. Lần khởi động đầu tải image của máy chủ, `ghcr.io/oleafly/oleafly-server`, ở phiên bản của bản phát hành.

   ```sh
   sudo docker compose up -d
   ```

6. Kiểm tra rằng nó trả lời. Lệnh này in ra `200`:

   ```sh
   curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz
   ```

7. [Trở thành quản trị viên đầu tiên](#become-the-first-admin). Mã thiết lập nằm trong nhật ký:

   ```sh
   sudo docker compose logs oleafly-server | grep 'Setup code'
   ```

Dữ liệu của bạn nằm trong Docker volume `oleafly-server_oleafly-data`. Caddy giữ chứng chỉ của nó trong `oleafly-server_caddy-data`.

Docker tự mở cổng 80 và 443, kể cả khi một tường lửa máy chủ như `ufw` đang bật. Đó là điều Caddy cần. Đừng thêm mục `ports:` vào dịch vụ `oleafly-server`. Để tiếp cận máy chủ từ chính máy đó, hãy publish nó dưới dạng `127.0.0.1:8080:8080` để nó không lộ ra mạng.

Nếu bạn thay đổi `Caddyfile`, hãy chạy `sudo docker compose up -d --force-recreate caddy`. Để cập nhật về sau, tải các tệp của bản phát hành mới theo cách tương tự và chạy lại `sudo docker compose up -d`.

### Giữ các secret ra khỏi .env

Bảy cài đặt có thể chứa secret: `OLEAFLY_SETUP_CODE`, `OLEAFLY_GITHUB_CLIENT_SECRET`, `OLEAFLY_OIDC_<NAME>_CLIENT_SECRET`, `OLEAFLY_SMTP_URL`, `OLEAFLY_BLOB_STORE`, `OLEAFLY_S3_ACCESS_KEY_ID` và `OLEAFLY_S3_SECRET_ACCESS_KEY`. Mỗi cái còn có một phiên bản `_FILE` chỉ định một tệp giữ giá trị đó. Chỉ đặt một trong hai, không đặt cả hai.

Ví dụ, để truyền client secret của GitHub dưới dạng một Docker secret, hãy lưu nó trong `secrets/github_client_secret` cạnh `docker-compose.yml`, cho người dùng của máy chủ (ID 10001) đọc được nó, và xóa dòng `OLEAFLY_GITHUB_CLIENT_SECRET` khỏi `.env`:

```sh
sudo chown 10001:10001 secrets/github_client_secret
sudo chmod 400 secrets/github_client_secret
```

Rồi tạo `docker-compose.override.yml` cạnh `docker-compose.yml`. Compose tự đọc nó, và trình cài đặt không đụng đến nó khi cập nhật các tệp khác.

```yaml
services:
  oleafly-server:
    environment:
      OLEAFLY_GITHUB_CLIENT_SECRET_FILE: /run/secrets/github_client_secret
    secrets:
      - github_client_secret

secrets:
  github_client_secret:
    file: ./secrets/github_client_secret
```

Chạy lại `sudo docker compose up -d`.

## Coolify

Coolify đặt proxy riêng của nó đứng trước máy chủ và lấy chứng chỉ, nên cách thiết lập này không có Caddy. Coolify có thể dựng máy chủ từ kho mã Oleafly, hoặc chạy [image đã xuất bản](#deploy-the-published-image), vốn bỏ qua bước dựng.

Trước khi bắt đầu, hãy trỏ bản ghi DNS của tên miền bạn, chẳng hạn `collab.example.org`, đến máy chủ Coolify. Rồi tạo ứng dụng GitHub OAuth như mô tả ở phần [GitHub](/docs/collaboration/server-access/#github), với địa chỉ callback `https://collab.example.org/auth/callback/github`. Giữ sẵn client ID và secret của ứng dụng.

### Dựng từ kho mã

1. Trong dự án Coolify của bạn, chọn **+ New**, rồi **Public Repository**, và nhập `https://github.com/Oleafly/Oleafly`. Giữ nguyên nhánh `main`.
2. Đặt **Build Pack** thành **Docker Compose**, **Base Directory** thành `/` và **Docker Compose Location** thành `/deploy/server/docker-compose.coolify.yml`, rồi chọn **Continue**.
3. Dưới **Advanced › Build**, đặt **Build arguments** thành **Managed manually in Dockerfile**. Image của máy chủ không cần tham số dựng. Nếu để chế độ tự động, Coolify sẽ ghi mọi biến, kể cả các secret, vào lịch sử dựng của image.
4. Dưới **General**, đặt tên miền của `oleafly-server` thành `https://collab.example.org:8080` rồi lưu. Phần `:8080` cho proxy của Coolify biết máy chủ lắng nghe trên cổng nào. Mọi người vẫn kết nối trên cổng HTTPS thông thường, và Coolify tự đặt `OLEAFLY_PUBLIC_URL` thành `https://collab.example.org` cho bạn.
5. Dưới **Environment Variables**, điền `OLEAFLY_SERVER_NAME`, mà Coolify đánh dấu là bắt buộc, rồi `OLEAFLY_GITHUB_CLIENT_ID` và `OLEAFLY_GITHUB_CLIENT_SECRET`. Để trống các biến mà bạn không dùng.
6. Chọn **Deploy**. Lần dựng đầu tiên biên dịch máy chủ và mất vài phút. Khi hoàn tất, Coolify hiển thị tài nguyên đang chạy và ổn định.
7. Mở `https://collab.example.org/healthz` trong trình duyệt. Nó hiển thị `{"status":"ok"}`.
8. Mở **Logs**, chọn container `oleafly-server`, và sao chép mã từ dòng mới nhất bắt đầu bằng `Setup code:`.
9. [Trở thành quản trị viên đầu tiên](#become-the-first-admin) với mã đó.

Nếu máy chủ không khởi động, nhật ký của nó sẽ nêu tên cài đặt mà nó không dùng được. Khi nhật ký nói `OLEAFLY_PUBLIC_URL` chưa được đặt, tức là thiếu bước 4. Một tên miền bắt đầu bằng `http://` sẽ bị từ chối, vì máy chủ cần HTTPS.

Nếu Cloudflare đứng trước Coolify, vì bản ghi DNS của bạn đi qua proxy của Cloudflare hoặc một tunnel dẫn đến proxy của Coolify, hãy đặt `OLEAFLY_PROXY_HOPS` thành `2`. Nếu không, nhật ký bảo mật sẽ hiển thị địa chỉ của proxy cho tất cả mọi người, và họ dùng chung một giới hạn đăng nhập.

Tệp Coolify có chỗ cho GitHub và một nhà cung cấp OpenID Connect tên `UNIVERSITY`. Đặt `OLEAFLY_OIDC_UNIVERSITY_LABEL` thành văn bản mọi người sẽ thấy, chẳng hạn `GitLab`. Địa chỉ callback của nó kết thúc bằng `/auth/callback/university`. Để thêm nhà cung cấp khác, hãy triển khai từ một fork với bản sao tệp riêng của bạn.

Dữ liệu nằm trong một Docker volume có tên kết thúc bằng `oleafly-data`. Tìm nó bằng `docker volume ls --filter name=oleafly-data`. Image không có shell, nên **Terminal** của Coolify không thể mở một shell trong container của máy chủ. Nhật ký và health check hoạt động như thường lệ.

### Triển khai image đã xuất bản

Chạy image đã xuất bản sẽ bỏ qua bước dựng, phù hợp với một máy chủ Coolify nhỏ. Làm theo các bước trên với hai thay đổi. Ở bước 2, đặt **Docker Compose Location** thành `/deploy/server/docker-compose.coolify-image.yml`. Bỏ qua bước 3, vì không có gì được dựng. Tệp theo dõi một chuỗi bản phát hành, nên mỗi lần **Redeploy** sẽ kéo bản phát hành mới nhất trong chuỗi đó.

## Render

[Deploy to Render](https://render.com/deploy?repo=https://github.com/Oleafly/Oleafly) đọc Blueprint trong kho mã Oleafly. Nó tạo một dịch vụ web từ image đã xuất bản, với một đĩa 1 GB cho thư mục dữ liệu. Render chỉ gắn đĩa vào các loại instance trả phí, nên dịch vụ khởi động trên loại trả phí nhỏ nhất, trong khu vực Oregon của Render. Để dùng khu vực khác, hãy triển khai từ một fork với `region` được đặt trong `render.yaml`.

1. Mở liên kết và đăng nhập vào Render.
2. Render hỏi `OLEAFLY_SERVER_NAME` cùng client ID và secret của GitHub. Điền tên và để trống các trường GitHub trong lúc này. Địa chỉ callback của chúng phụ thuộc vào địa chỉ dịch vụ, mà bạn chưa có.
3. Chọn **Deploy Blueprint**. Khi dịch vụ hoạt động, trang của nó hiển thị địa chỉ, chẳng hạn `https://oleafly-server.onrender.com`. Blueprint đặt `OLEAFLY_PUBLIC_URL` thành địa chỉ đó.
4. Tạo ứng dụng GitHub OAuth như mô tả ở phần [GitHub](/docs/collaboration/server-access/#github), với địa chỉ đó theo sau `/auth/callback/github` làm địa chỉ callback. Thêm client ID và secret dưới **Environment** của dịch vụ. Render khởi động lại máy chủ với các giá trị đó.
5. Tìm dòng `Setup code:` mới nhất trong **Logs** của dịch vụ và [trở thành quản trị viên đầu tiên](#become-the-first-admin).

Nếu bạn gán cho dịch vụ tên miền riêng của mình, hãy đặt `OLEAFLY_PUBLIC_URL` thành nó dưới **Environment** và đổi địa chỉ callback tại GitHub cho khớp.

Vì có đĩa, Render dừng máy chủ đang chạy trước khi khởi động máy chủ mới, nên mỗi lần triển khai làm máy chủ gián đoạn vài giây. Oleafly tự kết nối lại.

## Railway

Railway chạy image đã xuất bản, với một volume cho thư mục dữ liệu.

1. Trong một dự án Railway, chọn **+ New**, rồi **Docker Image**, và nhập `ghcr.io/oleafly/oleafly-server:latest`. Để tự chọn thời điểm nâng cấp, hãy dùng tag riêng của một bản phát hành từ [trang phát hành](https://github.com/Oleafly/Oleafly/releases) thay thế. Railway có thể bắt đầu một lần triển khai đầu tiên ngay lập tức. Nó dừng với `OLEAFLY_PUBLIC_URL is not set`, điều này là bình thường ở giai đoạn này.
2. Mở dịch vụ. Dưới **Settings › Networking**, chọn **Generate Domain** và nhập cổng `8080`. Railway hiển thị địa chỉ, chẳng hạn `oleafly-server-production.up.railway.app`.
3. Dưới **Settings › Deploy**, đặt **Healthcheck Path** thành `/readyz`.
4. Nhấp chuột phải vào khung dự án, thêm một volume, gắn nó vào dịch vụ của máy chủ và đặt đường dẫn gắn của nó thành `/data`.
5. Dưới **Variables**, mở **Raw Editor** và dán các dòng sau với tên máy chủ của riêng bạn. Với các giá trị GitHub, làm theo phần [GitHub](/docs/collaboration/server-access/#github). Địa chỉ callback là địa chỉ của bạn từ bước 2, với `https://` đứng trước và `/auth/callback/github` đứng sau.

   ```ini
   OLEAFLY_PUBLIC_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}
   OLEAFLY_BIND=0.0.0.0:8080
   OLEAFLY_DATA_DIR=/data
   OLEAFLY_BEHIND_PROXY=true
   OLEAFLY_SERVER_NAME=Smith Lab
   OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId
   OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret
   PORT=8080
   RAILWAY_RUN_UID=0
   ```

   Railway gắn volume với quyền root. `RAILWAY_RUN_UID=0` chạy máy chủ dưới quyền root để nó ghi được vào volume.

6. Triển khai các thay đổi. Tìm dòng `Setup code:` mới nhất trong **Deploy Logs** của dịch vụ và [trở thành quản trị viên đầu tiên](#become-the-first-admin).

## Linux không dùng Docker

Trên một máy không có Docker, máy chủ chạy như một chương trình đơn lẻ dưới systemd, với Caddy đứng trước cho HTTPS.

### Tải xuống máy chủ

Mỗi bản phát hành máy chủ trên [trang phát hành](https://github.com/Oleafly/Oleafly/releases) có một chương trình dựng sẵn cho x86-64 và cho ARM, cùng một tệp `SHA256SUMS` để kiểm tra. Chương trình không cần cài thêm gì khác.

Tải bản nén cho máy của bạn, kết thúc bằng `x86_64-unknown-linux-musl.tar.gz` hoặc `aarch64-unknown-linux-musl.tar.gz`, cùng `SHA256SUMS` vào một thư mục. Rồi kiểm tra và cài đặt. Trên máy ARM, dùng `aarch64` thay cho `x86_64`:

```sh
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf oleafly-server-*-x86_64-unknown-linux-musl.tar.gz
sudo install -m 0755 oleafly-server-*-x86_64-unknown-linux-musl/oleafly-server /usr/local/bin/oleafly-server
oleafly-server --version
```

Nếu đã cài GitHub CLI, lệnh `gh attestation verify oleafly-server-*-x86_64-unknown-linux-musl.tar.gz --repo Oleafly/Oleafly` còn kiểm tra rằng GitHub đã dựng bản nén đó từ kho mã Oleafly. Bản nén gồm cả unit systemd, `oleafly-server.service`.

Để tự dựng chương trình thay vì tải, hãy chạy lệnh này từ một bản clone của kho mã Oleafly trên bất kỳ máy tính nào có Docker. Dùng `--platform linux/arm64` cho một máy chủ ARM.

```sh
docker buildx build --platform linux/amd64 --target binary --output type=local,dest=dist -f crates/oleafly-server/Dockerfile .
```

Lệnh này ghi ra `dist/oleafly-server`. Sao chép nó vào `/usr/local/bin/oleafly-server` trên máy chủ và cấp quyền thực thi cho nó.

### Chạy với systemd

1. Tạo tệp cài đặt. Chỉ root mới đọc được nó:

   ```sh
   sudo install -d -m 0755 /etc/oleafly-server
   sudo install -m 0600 /dev/null /etc/oleafly-server/oleafly-server.env
   sudoedit /etc/oleafly-server/oleafly-server.env
   ```

   Đặt mỗi cài đặt trên một dòng. `OLEAFLY_BIND=127.0.0.1:8080` giữ máy chủ ngoài mạng để chỉ Caddy tiếp cận được nó. Đừng đặt `OLEAFLY_DATA_DIR`, vì unit đã đặt nó sẵn.

   ```ini
   OLEAFLY_PUBLIC_URL=https://collab.example.org
   OLEAFLY_BIND=127.0.0.1:8080
   OLEAFLY_BEHIND_PROXY=true
   OLEAFLY_SERVER_NAME=Smith Lab
   OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId
   OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret
   ```

2. Cài đặt và khởi động unit từ bản nén đã giải nén, hoặc từ `deploy/server` trong một bản clone của kho mã. Rồi tìm mã thiết lập:

   ```sh
   sudo install -m 0644 oleafly-server.service /etc/systemd/system/oleafly-server.service
   sudo systemctl daemon-reload
   sudo systemctl enable --now oleafly-server
   sudo journalctl -u oleafly-server | grep 'Setup code'
   ```

Unit chạy máy chủ dưới một người dùng mà systemd tạo cho nó, với chế độ chỉ đọc đối với phần còn lại của hệ thống. Nơi duy nhất nó ghi được là `/var/lib/oleafly-server`, nơi nó giữ dữ liệu của mình. Trên đĩa, thư mục đó là `/var/lib/private/oleafly-server`.

Để giữ client secret ra khỏi tệp cài đặt, hãy dùng một credential của systemd. Lưu secret trong `/etc/oleafly-server/github-client-secret` với chế độ 600, xóa dòng `OLEAFLY_GITHUB_CLIENT_SECRET` khỏi tệp cài đặt, chạy `sudo systemctl edit oleafly-server`, và thêm:

```ini
[Service]
LoadCredential=github-client-secret:/etc/oleafly-server/github-client-secret
Environment=OLEAFLY_GITHUB_CLIENT_SECRET_FILE=%d/github-client-secret
```

Rồi chạy `sudo systemctl restart oleafly-server`.

### Đặt HTTPS đứng trước

Cài Caddy theo [hướng dẫn dành cho bản phân phối của bạn](https://caddyserver.com/docs/install). Thay `/etc/caddy/Caddyfile` bằng các dòng sau và chạy `sudo systemctl reload caddy`. Caddy lấy chứng chỉ và chuyển tiếp các kết nối thời gian thực.

```
collab.example.org {
	reverse_proxy 127.0.0.1:8080
}
```

Với nginx hoặc Apache, hoặc một máy chủ web mà trường đại học của bạn đã chạy, hãy đọc [Sau một reverse proxy](/docs/collaboration/server-operations/#behind-a-reverse-proxy).

## Khi không có địa chỉ công khai

Nếu máy không có địa chỉ công khai, chẳng hạn một máy tính trong phòng thí nghiệm của bạn nằm sau tường lửa của trường đại học, Cloudflare Tunnel có thể làm cho nó truy cập được. Bạn cần một tài khoản Cloudflare có tên miền của bạn trên đó. Cloudflare xử lý HTTPS cho tên máy chủ, nên các yêu cầu được giải mã trên mạng của Cloudflare trước khi đến máy của bạn. Hãy kể Cloudflare vào số những bên có thể đọc lưu lượng đến máy chủ của bạn.

1. Làm theo các bước của [Docker Compose thủ công](#docker-compose-by-hand) cho đến bước chỉnh sửa `.env`. Đặt `OLEAFLY_DOMAIN` thành tên máy chủ bạn sẽ dùng, chẳng hạn `collab.example.org`. Trình cài đặt một lệnh không phù hợp ở đây, vì nó khởi động Caddy.
2. Chỉ khởi động máy chủ. Caddy không cần ở đây:

   ```sh
   sudo docker compose up -d oleafly-server
   ```

3. Trong bảng điều khiển Cloudflare, vào **Networking › Tunnels**, chọn **Create Tunnel**, đặt tên cho tunnel, rồi chọn **Create Tunnel** lần nữa. Sao chép token từ lệnh cài đặt mà nó hiển thị.
4. Khởi động tunnel cạnh máy chủ. Lệnh `read` chờ bạn dán token vào và không hiển thị token:

   ```sh
   read -rs TUNNEL_TOKEN && export TUNNEL_TOKEN
   sudo --preserve-env=TUNNEL_TOKEN docker run -d --name oleafly-tunnel --restart unless-stopped --network oleafly-server_default -e TUNNEL_TOKEN cloudflare/cloudflared:2026.10.0 tunnel --no-autoupdate run
   ```

5. Quay lại bảng điều khiển, mở tunnel. Dưới **Routes**, chọn **Add route**, rồi **Published application**. Dưới **Hostname**, nhập tên miền phụ và chọn tên miền của bạn. Đặt **Service URL** thành `http://oleafly-server:8080` và chọn **Add route**.
6. Kiểm tra rằng nó trả lời tại `https://collab.example.org/healthz`, rồi [trở thành quản trị viên đầu tiên](#become-the-first-admin).

Trên một máy không có Docker, hãy cài `cloudflared` từ [kho gói của Cloudflare](https://pkg.cloudflare.com/), chạy `sudo cloudflared service install` theo sau là token, và đặt **Service URL** thành `http://127.0.0.1:8080`.

Cloudflare chuyển tiếp các kết nối thời gian thực và đặt địa chỉ của người truy cập ở vị trí cuối cùng trong `X-Forwarded-For`, nên hãy giữ `OLEAFLY_BEHIND_PROXY=true`. Khi tunnel dẫn đến một proxy khác, chẳng hạn proxy của Coolify, chứ không đi thẳng đến máy chủ, cũng hãy đặt `OLEAFLY_PROXY_HOPS=2`. Cloudflare từ chối các yêu cầu lớn hơn 100 MB trên các gói Free và Pro, nên hãy đặt `OLEAFLY_MAX_PROJECT_MB` thành 100 hoặc nhỏ hơn, nếu không các dự án lớn sẽ không tải lên được. Đừng đặt Cloudflare Access đứng trước máy chủ, vì Oleafly không thể vượt qua trang đăng nhập của nó.

Khi bạn cập nhật máy chủ về sau, hãy tải các tệp của bản phát hành mới và nêu tên dịch vụ để Caddy không tham gia: `sudo docker compose up -d oleafly-server`.

## Trở thành quản trị viên đầu tiên

Một máy chủ mới chưa có quản trị viên. Cho đến khi ai đó hoàn tất thiết lập, máy chủ tạo một mã thiết lập dùng một lần mới mỗi lần khởi động và ghi nó vào nhật ký.

1. Tìm dòng mới nhất bắt đầu bằng `Setup code:` trong nhật ký:
   - Cài đặt bằng một lệnh: trình cài đặt in mã khi hoàn tất. Để xem lại, chạy `cd /opt/oleafly-server && sudo docker compose logs oleafly-server | grep 'Setup code'`
   - Docker Compose thủ công: chạy `sudo docker compose logs oleafly-server | grep 'Setup code'` trong thư mục của máy chủ
   - Coolify: nhật ký của dịch vụ `oleafly-server`
   - systemd: `sudo journalctl -u oleafly-server | grep 'Setup code'`
2. Trong Oleafly, mở **Settings → Collaboration**, chọn **Add server**, và nhập địa chỉ máy chủ của bạn. Oleafly nhận thấy máy chủ cần thiết lập và hỏi **Setup code**.
3. Nhập mã và đăng nhập bằng bất kỳ nhà cung cấp nào bạn đã cấu hình. Bạn trở thành quản trị viên của máy chủ, và mã ngừng hoạt động.

Bất kỳ ai có mã trước khi bạn dùng nó đều có thể tự lên làm quản trị viên, nên hãy chỉ dán mã vào Oleafly mà thôi.

Bạn cũng có thể tự chọn mã bằng `OLEAFLY_SETUP_CODE`: ít nhất 12 chữ cái hoặc chữ số, thêm dấu gạch ngang hay dấu cách tùy ý. Máy chủ khi đó không bao giờ in mã ra. Nhật ký chỉ ghi `Setup code: set by OLEAFLY_SETUP_CODE`, và bạn nhập giá trị bạn đã đặt. Sau khi thiết lập xong, hãy xóa nó khỏi cài đặt của bạn.

Tiếp theo, hãy cho mọi người vào. [Đăng nhập và truy cập](/docs/collaboration/server-access/#access-rules) giải thích cách làm.

## Kiểm tra máy chủ

- Với cách cài đặt bằng một lệnh, `sudo sh /opt/oleafly-server/install.sh status` kiểm tra các container và HTTPS trong một lần.
- `https://collab.example.org/healthz` trả lời `200` khi tiến trình máy chủ đang chạy.
- `/readyz` chỉ trả lời `200` khi máy chủ ghi được vào cơ sở dữ liệu và thư mục dữ liệu của mình. Khi không ghi được, chẳng hạn khi đĩa đầy, nó trả lời `503` và nêu rõ bộ phận gặp lỗi, `database` hoặc `storage`.
- Image Docker tự kiểm tra `/readyz`, nên `docker ps` và Coolify hiển thị một máy chủ không ổn định thay vì một máy chủ đang chạy mà không lưu được gì.
- Trong Oleafly, **Test connection** dưới **Settings → Collaboration** kiểm tra địa chỉ, HTTPS, phiên bản, các kết nối thời gian thực, các tùy chọn đăng nhập và đồng hồ của máy chủ. **Connection checks** trong [bảng điều khiển quản trị](/docs/collaboration/server-access/#admin-console) chạy cũng những kiểm tra đó.
