Cách triển khai NestJS trên Namecheap Shared Hosting
Triển khai NestJS lên Namecheap shared hosting không giống như triển khai một trang web tĩnh hay một ứng dụng PHP. Bạn không thể chỉ đơn giản là tải các tệp lên và mong đợi nó hoạt động.
Bạn phải biên dịch TypeScript sang JavaScript, cài đặt các phụ thuộc (dependencies) cho môi trường production và sử dụng cPanel để quản lý quy trình thông qua Passenger.
Tôi đã từng gặp phải tình trạng thư mục trống, thiếu các tệp build và lỗi kết nối Redis trước khi tìm ra cách làm đúng. Dưới đây là quy trình làm việc đã được kiểm chứng.
Logic thiết lập
Yêu cầu (request) sẽ đi theo lộ trình sau: • Trình duyệt hoặc API client • Tên miền và HTTPS • Apache / Passenger trên Namecheap • app.js (cầu nối) • dist/main.js (mã đã biên dịch) • Ứng dụng NestJS
Các yêu cầu chính
• Một tài khoản hosting Namecheap có hỗ trợ Node.js • Quyền truy cập vào cPanel và SSH/Terminal • Một dự án NestJS đang hoạt động • Thông tin đăng nhập (credentials) môi trường production cho cơ sở dữ liệu hoặc Redis của bạn
Bước 1: Chuẩn bị mã nguồn
Đừng sử dụng cổng (port) được viết cứng (hard-coded). Trong tệp src/main.ts, hãy sử dụng process.env.PORT:
async function bootstrap() {
const app = await NestFactory.create(AppModule);
await app.listen(process.env.PORT || 4000);
}
Bước 2: Sắp xếp các phụ thuộc (dependencies)
Hãy chuyển các gói runtime như @nestjs/common và @nestjs/core sang phần dependencies trong package.json. Nếu chúng vẫn nằm trong devDependencies, ứng dụng của bạn sẽ bị lỗi khi chạy trên môi trường production.
Bước 3: Build và tạo cầu nối
Namecheap chạy JavaScript, không phải TypeScript.
• Chạy npm run build ở máy cục bộ (locally).
• Kiểm tra xem dist/main.js có tồn tại hay không.
• Tạo một tệp app.js trong thư mục gốc của dự án với dòng này: require('./dist/main');
Tệp app.js này đóng vai trò là điểm khởi đầu (entry point) cho Passenger.
Bước 4: Chiến lược triển khai
Cách an toàn nhất là build ở máy cục bộ và tải lên các tệp thành phẩm (artifacts):
• Tải lên app.js
• Tải lên thư mục dist/
• Tải lên package.json và package-lock.json
• Trên Namecheap, chạy: npm ci --omit=dev
Đừng bao giờ tải lên thư mục node_modules cục bộ của bạn. Các module native được build trên máy tính của bạn sẽ không hoạt động trên máy chủ Linux.
Bước 5: Cấu hình cPanel
Truy cập vào Setup Node.js App trong cPanel:
• Chọn phiên bản Node.js chính xác.
• Đặt chế độ (mode) thành Production.
• Đặt Application root là thư mục của bạn.
• Đặt Application startup file là app.js.
Bước 6: Biến môi trường (Environment Variables)
Thêm các thông tin bảo mật (như DATABASE_URL hoặc API keys) trực tiếp trong giao diện Node.js của cPanel. Bạn cũng có thể sử dụng tệp .env ở thư mục gốc, nhưng hãy đảm bảo nó không nằm bên trong thư mục dist. Khởi động lại ứng dụng sau khi thực hiện thay đổi.
Các lỗi thường gặp và cách khắc phục
• EADDRINUSE: Có khả năng bạn đang có một tiến trình chạy thủ công. Hãy để Passenger quản lý ứng dụng.
• Cannot find module: Bản build của bạn bị thiếu hoặc đường dẫn trong app.js bị sai.
• Redis connection failed: Kiểm tra xem Namecheap có cho phép các kết nối outbound trên cổng Redis của bạn hay không. Bạn có thể cần yêu cầu bộ phận hỗ trợ của Namecheap mở cổng đó.
Source: https://dev.to/adesoji/how-to-deploy-and-run-a-nestjs-app-on-namecheap-shared-hosting-5c45