Hướng Dẫn Cài Đặt Strapi v5 Lên Hosting cPanel

Strapi v5 là phiên bản CMS mã nguồn mở mạnh mẽ nhất hiện nay. Tuy nhiên, việc đưa Strapi lên Shared Hosting sử dụng cPanel thường gặp khó khăn do cấu hình môi trường. Bài viết này sẽ giúp bạn giải quyết vấn đề đó.

1. Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo Hosting của bạn đáp ứng:

RAM: Tối thiểu 2GB (Strapi v5 khá tốn tài nguyên khi build).
Node.js: Phiên bản 18.x hoặc 20.x trở lên.
Quyền truy cập SSH: Bắt buộc phải có để chạy các lệnh cài đặt.
Database: MySQL hoặc MariaDB (với Strapi v5, bạn nên dùng MySQL 8.0+).

2. Các bước thực hiện chi tiết

Bước 1: Chuẩn bị mã nguồn Strapi dưới Local

Thay vì cài đặt trực tiếp trên Hosting (dễ lỗi do giới hạn tài nguyên), bạn nên cài đặt và build sẵn ở máy tính cá nhân.

Khởi tạo dự án Strapi v5:

npx create-strapi-app@latest my-project

Quan trọng nhất là dòng: `Strapi Your application was created!` nghĩa là mã nguồn Strapi đã được tạo thành công trong thư mục my-project rồi.

Đóng gói Source Code (Quan trọng)
   - Chỉ nén các thư mục/file cần thiết. `KHÔNG` nén `node_modules`, `dist`, `.git`, `.env`.
   - Các file cần có trong file nén (.zip hoặc .tar):
     + config/
     + database/
     + public/
     + src/
     + types/
     + favicon.png
     + package.json
     + package-lock.json (hoặc yarn.lock)
     + tsconfig.json
   - Nếu dùng lệnh terminal (MacOS/Linux):
     tar -cvf strapi.tar --exclude='node_modules' --exclude='dist' --exclude='.git' --exclude='.strapi' --exclude='.env' .

Bây giờ bạn tiếp tục các bước như hướng dẫn:

Truy cập vào thư mục vừa tạo (trên máy bạn):

cd my-project

Nén lại để upload (bỏ qua node_modules vì lên hosting cài lại cho chuẩn):


tar -cvf strapi.tar --exclude='node_modules' --exclude='.git' .

Bước 2: Tạo ứng dụng Node.js trên cPanel

1. Vào cPanel -> Setup Node.js App.
- Bấm "Create Application".
- Cấu hình:
+ Node.js version: Chọn bản tương thích (Khuyên dùng v20.x cho Strapi V5).
+ Application mode: Production.
+ Application root: Nhập tên thư mục muốn chứa code (ví dụ: domains/strapi.quyenlt.com).
+ Application URL: Chọn domain/subdomain sẽ chạy.
+ Application startup file: Nhập `app.js` (Lát nữa sẽ tạo file này).
- Bấm "Create".

2.Ngoài ra chúng ta cần chuẩn bị Database
- Vào cPanel -> MySQL Databases.
- Tạo Database mới.
- Tạo User mới và gán full quyền cho Database vừa tạo.
- Lưu lại thông tin: DB_NAME, DB_USER, DB_PASSWORD.

3. Upload Source Code
- Vào File Manager, truy cập đúng thư mục Root vừa tạo ở bước trên.
- Upload file nén (strapi.tar hoặc .zip) và giải nén ra (Extract).
- Đảm bảo các file (src, package.json...) nằm ngay thư mục gốc, không nằm lồng trong thư mục con.

4. Cài đặt Cấu hình & Thư viện
- Bước 4.1: Cài đặt thư viện

Hãy vào Terminal (hoặc SSH) cd vào thư mục và chạy lệnh:

 npm install

- Bước 4.2: Cấu hình biến môi trường (.env)
+ Tạo file `.env` tại thư mục gốc.
+ Copy mẫu từ `.env.example`.
+ Sửa thông tin quan trọng:


       DATABASE_HOST=127.0.0.1  (Lưu ý: Không dùng 'localhost' nếu lỗi kết nối)
       DATABASE_NAME= (Tên DB đã tạo ở Bước 2.2)
       DATABASE_USERNAME=
       DATABASE_PASSWORD=
       PORT=1337 (Thực tế cPanel quản lý port qua Passenger, nhưng cứ để 1337 để tránh lỗi config)

5. Tạo file khởi chạy `app.js` (Dành riêng cho cPanel/Passenger)
- Vì cPanel dùng Phusion Passenger để chạy Node app, nó cần entry point.
- Tạo file `app.js` ngang hàng với `package.json`.
- Nội dung file `app.js` cho Strapi V5:

     const { createStrapi } = require('@strapi/strapi');
     const strapi = createStrapi({
       distDir: './dist',
     });
     strapi.start();

6. Thêm đoạn cấu hình sau vào cuối file `.htaccess`

# Quy tắc Rewrite để cho phép truy cập Public Assets (ảnh, css...)
RewriteEngine On
RewriteCond %{REQUEST_URI} !^/uploads/
ReWriteRule ^.*$ - [NC,L]

7. Build Admin Panel (Bắt buộc)
- Strapi cần build lại giao diện Admin để chạy production.
- Vào Terminal của cPanel (hoặc SSH) sau đó chạy lệnh vào môi trường Nodejs và chạy lệnh

Chờ lệnh chạy xong (thấy báo Success).

npm run build

8. Khởi chạy
- Quay lại giao diện "Setup Node.js App".
- Bấm nút "Restart".
- Truy cập domain của bạn để kiểm tra kết quả.
- Vào /admin để tạo tài khoản quản trị viên đầu tiên.

3. Kết luận

Việc cài đặt Strapi v5 trên cPanel hoàn toàn khả thi nếu bạn tuân thủ quy trình build ở local và deploy bản dist. Điều này giúp tiết kiệm tài nguyên hosting và tránh các lỗi xung đột môi trường.

Lưu ý: Strapi v5 yêu cầu tài nguyên khá lớn, nếu website của bạn có lượng truy cập cao, hãy cân nhắc sử dụng VPS để có hiệu năng tốt nhất.