Hướng dẫn cài đặt ứng dụng Node.js trên cPanel

cPanel cho phép bạn chạy ứng dụng Node.js trực tiếp trên shared hosting mà không cần VPS. Bài này hướng dẫn từ A-Z: tạo app, deploy code, và test kết quả — tất cả đã được thực hiện và kiểm chứng thật trên cPanel.

I. Yêu cầu

• Hosting cPanel có hỗ trợ Setup Node.js App (thường có trên hosting dùng CloudLinux)
• Một domain hoặc subdomain để trỏ đến app
• File ứng dụng Node.js (sẽ tạo trong bài)

II. Truy cập Setup Node.js App

Đăng nhập cPanel → tìm Setup Node.js App trong phần Software trên sidebar trái (hoặc gõ “Node.js” vào thanh tìm kiếm).

Trên trang này bạn sẽ thấy danh sách các app đã tạo, kèm trạng thái (started/stopped), phiên bản Node.js, và các nút: Stop, Restart, Edit, Delete.

III. Tạo ứng dụng Node.js

Bước 1: Chuẩn bị code

Vào File Manager → tạo thư mục chứa app trong home directory (ngoài public_html). Ví dụ: tạo thư mục mynodeapp.

Tạo file app.js trong thư mục mynodeapp. Đây là ví dụ đơn giản dùng module http có sẵn (không cần cài thêm package):

const http = require("http");
const port = process.env.PORT || 3000;
const server = http.createServer((req, res) => {
  res.writeHead(200, {"Content-Type": "text/html; charset=utf-8"});
if (req.url === "/") {
    res.end(`
      <h1>🚀 Node.js App on cPanel</h1>
      <p>Node.js version: ${process.version}</p>
      <p>Platform: ${process.platform} (${process.arch})</p>
      <p>Server time: ${new Date().toLocaleString("vi-VN", {timeZone: "Asia/Ho_Chi_Minh"})}</p>
      <p><a href="/api">Xem API JSON</a></p>
    `);
  } else if (req.url === "/api") {
    res.setHeader("Content-Type", "application/json");
    res.end(JSON.stringify({
      status: "ok",
      node: process.version,
      time: new Date().toISOString(),
      uptime: process.uptime()
    }, null, 2));
  } else {
    res.writeHead(404);
    res.end("Not Found");
  }
});
server.listen(port, "127.0.0.1", () => {
  console.log("Server on port " + port);
});

💡 Lưu ý quan trọng: Server phải listen trên 127.0.0.1 (hoặc bỏ trống) và dùng process.env.PORT — Passenger sẽ tự gán port. Không hardcode port số cụ thể.

Tạo file package.json:

{
  "name": "mynodeapp",
  "version": "1.0.0",
  "main": "app.js",
  "scripts": {
    "start": "node app.js"
  }
}

Bước 2: Tạo Application trên cPanel

Click nút Create Application (hoặc icon +) trên trang Setup Node.js App:

Điền thông tin:

• Node.js version: Chọn phiên bản mới nhất ổn định (trong bài này dùng 22.22.0)
• Application mode: Chọn Production
• Application root: mynodeapp (tên thư mục đã tạo ở Bước 1)
• Application URL: Chọn domain, sau đó nhập đường dẫn phụ nếu muốn (VD: nodeapp → app sẽ chạy tại domain.com/nodeapp)
• Application startup file: app.js

Click Create. cPanel sẽ tạo virtual environment và cấu hình Passenger tự động.

Bước 3: Cài đặt dependencies (nếu cần)

Sau khi tạo app, cPanel hiển thị thông báo kèm lệnh activate virtual environment:

source /home/username/nodevenv/mynodeapp/22/bin/activate && cd /home/username/mynodeapp

Nếu app dùng package bên ngoài (express, axios…), bạn cần chạy npm install. Có 2 cách:

• Cách 1 — Qua giao diện: Click Edit (icon bút chì) trên app → click Run NPM Install
• Cách 2 — Qua Terminal: Vào Terminal trên cPanel, chạy lệnh activate rồi npm install

💡 Mẹo: Với ví dụ trong bài này, app chỉ dùng module http có sẵn trong Node.js nên không cần npm install. Chỉ cần npm install khi bạn dùng package bên ngoài (express, dotenv…).

Bước 4: Restart và test

Quay lại danh sách app, click Restart (icon mũi tên xoay). Sau đó truy cập URL:

App hiển thị thông tin Node.js version, platform, thời gian server — xác nhận đang chạy thật trên cPanel!

IV. Ví dụ nâng cao: Express.js

Để dùng framework phổ biến hơn, cài Express qua Terminal:

# Activate virtual environment
source /home/username/nodevenv/mynodeapp/22/bin/activate
# Cài Express
cd ~/mynodeapp
npm install express

Cập nhật file app.js:

const express = require('express');
const app = express();
const port = process.env.PORT || 3000;
app.get('/', (req, res) => {
  res.send(`
    <h1>🚀 Express.js trên cPanel</h1>
    <p>Server time: ${new Date().toLocaleString('vi-VN')}</p>
    <p>Node version: ${process.version}</p>
  `);
});
app.get('/api/info', (req, res) => {
  res.json({
    app: 'My Express App',
    node: process.version,
    platform: process.platform,
    uptime: process.uptime()
  });
});
app.listen(port, () => {
  console.log(`Express app listening on port ${port}`);
});

Sau đó vào cPanel → Setup Node.js App → click Restart để cập nhật.

V. Xử lý lỗi thường gặp

• 503 Service Unavailable: App chưa start hoặc bị crash — kiểm tra stderr.log trong thư mục app, đảm bảo startup file đúng tên
• 502 Bad Gateway: App crash liên tục — kiểm tra syntax code, đảm bảo listen trên đúng port (process.env.PORT)
• npm install lỗi: Có thể do thiếu bộ nhớ hoặc package không tương thích. Thử: (1) Click Run NPM Install qua giao diện, (2) Nếu vẫn lỗi, dùng Terminal chạy thủ công, (3) Cài từng package một
• App không cập nhật sau khi sửa code: Phải click Restart — Passenger cache ứng dụng
• Không thấy phiên bản Node.js mới: Liên hệ hosting provider để cập nhật CloudLinux

VI. Tổng kết

Chạy Node.js trên cPanel shared hosting hoàn toàn khả thi cho các ứng dụng nhỏ-vừa: API server, landing page, tool nội bộ, webhook receiver… Quy trình tóm gọn:

1. Upload code vào thư mục trên hosting (ngoài public_html)
2. Tạo app trên Setup Node.js App → chọn version, mode Production, điền đường dẫn
3. Cài dependencies nếu cần (Run NPM Install hoặc Terminal)
4. Click Restart và test URL

Nếu cần nhiều tài nguyên hơn hoặc chạy ứng dụng phức tạp (Next.js SSR, real-time WebSocket…), cân nhắc chuyển sang VPS để có toàn quyền kiểm soát.