Published about 6 hours ago 17 min read

Hướng Dẫn Cài Đặt Và Sử Dụng Coolify Trên VPS Ubuntu

Nếu bạn từng triển khai các dự án vừa và nhỏ lên các nền tảng thương mại như Heroku, Vercel, Railway hay Render, chắc hẳn bạn đã trải qua cảm giác tiện lợi: chỉ cần git push là code tự động build, SSL tự cấp và database sẵn sàng sau vài cú click.

Tuy nhiên, khi dự án bắt đầu có traffic, số lượng container tăng lên hoặc cần lưu trữ database dung lượng lớn, hóa đơn hàng tháng từ các nền tảng này có thể tăng vọt theo số lượng serverless execution, bandwidth hay compute hours.

Giải pháp quen thuộc của dân kỹ thuật là chuyển về thuê một máy chủ ảo (VPS) trả phí cố định hàng tháng. Nhưng đi kèm với đó là gánh nặng vận hành: phải tự cài Nginx/Traefik reverse proxy, setup Certbot gia hạn SSL, cấu hình Docker Compose thủ công, quản lý firewall và viết script CI/CD qua GitHub Actions.

Đó là lý do Coolify v4 trở thành một trong những dự án mã nguồn mở phát triển nhanh nhất hiện nay. Coolify là một Self-hosted PaaS (Platform as a Service) mã nguồn mở, cho phép bạn biến một VPS Ubuntu thông thường thành một nền tảng cloud hoàn chỉnh tương tự Heroku/Vercel với giao diện web trực quan.

Trong bài viết này, mình sẽ hướng dẫn chi tiết cách cài đặt và sử dụng Coolify trên VPS Ubuntu (22.04 hoặc 24.04 LTS), cấu hình tường lửa, tối ưu Swap chống tràn RAM, quản lý biến môi trường và triển khai ứng dụng thực tế.

1. Yêu cầu hệ thống & Lựa chọn phần cứng VPS

Coolify chạy trực tiếp trên Docker Engine và điều phối các container ứng dụng, database và reverse proxy (Traefik). Để hệ thống hoạt động ổn định, bạn cần lưu ý thông số phần cứng:

Bảng cấu hình khuyến nghị

Thành phần	Mức tối thiểu (Thử nghiệm)	Mức khuyến nghị (Production)	Ghi chú
CPU	2 vCPU	2 – 4 vCPU	Kiến trúc x86_64 (AMD64) hoặc ARM64
RAM	2 GB	4 GB – 8 GB	Build app Node.js/Next.js tiêu tốn nhiều RAM
Ổ cứng	20 GB SSD/NVMe	40 GB – 80 GB NVMe	Docker images & build cache tốn dung lượng
Hệ điều hành	Ubuntu 22.04 / 24.04 LTS	Ubuntu 22.04 / 24.04 LTS	Cài mới (Fresh OS), không cài sẵn Snap Docker

Lưu ý thực tế: Nếu bạn chọn VPS chỉ có 1GB RAM, tiến trình build của Coolify (sử dụng Nixpacks hoặc Docker BuildKit) gần như chắc chắn sẽ bị Linux Kernel kích hoạt OOM Killer (Out of Memory) dừng tiến trình ngay lập tức. Mức 2GB RAM là điểm sàn, nhưng bắt buộc phải tạo thêm Swap file.

Để Coolify và các container build ổn định, bạn nên chuẩn bị một VPS sạch chạy Ubuntu 22.04/24.04 với tối thiểu 2 vCPU và 2GB RAM (tốt nhất là 4GB nếu chạy cả Database). Nếu bạn đang tìm kiếm một nhà cung cấp trong nước có hạ tầng ổn định, ổ cứng NVMe tốc độ cao để triển khai dự án, bạn có thể Tham Khảo Các Gói Thuê VPS Giá Tốt của InterData – nơi mình đang làm việc, hoặc chủ động lựa chọn bất kỳ nhà cung cấp nào khác phù hợp với chi phí của bạn.

2. Chuẩn bị môi trường VPS & Cấu hình Firewall

Sau khi khởi tạo VPS và kết nối qua SSH bằng quyền root hoặc user có quyền sudo, chúng ta tiến hành chuẩn bị hệ thống.

# Cập nhật index gói và nâng cấp hệ thống
sudo apt update && sudo apt upgrade -y

# Cài đặt một số công cụ bổ trợ cần thiết
sudo apt install -y curl wget git jq ufw htop

Thiết lập Swap Memory chống lỗi OOM (Bắt buộc cho VPS 2GB RAM)

Khi bạn deploy các ứng dụng viết bằng TypeScript, Next.js hay Laravel, quá trình biên dịch (compile/bundle) sẽ đẩy mức tiêu thụ RAM lên đỉnh điểm trong thời gian ngắn. Thiết lập 2GB – 4GB Swap trên ổ cứng SSD/NVMe giúp server không bị crash.

# 1. Kiểm tra dung lượng Swap hiện tại
sudo swapon --show

# 2. Tạo file swap 4GB (nếu chưa có swap)
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 3. Giữ swap cố định sau mỗi lần reboot
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# 4. Tối ưu swappiness (chỉ dùng swap khi RAM thực sắp hết)
sudo sysctl vm.swappiness=10
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf

Cấu hình Tường lửa (Firewall UFW)

Coolify yêu cầu mở một số cổng mạng đặc thù để điều khiển container, cấp SSL và quản lý terminal. Dưới đây là danh sách các cổng cần thiết:

22/TCP: Kết nối SSH.
80/TCP: Nhận traffic HTTP và giải quyết ACME Challenge (Let's Encrypt SSL).
443/TCP: Nhận traffic HTTPS bảo mật.
8000/TCP: Giao diện Dashboard quản trị Coolify (Ban đầu).
6001/TCP: Kết nối WebSocket / Soketi (Đẩy build logs và thông báo thời gian thực).
6002/TCP: Coolify Web Terminal (Truy cập console của container trực tiếp từ trình duyệt).

Thao tác cấu hình tường lửa bằng UFW:

# Cho phép SSH trước tiên để tránh bị mất kết nối
sudo ufw allow 22/tcp

# Mở các cổng dịch vụ web và SSL
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Mở các cổng điều khiển của Coolify
sudo ufw allow 8000/tcp
sudo ufw allow 6001/tcp
sudo ufw allow 6002/tcp

# Kích hoạt tường lửa
sudo ufw --force enable
sudo ufw status

3. Cài đặt Coolify bằng Script chính thức

Coolify cung cấp một script cài đặt tự động. Script này sẽ kiểm tra phần cứng, tự động cài Docker Engine phiên bản mới nhất từ repository chính thống của Docker (không dùng bản Snap có thể gây lỗi permission), tạo thư mục /data/coolify và kéo các container hạ tầng về chạy.

Chạy lệnh sau trên terminal của VPS:

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

Quá trình cài đặt mất khoảng 2 – 5 phút tùy thuộc vào tốc độ mạng và hiệu năng I/O của ổ cứng.

.......................................................
Coolify installation completed!
Please visit http://<IP-VPS>:8000 to complete the onboarding process.
.......................................................

Cảnh báo bảo mật quan trọng ngay sau khi cài đặt

Ngay khi script thông báo hoàn tất, hãy mở trình duyệt và truy cập ngay vào:

http://<IP_VPS_CỦA_BẠN>:8000

CẢNH BÁO: Instance Coolify mới dựng chưa hề có tài khoản quản trị. Bất kỳ ai truy cập đầu tiên vào địa chỉ http://<IP_VPS>:8000 đều có thể đăng ký tài khoản và nắm toàn quyền điều khiển (Root) máy chủ của bạn. Do đó, bạn cần tạo tài khoản Admin ngay lập tức.

Điền thông tin tài khoản:

Name: Tên của bạn.
Email: Email quản trị.
Password: Mật khẩu phức tạp (nên gồm chữ hoa, chữ thường, số và ký tự đặc biệt).

4. Cấu hình Domain cho Coolify Dashboard & Sao lưu Secrets

Sau khi tạo xong tài khoản Admin, bạn sẽ được đưa vào giao diện Dashboard. Việc tiếp theo cần làm là gắn một domain riêng (ví dụ: coolify.yourdomain.com) cho Dashboard và kích hoạt HTTPS, thay vì dùng port 8000 không mã hóa.

Gắn Domain cho Dashboard

Truy cập vào phần Settings -> Instance.
Tại mục Custom Domain (FQDN), nhập domain bạn muốn dùng: https://coolify.yourdomain.com.
Trỏ bản ghi A của domain coolify.yourdomain.com trên DNS Manager (Cloudflare, Route53, Namecheap...) về IP của VPS.
Bấm Save. Coolify thông qua Traefik proxy sẽ tự động yêu cầu Let's Encrypt cấp chứng chỉ SSL. Sau khoảng 30–60 giây, bạn có thể truy cập dashboard trực tiếp qua https://coolify.yourdomain.com.

(Tùy chọn nâng cao): Sau khi đã truy cập an toàn qua HTTPS bằng domain, bạn có thể đóng cổng 8000 trên firewall để tăng tính bảo mật:

sudo ufw delete allow 8000/tcp

Sao lưu file `.env` quan trọng nhất của hệ thống

Toàn bộ thông tin cấu hình, database nội bộ và đặc biệt là khóa mã hóa APP_KEY của Coolify được lưu tại:

/data/coolify/source/.env

Nếu mất APP_KEY, bạn sẽ không thể giải mã các biến môi trường, private SSH key hoặc mật khẩu database đã lưu trong hệ thống khi cần restore. Hãy sao lưu file này về máy cá nhân:

# Xem nội dung file cấu hình gốc
sudo cat /data/coolify/source/.env

Lưu trữ chuỗi APP_KEY cẩn thận trong trình quản lý mật khẩu của bạn.

5. Thực hành: Triển khai Ứng dụng Web (Git Push to Deploy)

Bây giờ chúng ta sẽ đi vào phần quan trọng nhất: Deploy một ứng dụng thực tế. Coolify hỗ trợ hầu hết các framework phổ biến: Node.js/Next.js, Laravel/PHP, Python (FastAPI/Django), Go, Rust, Ruby on Rails...

Bước 1: Tạo Project và Environment

Tại thanh điều hướng bên trái, chọn Projects -> + Add.
Đặt tên Project: production-apps.
Chọn Environment mặc định là production.

Bước 2: Kết nối Source Code

Bấm + New Resource -> Chọn Public Repository hoặc GitHub App (đối với repository private).

Nếu dùng Public Repo, bạn dán link Git repository của mình vào:

https://github.com/username/my-nextjs-app

Chọn branch cần deploy (ví dụ: main).

Bước 3: Cấu hình Build Pack

Coolify cung cấp 3 cơ chế build chính:

Nixpacks (Khuyến nghị): Tương tự cơ chế của Railway/Heroku, tự động phân tích mã nguồn (package.json, composer.json, requirements.txt) để cài đặt runtime và build tự động mà không cần viết Dockerfile.
Dockerfile: Tận dụng file Dockerfile có sẵn trong root repository.
Docker Compose: Dành cho ứng dụng đa container phức tạp.

Nếu bạn chưa có Dockerfile, cứ giữ nguyên tùy chọn Nixpacks.

Bước 4: Cấu hình Biến môi trường (Build-time vs Runtime)

Đây là phần rất nhiều developer hay bị nhầm lẫn dẫn đến lỗi build trắng trang hoặc không nhận API URL.

Coolify phân định rõ hai loại biến môi trường:

Runtime Variables: Biến môi trường chỉ được nạp khi container chạy (ví dụ: DATABASE_URL, JWT_SECRET, REDIS_HOST).
Build-time Variables: Biến môi trường cần thiết ngay trong lúc chạy lệnh build (ví dụ: NEXT_PUBLIC_API_URL của Next.js, VITE_BACKEND_URL của Vite).

Tại tab Environment Variables:

Nhập tên biến và giá trị.
Nếu là biến cần cho quá trình compile giao diện (như Next.js static generation), tích chọn ô Build Variable.

# Ví dụ cấu hình biến môi trường
NODE_ENV=production
DATABASE_URL=postgresql://user:password@postgres-db:5432/app_db
NEXT_PUBLIC_API_URL=https://api.yourdomain.com   # (Nhớ bật tích Build Variable)

Bước 5: Gán Tên miền và Triển khai

Tại tab General, mục Domains, nhập URL hoàn chỉnh kèm giao thức https://:
```
https://app.yourdomain.com
```
Đảm bảo bản ghi DNS (A record) của app.yourdomain.com đã trỏ về IP của VPS.
Bấm nút Deploy ở góc trên bên phải.

Bạn có thể theo dõi tiến trình build thời gian thực thông qua tab Build Logs. Khi log báo trạng thái Container is healthy, ứng dụng đã live trên Internet với SSL Let's Encrypt được kích hoạt hoàn toàn tự động.

6. Tạo Database & Dịch vụ với 1-Click (Internal Network)

Coolify cho phép khởi tạo nhanh các hệ quản trị cơ sở dữ liệu phổ biến như PostgreSQL, MySQL, Redis, MongoDB, ClickHouse.

Các bước tạo Database:

Trong Project của bạn, chọn + New Resource -> Databases.
Chọn loại DB cần dùng (ví dụ: PostgreSQL).
Coolify sẽ tự sinh ngẫu nhiên Database Name, User, Password và Root Password.

DB Name: defaultdb
DB User: coolify_user
DB Password: <random_generated_string>

Tư duy kết nối qua Docker Internal Network

Một lỗi bảo mật phổ biến khi dùng VPS là mở public cổng Database (như 5432, 3306) ra toàn Internet.

Trong Coolify, tất cả các Resource nằm trong cùng một Environment sẽ được kết nối chung vào một Docker Bridge Network. Điều này đồng nghĩa:

Ứng dụng backend của bạn có thể kết nối trực tiếp với Database qua Hostname nội bộ (Internal URL) mà không cần mở bất kỳ port DB nào ra ngoài.

Tại giao diện cấu hình Database, bạn sẽ thấy mục Internal URL:

postgresql://coolify_user:secretpass@postgresql-db-service-name:5432/defaultdb

Chỉ cần copy chuỗi kết nối nội bộ này dán vào biến DATABASE_URL của ứng dụng backend, kết nối sẽ hoàn toàn khép kín, an toàn và có độ trễ cực thấp.

7. Troubleshooting: Xử lý các sự cố thường gặp

Trong quá trình vận hành Coolify trên VPS Ubuntu, bạn có thể gặp một số tình huống kỹ thuật sau:

Lỗi 1: Build bị dừng đột ngột (Exit Code 137 - OOM Killed)

Hiện tượng: Quá trình build ứng dụng Node/Next.js/Rust đang chạy thì văng ra, log không báo lỗi cú pháp mà dừng đột ngột.
Nguyên nhân: Thiếu RAM vật lý và chưa cấu hình Swap, khiến tiến trình bị Linux Kernel chấm dứt (Sigkill 137).
Cách khắc phục: Kiểm tra lại dung lượng swap bằng lệnh free -m. Nếu swap bằng 0, hãy thực hiện lại các bước tạo Swap 4GB ở Phần 2.

Lỗi 2: Không thể cấp chứng chỉ SSL (Let's Encrypt Failed)

Hiện tượng: Domain truy cập qua http:// được nhưng https:// báo lỗi chứng chỉ không hợp lệ.
Nguyên nhân:
1. Bản ghi DNS chưa được cập nhật đầy đủ (DNS propagation delay).
2. Cổng 80 hoặc 443 bị chặn bởi tường lửa UFW hoặc Security Group của nhà cung cấp VPS. Let's Encrypt bắt buộc phải truy cập được port 80 để giải quyết ACME HTTP-01 challenge.

Cách khắc phục:

# Kiểm tra xem port 80 và 443 có đang LISTEN không
sudo netstat -tlpn | grep -E ':(80|443)'

# Đảm bảo UFW cho phép traffic HTTP/HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Lỗi 3: Không mở được Web Terminal (Container Shell)

Hiện tượng: Bấm vào nút "Terminal" trong giao diện ứng dụng trên Coolify thì màn hình đen xì hoặc báo lỗi kết nối socket.
Nguyên nhân: Cổng 6002 (cổng dành cho terminal service của Coolify) chưa được mở trên firewall.

Cách khắc phục:

sudo ufw allow 6002/tcp
sudo ufw reload

Lỗi 4: Xung đột Docker nếu từng cài Docker qua Snap

Hiện tượng: Script cài đặt báo lỗi không thể khởi động Docker daemon hoặc gặp lỗi permission socket.
Nguyên nhân: Hệ thống Ubuntu trước đó đã cài đặt gói docker thông qua Snap Store (snap install docker), gây xung đột nghiêm trọng với Docker Engine chính thức từ Docker APT Repository.

Cách khắc phục:

# Gỡ bỏ hoàn toàn Docker bản Snap
sudo snap remove docker

# Sau đó chạy lại script cài đặt của Coolify
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

8. Đánh giá Ưu & Nhược điểm khi tự host với Coolify

Sau nhiều dự án triển khai thực tế, mình rút ra một số góc nhìn khách quan về việc sử dụng Coolify thay thế các nền tảng thương mại:

Ưu điểm

Tối ưu chi phí: Bạn chỉ trả chi phí cố định cho phần cứng VPS. Bạn có thể deploy 5–10 ứng dụng, nhiều cơ sở dữ liệu cùng lúc trên một server mà không phát sinh thêm phí.
Toàn quyền kiểm soát (Full Control): Dữ liệu nằm hoàn toàn trên hạ tầng của bạn, không bị vendor lock-in.
Hỗ trợ đa dạng: Tự động cấu hình Traefik reverse proxy, SSL tự động, backup database tự động lên S3/R2 storage, hỗ trợ Git Webhook (push to deploy).

Nhược điểm & Trách nhiệm

Phải tự chịu trách nhiệm vận hành: Bạn phải tự theo dõi tài nguyên VPS, cấu hình backup định kỳ và update OS/Docker khi có bản vá bảo mật.
Không có tính năng Auto-scaling đa cụm máy chủ tự động: Khác với mô hình serverless của Vercel có thể mở rộng hàng nghìn instance trong giây lát, VPS của bạn chỉ scale theo dạng Vertical Scaling (nâng cấp CPU/RAM của chính VPS đó).

9. Tổng kết

Coolify v4 đã rút ngắn đáng kể khoảng cách giữa việc tự quản trị VPS truyền thống và trải nghiệm mượt mà của các nền tảng PaaS hiện đại. Chỉ với một máy chủ Ubuntu sạch, bạn hoàn toàn có thể tự dựng một private cloud hoàn chỉnh, phục vụ tốt cho cả môi trường staging lẫn production vừa và nhỏ.

Hy vọng bài viết giúp bạn tiết kiệm thời gian thiết lập hạ tầng và tự tin làm chủ hệ thống của mình. Nếu gặp bất kỳ vướng mắc nào trong quá trình cài đặt và cấu hình, bạn hãy để lại bình luận bên dưới, mình và mọi người sẽ cùng thảo luận và hỗ trợ nhé!

1. Yêu cầu hệ thống & Lựa chọn phần cứng VPS

Bảng cấu hình khuyến nghị

2. Chuẩn bị môi trường VPS & Cấu hình Firewall

Thiết lập Swap Memory chống lỗi OOM (Bắt buộc cho VPS 2GB RAM)

Cấu hình Tường lửa (Firewall UFW)

3. Cài đặt Coolify bằng Script chính thức

Cảnh báo bảo mật quan trọng ngay sau khi cài đặt

4. Cấu hình Domain cho Coolify Dashboard & Sao lưu Secrets

Gắn Domain cho Dashboard

Sao lưu file .env quan trọng nhất của hệ thống

5. Thực hành: Triển khai Ứng dụng Web (Git Push to Deploy)

Bước 1: Tạo Project và Environment

Bước 2: Kết nối Source Code

Bước 3: Cấu hình Build Pack

Bước 4: Cấu hình Biến môi trường (Build-time vs Runtime)

Bước 5: Gán Tên miền và Triển khai

6. Tạo Database & Dịch vụ với 1-Click (Internal Network)

Các bước tạo Database:

Tư duy kết nối qua Docker Internal Network

7. Troubleshooting: Xử lý các sự cố thường gặp

Lỗi 1: Build bị dừng đột ngột (Exit Code 137 - OOM Killed)

Lỗi 2: Không thể cấp chứng chỉ SSL (Let's Encrypt Failed)

Lỗi 3: Không mở được Web Terminal (Container Shell)

Lỗi 4: Xung đột Docker nếu từng cài Docker qua Snap

8. Đánh giá Ưu & Nhược điểm khi tự host với Coolify

Ưu điểm

Nhược điểm & Trách nhiệm

9. Tổng kết

Table of contents

Sao lưu file `.env` quan trọng nhất của hệ thống