# Triển khai Mailroom lên cPanel

## Yêu cầu hosting

- Có **Node.js 22.13 trở lên** và mục **Application Manager**, **Setup Node.js App** hoặc **Web Apps**.
- Có domain/subdomain đã bật HTTPS, ví dụ `mail.example.com`.
- Cho phép tiến trình Node.js kết nối ra ngoài tới Google APIs.
- Thư mục ứng dụng và thư mục `data` có quyền ghi.

Nếu cPanel chỉ có PHP hoặc Node.js thấp hơn 22.13, hãy yêu cầu nhà cung cấp nâng phiên bản. Ứng dụng dùng SQLite tích hợp của Node.js nên không chạy trên Node.js cũ.

## 1. Chuẩn bị domain

Tạo một subdomain riêng, ví dụ `mail.example.com`, rồi bật chứng chỉ SSL/AutoSSL. Không dùng đường dẫn con nếu giao diện cPanel cho phép gắn ứng dụng trực tiếp vào subdomain.

## 2. Tải và giải nén mã nguồn

Trong **File Manager**, tạo thư mục ngoài `public_html`, ví dụ:

```text
/home/CPANEL_USER/mailroom
```

Tải `mailroom-cpanel.zip` vào thư mục này và giải nén. Sau khi giải nén, `app.js`, `server.mjs` và `package.json` phải nằm ngay trong thư mục ứng dụng.

## 3. Tạo ứng dụng Node.js

Trong **Application Manager / Setup Node.js App / Web Apps**:

1. Chọn Node.js 22 hoặc mới hơn.
2. Chọn chế độ **Production**.
3. Application root: `mailroom`.
4. Application URL: subdomain HTTPS đã tạo.
5. Startup file: `app.js`.
6. Lưu ứng dụng.

Không tự đặt `PORT` nếu cPanel đã cung cấp biến này. Mailroom sẽ dùng cổng do cPanel cấp.

## 4. Thêm biến môi trường

Thêm các biến sau trong phần **Environment Variables** của ứng dụng:

```text
APP_MODE=live
HOST=127.0.0.1
BASE_URL=https://mail.example.com
DATABASE_PATH=./data/live.sqlite
SESSION_SECRET=CHUOI_NGAU_NHIEN_IT_NHAT_32_KY_TU
DEFAULT_DAILY_LIMIT=200
```

Thay `mail.example.com` bằng subdomain thật. `BASE_URL` phải là địa chỉ HTTPS gốc, không có đường dẫn và không có dấu `/` cuối.

Tạo `SESSION_SECRET` trong Terminal của cPanel:

```bash
node -e "console.log(require('node:crypto').randomBytes(48).toString('hex'))"
```

Giữ nguyên secret này khi cập nhật ứng dụng. Nếu đổi hoặc mất secret, khóa service account đã lưu sẽ không giải mã được.

## 5. Cài thư viện và khởi động

Dùng nút **Enable Dependencies / Run NPM Install** của cPanel. Nếu hosting cung cấp Terminal, có thể chạy trong thư mục ứng dụng:

```bash
npm install --omit=dev
mkdir -p data tmp
touch tmp/restart.txt
```

Mở `https://mail.example.com/health`. Kết quả đúng:

```json
{"ok":true,"mode":"live"}
```

Sau đó mở trang chính. Với database mới, tạo tài khoản Chủ hệ thống bằng:

```text
Email: info@nghi.org
Mật khẩu: @admin123
```

Đăng nhập, mở **Workspace & phân quyền**, tải `service-account.json` và nhập email Super Admin. Hệ thống sẽ kiểm tra Domain-wide delegation, mã hóa khóa rồi đồng bộ tài khoản Workspace.

## Giữ bộ gửi theo lịch hoạt động

Một số gói shared hosting cho tiến trình Passenger ngủ khi không có truy cập. Trong **Cron Jobs**, thêm tác vụ mỗi phút để giữ ứng dụng hoạt động:

```cron
* * * * * curl -fsS https://mail.example.com/health >/dev/null 2>&1
```

Thay domain bằng URL thật. Nếu nhà cung cấp có tùy chọn giữ Node.js app luôn chạy hoặc cấu hình Passenger minimum instances, hãy bật tùy chọn đó. Với chiến dịch cần chạy liên tục và chính xác từng giây, dùng VPS hoặc gói hosting cam kết không cho tiến trình Node.js ngủ.

## 6. Cập nhật phiên bản sau này

Sao lưu thư mục `data` trước khi cập nhật. Ghi đè mã nguồn nhưng giữ nguyên `data` và các biến môi trường, chạy lại `npm install --omit=dev`, sau đó tạo tệp khởi động lại:

```bash
touch tmp/restart.txt
```

Không tải `.env`, `service-account.json` hoặc database vào thư mục web công khai.