Hướng Dẫn Deploy Next.js Lên VPS Bằng Coolify – Thoát Phí Vercel, Tự Chủ Hạ Tầng

Deploy Next.js lên VPS bằng Coolify là hướng đi nhiều dev Việt Nam chuyển sang khi hóa đơn Vercel tăng theo build minutes và bandwidth, hoặc khi cần tự chủ hạ tầng cho nhiều dự án cùng lúc. Coolify cho bạn giao diện quản lý gần giống Vercel, nhưng chạy trên chính VPS của bạn. Bài viết này của InterData đi từng bước thật, kèm lỗi thường gặp và cách xử lý.

Coolify Là Gì? Vì Sao Deploy Next.js Qua Coolify Thay Vì Vercel?

Coolify là phần mềm PaaS (Platform as a Service) mã nguồn mở, cài trực tiếp trên VPS của bạn để build, deploy và quản lý ứng dụng qua giao diện web – vai trò gần giống Vercel hay Heroku, nhưng chạy trên hạ tầng bạn tự kiểm soát, không bị giới hạn theo gói trả phí của bên thứ ba.

Cần phân biệt rõ ngay từ đầu: bài này hướng dẫn tự cài Coolify (self-hosted) trên VPS của bạn – mã nguồn mở, không mất phí bản quyền. Coolify Cloud là bản SaaS do chính đội ngũ Coolify vận hành, tính phí theo tháng và bạn không cần quản lý server. Hai mô hình triển khai khác nhau hoàn toàn dù giao diện sử dụng giống nhau, và toàn bộ bài viết này chỉ nói về cách tự host.

Coolify chạy dựa trên nền Docker: mỗi ứng dụng bạn deploy được đóng gói thành container riêng, cô lập với nhau trên cùng một VPS. Đây là lý do Coolify có thể chạy nhiều Next.js app, hoặc kết hợp cả database, cùng lúc trên một máy chủ mà không xung đột môi trường.

So với Vercel, lý do phổ biến nhất khiến dev chuyển sang tự host là chi phí ở quy mô lớn: build minutes, bandwidth, số lượng function invocation đều tính phí theo gói, và tăng nhanh khi traffic hoặc số dự án tăng. Lý do thứ hai là muốn chủ động hạ tầng – tự quyết định RAM, region, cách scale, thay vì phụ thuộc vào giới hạn của nền tảng. Đây không phải nhận định Vercel kém, chỉ là bài toán chi phí và quyền kiểm soát khác nhau theo quy mô sử dụng.

Chuẩn Bị Gì Trước Khi Deploy Next.js Lên VPS Bằng Coolify

Trước khi mở dashboard Coolify, cần chuẩn bị đủ 4 thứ: một VPS có quyền root, domain đã trỏ được, source code trên Git, và Next.js đã cấu hình đúng cho môi trường container. Bỏ sót bước cấu hình Next.js là lỗi phổ biến nhất khiến người mới deploy lần đầu bị kẹt.

• Một VPS chạy Ubuntu, có quyền truy cập root qua SSH – Coolify cần cài trực tiếp vào hệ điều hành, không chạy được trên hosting chia sẻ.
• Domain hoặc subdomain đã trỏ bản ghi A về IP của VPS (có thể trỏ sau khi cài Coolify xong, nhưng nên chuẩn bị trước để không mất thời gian chờ DNS propagate ở bước SSL).
• Source code Next.js đã đẩy lên repository trên GitHub hoặc GitLab – Coolify kéo code trực tiếp từ đây để build.
• Ứng dụng đã chạy được lệnh npm run build thành công ở máy local. Nếu build lỗi ở local, Coolify cũng sẽ lỗi y hệt, chỉ khác là khó debug hơn vì phải đọc log trong container.
• Nếu định dùng build pack Dockerfile (phần sau sẽ so sánh), file next.config.js cần thêm output: 'standalone' để Next.js xuất ra bản build gọn, chỉ chứa đúng file cần thiết cho runtime.
• Danh sách các biến môi trường ứng dụng cần, đặc biệt phân loại rõ biến nào có tiền tố NEXT_PUBLIC_ – phần này sẽ quyết định app chạy đúng hay sai ở bước sau.

Cài Đặt Coolify Trên VPS

Yêu cầu trước khi cài

Coolify tự cài Docker và các dependency cần thiết trong quá trình chạy script, nên bạn không cần cài Docker thủ công trước. Điều kiện thực tế là VPS chạy Ubuntu (khuyến nghị bản LTS), có kết nối internet ổn định để tải image, và đủ RAM để cả Coolify lẫn ứng dụng build cùng lúc – Next.js build thường nặng hơn lúc chạy runtime, nên nếu VPS cấu hình thấp, nên thử build thử một lần trước khi đưa vào production thay vì suy đoán con số cụ thể.

Chạy script cài đặt

SSH vào VPS với quyền root, rồi chạy script cài đặt chính thức của Coolify:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

Script sẽ tự cài Docker, kéo các image cần thiết và khởi động Coolify. Quá trình này mất vài phút tùy tốc độ mạng của VPS. Nếu bạn muốn xem chi tiết từng bước cài trên Ubuntu, tham khảo thêm hướng dẫn cách cài đặt Coolify trên Ubuntu của InterData.

Truy cập dashboard lần đầu

Sau khi script chạy xong, mở trình duyệt và truy cập http://IP-VPS-CUA-BAN:8000 để vào dashboard Coolify. Lần đầu vào, bạn tạo tài khoản admin, sau đó Coolify sẽ dẫn qua bước cấu hình “Server” – chính là VPS bạn vừa cài, để Coolify biết nơi triển khai container.

Trỏ Domain Và Cấu Hình SSL Tự Động Cho Coolify

Coolify dùng Traefik làm reverse proxy mặc định, không phải Nginx như nhiều hướng dẫn tự cấu hình VPS thủ công vẫn dùng. Vai trò thì giống nhau – điều hướng traffic từ domain vào đúng container ứng dụng – nhưng Traefik được Coolify tích hợp sẵn, tự động phát hiện container mới và cấp chứng chỉ SSL mà bạn không cần chỉnh file cấu hình bằng tay.

Để domain trỏ đúng, vào phần quản lý DNS của domain, tạo bản ghi A trỏ về IP VPS. Sau khi DNS đã propagate (kiểm tra bằng lệnh ping domain-cua-ban.com thấy đúng IP), vào Application trong Coolify, gán domain ở mục Domains, Coolify sẽ tự động gọi Let’s Encrypt để cấp SSL miễn phí qua Traefik, không cần thao tác thủ công như khi tự cấu hình Certbot.

Điểm hay bị bỏ sót: SSL chỉ cấp được khi domain đã thật sự phân giải đúng IP tại thời điểm Coolify gọi Let’s Encrypt. Gán domain quá sớm, lúc DNS chưa propagate xong, Coolify sẽ báo lỗi cấp SSL thất bại – cách xử lý đơn giản là đợi DNS ổn định rồi bấm cấp lại chứng chỉ trong Coolify, không cần cấu hình gì thêm.

Deploy Next.js Từ Git Repository Qua Coolify

Tạo Application mới

Trong dashboard, chọn Project rồi bấm “New Resource” > “Application”. Coolify hỗ trợ kết nối trực tiếp GitHub qua GitHub App (khuyến nghị, vì cho phép chọn đúng repo cần quyền truy cập thay vì cấp toàn bộ tài khoản), hoặc kết nối bằng Deploy Key cho repo private không muốn cài App. Sau khi chọn repo và branch, Coolify chuyển sang bước chọn build pack.

Bước 1: Tạo Project

Bước 2: Thêm Resouces

Chọn build pack: Nixpacks hay Dockerfile?

Đây là quyết định ảnh hưởng trực tiếp đến tốc độ build, dung lượng image và mức kiểm soát bạn có.

Nixpacks tự nhận diện Next.js và chạy build mà không cần bạn viết gì thêm phù hợp nếu bạn muốn deploy nhanh và không cần tối ưu sâu.

Dockerfile đòi hỏi bạn tự viết multi-stage build, nhưng cho image gọn hơn và kiểm soát rõ từng bước, đặc biệt hữu ích khi kết hợp với output: 'standalone' của Next.js.

Tiêu chí	Nixpacks	Dockerfile (standalone)
Thiết lập ban đầu	Không cần viết gì, tự nhận diện framework	Cần tự viết Dockerfile multi-stage
Dung lượng image	Thường lớn hơn do giữ nguyên node_modules đầy đủ	Gọn hơn nhờ standalone output chỉ copy file cần thiết
Kiểm soát build	Hạn chế, phụ thuộc cách Nixpacks tự suy luận	Toàn quyền: chọn base image, cache layer, bước build
Phù hợp với	Deploy nhanh, dự án đơn giản, mới bắt đầu với Coolify	Production nhiều traffic, cần image nhẹ và build ổn định lâu dài

Nếu chỉ deploy thử hoặc dự án cá nhân nhỏ, Nixpacks đủ dùng và tiết kiệm thời gian thiết lập. Với ứng dụng chạy production thật, đặc biệt khi định chạy nhiều app trên cùng một Coolify instance, Dockerfile với standalone output đáng đầu tư hơn – image nhẹ giúp deploy nhanh hơn và tốn ít tài nguyên hơn ở mỗi lần build.

So với việc tự cấu hình hạ tầng bằng tay, dưới đây là so sánh tổng quan để dễ hình dung Coolify đứng ở đâu:

Tiêu chí	Coolify (self-host)	Vercel	Tự cấu hình Nginx/PM2
Chi phí	Chỉ trả tiền VPS, không tính theo build/bandwidth	Miễn phí ở quy mô nhỏ, tăng theo build minutes/bandwidth	Chỉ trả tiền VPS, không phí phần mềm
SSL, domain	Tự động qua Traefik + Let’s Encrypt	Tự động, tích hợp sẵn	Tự cấu hình Certbot thủ công
Auto deploy khi push code	Có, qua webhook tích hợp sẵn	Có, mặc định	Phải tự viết script CI/CD
Thời gian thiết lập ban đầu	Trung bình – cài Coolify rồi kết nối repo	Rất nhanh, gần như không cấu hình	Lâu nhất, tự tay từng bước

Cấu Hình Biến Môi Trường Đúng Cách: Build-Time Vs Runtime

Lỗi biến môi trường NEXT_PUBLIC_* rỗng sau khi deploy là lỗi gặp nhiều nhất khi dùng Coolify với Next.js. Nguyên nhân: Next.js “nướng” các biến có tiền tố NEXT_PUBLIC_ thẳng vào bundle JavaScript ngay lúc chạy next build, không phải lúc container khởi động chạy runtime.

Trong Coolify, phần Environment Variables có hai loại: Runtime Variables (chỉ inject vào container lúc container start) và Build Variables (có mặt trong quá trình build image). Nếu bạn chỉ khai báo NEXT_PUBLIC_API_URL ở Runtime Variables mà quên bật cờ khả dụng lúc build, ứng dụng vẫn chạy bình thường, không báo lỗi gì – nhưng giá trị biến đó trong bundle client sẽ là chuỗi rỗng, vì lúc build không có nó.

Cách xử lý trong Coolify: khi thêm biến môi trường cho Application, bật tùy chọn đánh dấu biến đó khả dụng ở bước build (thường hiển thị dạng “Is Build Variable?” hoặc “Available at Buildtime” tùy phiên bản Coolify v4). Với mọi biến NEXT_PUBLIC_, luôn bật tùy chọn này – nếu không, dù set đúng giá trị ở Runtime, bundle vẫn không nhận được.

Nếu bạn dùng build pack Dockerfile tự viết thay vì Nixpacks, còn một bước nữa dễ bị bỏ sót: Nixpacks tự động truyền Build Variables của Coolify vào quá trình build, nhưng Dockerfile tự viết thì không tự động – bạn phải khai báo rõ trong Dockerfile:

ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL

RUN npm run build

Thiếu cặp ARG/ENV này, Coolify có set đúng Build Variable ở giao diện cũng vô nghĩa, vì Docker build stage không biết truyền giá trị đó vào đâu. Đây là điểm khác biệt thực tế giữa hai build pack mà nhiều hướng dẫn không nói tới.

Với biến không có tiền tố NEXT_PUBLIC_ – ví dụ connection string database dùng phía server – chỉ cần khai báo Runtime Variables là đủ, vì các biến này được đọc lúc chạy trong Server Components hoặc API Routes, không bị đóng cứng vào bundle client.

Thiết Lập Auto-Deploy Khi Push Code Lên GitHub

Coolify hỗ trợ tự động triển khai mỗi khi repository có code mới. Sau khi cấu hình webhook, mỗi lần bạn push code lên branch đang được Application sử dụng, GitHub sẽ gửi sự kiện đến Coolify. Coolify sau đó tự động lấy phiên bản code mới, build và deploy lại Application mà không cần nhấn Deploy thủ công.

Để thiết lập, trong Coolify hãy mở Application cần cấu hình, sau đó vào Webhooks. Tại phần Manual Git webhooks → GitHub, Coolify cung cấp hai thông tin cần thiết:

• Webhook URL: địa chỉ để GitHub gửi sự kiện push đến Coolify.
• Webhook secret: chuỗi bí mật dùng để xác thực webhook giữa GitHub và Coolify.

Tiếp theo, mở repository tương ứng trên GitHub và truy cập Settings → Webhooks → Add webhook. Tại đây, cấu hình như sau:

• Payload URL: dán Webhook URL lấy từ mục Manual Git webhooks → GitHub của Coolify.
• Content type: chọn application/json.
• Secret: dán chính xác Webhook secret được Coolify cung cấp.
• Events: chọn Just the push event.
• Active: bật để webhook bắt đầu hoạt động.

Sau đó nhấn Add webhook để hoàn tất. Từ lần push code tiếp theo lên branch được cấu hình cho Application, GitHub sẽ gửi sự kiện đến endpoint webhook và Coolify sẽ tự động kích hoạt quá trình build, deploy phiên bản mới.

Lưu ý: không sử dụng URL trong mục Deploy webhook làm Payload URL của GitHub. URL này dùng để kích hoạt deployment trực tiếp thông qua API hoặc các công cụ automation. Với GitHub, hãy sử dụng URL tại Manual Git webhooks → GitHub → Webhook URL.

Sau khi cấu hình, bạn có thể kiểm tra webhook tại GitHub → Settings → Webhooks → Recent Deliveries. Nếu request trả về mã HTTP 2xx và Coolify xuất hiện deployment mới trong Deployment Logs, Auto-Deploy đã hoạt động thành công.

Với dự án có nhiều môi trường như staging và production, nên tạo Application riêng cho từng branch tương ứng. Cách này giúp cấu hình Environment Variables, lịch sử deployment và quy trình rollback của từng môi trường được tách biệt, hạn chế deploy nhầm phiên bản lên production.

Xử Lý Lỗi Thường Gặp Khi Deploy Next.js Bằng Coolify

Build fail, thoát tiến trình đột ngột

Thường do VPS không đủ RAM cho quá trình build. Next.js build (đặc biệt với nhiều route, ảnh, hoặc dự án lớn) tốn RAM hơn hẳn lúc app chạy runtime bình thường. Cách xử lý nhanh nhất là thêm swap cho VPS để bù lúc build cần đỉnh RAM, sau đó theo dõi thực tế mức RAM tiêu thụ qua vài lần build để quyết định có cần nâng cấu hình VPS hay không – không nên đoán trước một con số cố định vì mức tiêu thụ phụ thuộc trực tiếp vào quy mô dự án.

Domain trả về lỗi 502 Bad Gateway

Phổ biến nhất là DNS chưa propagate xong tại thời điểm truy cập, hoặc bản ghi A trỏ sai IP. Kiểm tra bằng ping domain-cua-ban.com, đối chiếu đúng IP VPS. Nếu DNS đã đúng mà vẫn 502, kiểm tra container ứng dụng có đang chạy trong Coolify không – 502 nghĩa là Traefik nhận được request nhưng không kết nối được tới container phía sau, thường vì container đã crash hoặc chưa start xong.

SSL không tự cấp được

Let’s Encrypt yêu cầu domain đã phân giải đúng IP tại đúng thời điểm xác thực. Nếu bạn gán domain vào Application trước khi DNS propagate xong, Coolify sẽ báo lỗi cấp chứng chỉ. Đợi DNS ổn định (có thể mất từ vài phút đến vài giờ tùy nhà cung cấp domain), sau đó vào Coolify bấm cấp lại SSL, không cần cấu hình thêm gì khác.

Nên Chọn VPS Hay Cloud Server Để Chạy Coolify?

Nếu chỉ chạy một hoặc vài Next.js app trên một Coolify instance, VPS cấu hình khởi điểm là đủ – chi phí thấp, đáp ứng tốt phần lớn dự án cá nhân, landing page, hoặc dự án agency quy mô nhỏ. Vấn đề phát sinh khi bạn bắt đầu chạy nhiều app cùng lúc, hoặc traffic một trong số đó tăng đột biến: RAM và CPU trở thành giới hạn đầu tiên, đặc biệt lúc nhiều app build song song.

Tình huống sử dụng	Gợi ý	Lý do
1 app, traffic ổn định	VPS	Chi phí thấp, đủ tài nguyên cho nhu cầu cố định
Nhiều app/site trên cùng Coolify instance	Cloud Server	Dễ nâng RAM/CPU riêng lẻ khi thêm app, không phải đổi máy chủ
Traffic biến động mạnh theo thời điểm	Cloud Server	Nâng/hạ tài nguyên nhanh theo tải thực tế, không cần dự phòng dư thừa cố định

Nội dung mang tính tham khảo. Coolify là phần mềm mã nguồn mở của bên thứ ba, không phải sản phẩm của InterData. Cách cài đặt, giao diện và thông số có thể thay đổi theo phiên bản Coolify, Next.js và hệ điều hành thực tế. Nên kiểm thử, sao lưu dữ liệu và đánh giá rủi ro trước khi áp dụng cho production.