Hướng Dẫn Cài Đặt và Sử Dụng Dokploy Trên VPS: Chi Tiết Từng Bước Từ A-Z

Việc cài đặt và sử dụng Dokploy trên máy chủ riêng giúp lập trình viên và doanh nghiệp làm chủ hoàn toàn hạ tầng triển khai mà không phải chịu chi phí đắt đỏ từ các nền tảng thương mại như Vercel hay Heroku. Khi triển khai Dokploy trên nền tảng máy chủ của InterData, bạn có toàn quyền quản trị tài nguyên phần cứng, dữ liệu và tiến trình CI/CD với hiệu năng ổn định. Bài viết này sẽ hướng dẫn chi tiết từng bước thiết lập Dokploy từ dòng lệnh đến khi vận hành thực tế.

Dokploy là gì? Tại sao không dùng Vercel hay Heroku?

Dokploy là giải pháp self-hosted PaaS mã nguồn mở, hoạt động trực tiếp trên nền tảng Docker Swarm kết hợp Traefik để tự động hóa việc build, deploy và điều hướng lưu lượng mạng cho ứng dụng web.

Dokploy cho phép lập trình viên biến một máy chủ Linux thông thường thành môi trường PaaS hoàn chỉnh có giao diện quản lý đồ họa trực quan.

Khi sử dụng các nền tảng thương mại như Vercel hay Heroku, chi phí thường tăng phi mã theo lượng băng thông tiêu thụ, số lượng thành viên nhóm và thời gian chạy serverless functions.

Bạn cũng bị giới hạn bởi thời gian timeout của request, thiếu quyền can thiệp nhân hệ thống và không thể tùy biến các cấu hình mạng tầng sâu.

Dokploy giải quyết triệt để rào cản này bằng cách đưa toàn bộ quyền kiểm soát máy chủ về tay bạn, với chi phí cố định theo giá thuê VPS hàng tháng.

Nền tảng này tích hợp sẵn Traefik để tiếp nhận request và cấp phát chứng chỉ SSL tự động. Để hiểu rõ cơ chế định tuyến bên dưới, bạn có thể tham khảo bài phân tích Reverse Proxy là gì của InterData.

Dokploy phù hợp cho cá nhân, freelancer, lập trình viên full-stack và các startup muốn xây dựng hệ thống triển khai tự động ổn định nhưng cần tiết kiệm tối đa ngân sách vận hành hạ tầng.

So Sánh Dokploy vs Coolify vs CapRover: Chọn Cái Nào?

Thị trường PaaS nguồn mở hiện có ba cái tên nổi bật: Dokploy, Coolify và CapRover. Mỗi công cụ phục vụ một triết lý thiết kế và quy mô hạ tầng riêng biệt, đòi hỏi người dùng cân nhắc kỹ lưỡng cấu hình phần cứng trước khi lựa chọn.

Nếu bạn sở hữu VPS cấu hình vừa phải (1GB đến 2GB RAM) và cần sự gọn gàng, Dokploy là ứng viên sáng giá. Nếu bạn cần hệ sinh thái đồ sộ với hàng trăm template có sẵn, hãy cân nhắc cách cài Coolify trên Ubuntu.

Đối với các dự án JavaScript hiện đại cần scale nhiều container, bạn cũng có thể xem thêm hướng dẫn deploy Next.js lên VPS bằng Coolify để so sánh trực tiếp hiệu quả quản lý giữa hai công cụ.

Yêu Cầu Hệ Thống Trước Khi Cài Đặt Dokploy

Để đảm bảo Dokploy hoạt động mượt mà, máy chủ cần đáp ứng các điều kiện tiêu chuẩn về thông số phần cứng và môi trường mạng:

• Hệ điều hành: Khuyến nghị dùng Ubuntu 22.04 LTS hoặc Ubuntu 24.04 LTS. Nền tảng cũng hỗ trợ Debian 11/12, CentOS Stream 9 và Fedora.
• CPU & RAM: Tối thiểu 1 vCPU và 2GB RAM cho môi trường staging hoặc thử nghiệm. Khuyến nghị từ 2 vCPU và 4GB RAM trở lên đối với môi trường production có chạy cơ sở dữ liệu.
• Ổ cứng: Tối thiểu 30GB dung lượng trống chuẩn SSD NVMe để chứa Docker image layers, database volumes và logs ứng dụng.
• Cổng mạng (Ports): Đảm bảo các cổng 80 (HTTP), 443 (HTTPS) và 3000 (Dokploy Dashboard) không bị chiếm dụng bởi các tiến trình web server khác.
• Quyền hạn: Tài khoản root hoặc tài khoản có quyền thực thi lệnh sudo qua kết nối SSH.

Dokploy sẽ tự động tải và cấu hình Docker nếu máy chủ chưa có sẵn. Dù vậy, việc nắm chắc quy trình chuẩn hóa container từ bài hướng dẫn cài đặt Docker trên Ubuntu sẽ giúp bạn chủ động hơn khi tinh chỉnh hệ thống về sau.

Hướng Dẫn Cài Đặt và Sử Dụng Dokploy Trên VPS Ubuntu Từng Bước

Quy trình cài đặt Dokploy diễn ra tự động thông qua script chính thức từ nhà phát triển. Dưới đây là các bước thao tác chuẩn xác từ terminal của bạn.

1/ Đăng nhập vào VPS qua SSH

Mở terminal máy tính cá nhân và kết nối vào máy chủ bằng tài khoản có quyền quản trị cao nhất:

ssh root@your-vps-ip

> Xem thêm: Cách Đăng Nhập VPS Trên Máy Tính

2/ Cập nhật danh sách gói hệ thống

Đồng bộ các bản vá mới nhất của hệ điều hành trước khi cấu hình:

sudo apt update && sudo apt upgrade -y

3/ Thực thi script cài đặt Dokploy

Chạy một dòng lệnh duy nhất để tải và cài đặt toàn bộ thành phần phụ thuộc:

curl -sSL https://dokploy.com/install.sh | sh

Script này tự động kiểm tra Docker, kích hoạt Docker Swarm mode và khởi động cụm container quản trị gồm Traefik và Dokploy core.

4/ Mở cổng tường lửa UFW

Nếu VPS của bạn đang bật tường lửa, hãy mở các cổng dịch vụ cần thiết:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3000/tcp
sudo ufw reload

> Xem Thêm: Hướng Dẫn Cài Đặt Và Cấu Hình UFW Trên Ubuntu Chi Tiết Từ A-Z

5/ Truy cập Dashboard

Mở trình duyệt web và điều hướng tới địa chỉ:

http://your-vps-ip:3000

6/ Tạo tài khoản quản trị đầu tiên

Điền thông tin họ tên, địa chỉ email và mật khẩu quản trị để thiết lập quyền truy cập master cho cụm Dokploy.

Lưu ý cấu hình cho máy chủ Debian và hạ tầng mạng nhiều IP

Trên Debian 11 hoặc 12, quy trình thực hiện tương tự vì hệ điều hành này sử dụng chung trình quản lý gói apt. Trong trường hợp VPS của bạn có nhiều card mạng hoặc script nhận diện sai IP công khai khiến Docker Swarm không thể giao tiếp, hãy ép tham số IP công khai thông qua biến môi trường sau:

curl -sSL https://dokploy.com/install.sh | sudo ADVERTISE_ADDR=your-public-ip sh

Cách Triển Khai Ứng Dụng Khi Cài Đặt và Sử Dụng Dokploy

Sau khi hoàn tất đăng nhập, Dokploy phân chia tài nguyên theo cấu trúc Projects (Dự án). Bạn có thể triển khai từ mã nguồn Git, file cấu hình Compose hoặc database độc lập.

1. Triển khai ứng dụng trực tiếp từ Git Repository

Dokploy hỗ trợ kéo mã nguồn trực tiếp từ GitHub, GitLab hoặc bất kỳ Git URL công khai nào.

1. Tại màn hình Dashboard, nhấn Create Project và đặt tên cho dự án của bạn.
2. Bên trong Project, chọn Add Service > Application.
3. Tại mục Provider, chọn Git hoặc liên kết với tài khoản GitHub đã phân quyền. Nhập URL của repository và nhánh mã nguồn (ví dụ: main).
4. Chọn Build Type: Dokploy cung cấp hai lựa chọn cốt lõi:
   • Nixpacks: Tự động nhận diện ngôn ngữ lập trình (Node.js, Python, PHP, Golang, Rust) và tạo image tối ưu mà không cần Dockerfile.
   • Dockerfile: Đọc trực tiếp từ file Dockerfile sẵn có trong source code để người dùng toàn quyền kiểm soát build step.
5. Chuyển qua tab Domains, nhập tên miền (ví dụ: app.yourdomain.com), trỏ A record của domain về IP máy chủ VPS và kích hoạt tùy chọn HTTPS.
6. Nhấn Deploy. Dokploy sẽ tiến hành clone mã nguồn, chạy build, khởi chạy container và tự động gắn SSL qua Traefik.

2. Triển khai ứng dụng qua Docker Compose

Nếu dự án bao gồm nhiều service liên kết chặt chẽ (như Web App + Worker + Cache), tính năng Compose tích hợp sẽ mang lại sự thuận tiện tối đa.

Vào Project > Add Service > chọn Compose. Hệ thống sẽ mở ra một trình soạn thảo YAML trực quan trên giao diện web. Bạn chỉ cần dán cấu hình tiêu chuẩn vào đây:

version: '3.8'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    restart: always
  cache:
    image: redis:7-alpine
    restart: always

Kỹ năng quản lý các định dạng khai báo này rất quan trọng khi cấu trúc hệ thống lớn. Bạn có thể tham khảo bài cài đặt và sử dụng Docker Compose để nắm bắt cú pháp khai báo networks và volumes chuyên sâu.

3. Cài đặt Database độc lập (PostgreSQL, Redis, MongoDB)

Dokploy cho phép khởi tạo dịch vụ cơ sở dữ liệu production chỉ với vài cú nhấp chuột mà không cần viết file compose thủ công:

1. Chọn Add Service > chọn loại Database: PostgreSQL, MySQL, MariaDB, MongoDB hoặc Redis.
2. Nhập thông tin xác thực gồm Database Name, Username và Root Password.
3. Nhấn Deploy. Dokploy tự động tạo volume gắn ngoài để duy trì dữ liệu liên tục kể cả khi container khởi động lại.

Lưu ý quan trọng: Khi kết nối database với ứng dụng nằm trong cùng một Project Dokploy, hãy sử dụng tên service nội bộ của database làm hostname (ví dụ: postgres-service) thay vì dùng localhost hay IP máy chủ.

Thiết Lập Auto-Deploy Từ GitHub Với Dokploy

Để tối ưu chu trình phát triển phần mềm theo tiêu chuẩn CI/CD hiện đại, bạn cần thiết lập để mỗi khi có commit mới đẩy lên repository, Dokploy sẽ tự động kích hoạt tiến trình build mới.

1. Sử dụng GitHub App chính thức (Khuyên dùng)

Đây là giải pháp an toàn và liền mạch nhất. Trên giao diện Dokploy, điều hướng tới Settings > Git Providers > chọn GitHub và bấm nút cài đặt GitHub App. Bạn sẽ được chuyển hướng tới GitHub để chọn các repository muốn cấp quyền cho Dokploy. Sau khi hoàn tất, hệ thống tự động gán webhook mà không cần thao tác thủ công.

2. Cấu hình Webhook thủ công

Nếu bạn sử dụng repository riêng lẻ hoặc hệ thống Git tự host:

1. Truy cập vào ứng dụng trên Dokploy, tìm đến tab Deployments và sao chép đường dẫn Webhook URL.
2. Đăng nhập GitHub, vào repository cần thiết lập > chọn Settings > Webhooks > Add webhook.
3. Dán link vào mục Payload URL.
4. Mục Content type, bắt buộc phải chọn application/json.
5. Tại phần trigger, chọn Just the push event rồi nhấn Add webhook.

3. Tích hợp GitHub Actions qua Dokploy API

Trong các dự án lớn cần chạy unit test hoặc sonarqube trước khi deploy, bạn nên dùng GitHub Actions để kiểm thử, sau đó mới gửi lệnh deploy sang Dokploy:

1. Vào Dokploy Dashboard > Settings > API Keys > tạo một key mới.
2. Trên GitHub Repository, lưu key này vào Settings > Secrets and variables > Actions với tên DOKPLOY_API_KEY.
3. Thêm bước kích hoạt vào cuối file .github/workflows/deploy.yml:

name: Trigger Dokploy Deploy
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Webhook
        run: |
          curl -X POST "${{ secrets.DOKPLOY_WEBHOOK_URL }}" \
               -H "Authorization: Bearer ${{ secrets.DOKPLOY_API_KEY }}"

Khi kiểm tra các lỗi phát sinh trong luồng build này, việc thông thạo các lệnh Docker thông dụng sẽ giúp bạn truy vết log và tiến trình của build runner một cách nhanh chóng.

Bảo Mật và Tối Ưu Sau Khi Cài Đặt và Sử Dụng Dokploy Xong

Sau khi hệ thống đã vận hành trơn tru, việc bảo vệ máy chủ khỏi các rủi ro an ninh mạng và duy trì tính ổn định dịch vụ là bắt buộc.

1. Đặt Domain riêng cho Dashboard và đóng Port 3000

Theo mặc định, cổng 3000 để mở ngoài Internet là một điểm yếu bảo mật tiềm ẩn. Bạn nên gán domain cho giao diện Dokploy qua Traefik với chứng chỉ SSL, sau đó khóa cổng 3000 ở tầng firewall:

1. Truy cập Dokploy > Settings > Server Domain > điền domain quản trị (ví dụ: manage.yourdomain.com) và kích hoạt Let’s Encrypt.
2. Kiểm tra đăng nhập thành công qua giao diện HTTPS tại domain mới.
3. Khóa cổng 3000 trên tường lửa UFW:

   sudo ufw delete allow 3000/tcp
   sudo ufw reload

2. Thiết lập quy chuẩn bảo mật VPS

Hạ tầng máy chủ bên dưới cần được thiết lập cơ chế khóa cổng SSH root, chuyển cổng mặc định 22 sang cổng khác và cài đặt fail2ban. Bạn cần tuân thủ lộ trình chuẩn tại bài viết hướng dẫn bảo mật VPS sau khi cài đặt để bảo vệ các ứng dụng đang chạy bên trong.

3. Tùy chọn Reverse Proxy và giải pháp cấp phát SSL

Mặc dù Traefik được Dokploy điều khiển tự động rất tiện lợi, nhưng đối với các hạ tầng cần custom rewrite quy mô lớn hoặc kết hợp nhiều backend phức tạp, một số kỹ sư vẫn ưu tiên cấu hình Nginx đứng trước.

Khi đó, bạn có thể tham khảo hướng dẫn cấu hình Nginx Reverse Proxy để chuyển tiếp request vào các container Swarm.

Đồng thời, nếu gặp tình huống Traefik không thể cấp phát SSL do lỗi DNS cluster, việc hiểu cách cài SSL Let’s Encrypt bằng Certbot thủ công sẽ cung cấp cho bạn phương án dự phòng chuẩn xác.

4. Giám sát tính sẵn sàng của ứng dụng

Để nhận cảnh báo sự cố máy chủ kịp thời qua Telegram hoặc Discord, bạn nên tiến hành cài đặt Uptime Kuma để giám sát uptime.

Uptime Kuma có thể được deploy trực tiếp như một Compose service ngay trên Dokploy để kiểm tra tính sẵn sàng của các container khác trong hệ thống.

Xử Lý Lỗi Thường Gặp Khi Cài Đặt và Sử Dụng Dokploy

Dưới đây là 4 lỗi kỹ thuật phổ biến nhất được ghi nhận trong quá trình triển khai thực tế cùng giải pháp xử lý triệt để:

1. Không vào được Dashboard tại địa chỉ IP:3000

Triệu chứng: Trình duyệt báo lỗi “Connection timed out” hoặc “Unable to connect” khi truy cập http://vps-ip:3000.

Nguyên nhân: Do dịch vụ Dokploy chưa hoàn tất khởi động hoặc tường lửa của hệ điều hành/nhà cung cấp đang chặn cổng 3000.

Cách xử lý: Kiểm tra trạng thái của các container và log tiến trình bằng các lệnh sau:

# Kiểm tra danh sách service của Docker Swarm
docker service ls

# Xem chi tiết log khởi động của Dokploy
docker service logs dokploy --tail 50

# Kiểm tra trạng thái tường lửa UFW
sudo ufw status

2. Cổng 3000 bị ứng dụng khác chiếm dụng từ trước

Triệu chứng: Script cài đặt xuất hiện cảnh báo Port 3000 is already in use.

Nguyên nhân: Có một tiến trình Node.js, Grafana hoặc AdGuard Home đang lắng nghe trên cổng 3000.

Cách xử lý: Xác định tiến trình đang chiếm cổng và dừng tiến trình đó, hoặc chỉ định cổng khác cho Dokploy:

# Tìm PID của tiến trình đang giữ port 3000
sudo ss -tulnp | grep ':3000'

# Buộc dừng tiến trình nếu không sử dụng (thay PID bằng số thực tế)
sudo kill -9 <PID>

# Hoặc cài đặt Dokploy trên cổng khác (ví dụ cổng 3005)
curl -sSL https://dokploy.com/install.sh | sudo PORT=3005 sh

3. Lỗi Docker Swarm không thể khởi tạo do nhận diện sai IP

Triệu chứng: Script cài đặt thông báo lỗi Error response from daemon: could not choose an IP address to advertise.

Nguyên nhân: Máy chủ có nhiều hơn một giao diện mạng (network interface) hoặc chạy trên hạ tầng mạng nội bộ ảo khiến Docker Swarm không xác định được card mạng chính.

Cách xử lý: Chạy lại lệnh cài đặt kèm tham số chỉ định IP công khai chính xác của máy chủ:

curl -sSL https://dokploy.com/install.sh | sudo ADVERTISE_ADDR=your-public-ip sh

4. Webhook GitHub không kích hoạt tiến trình tự động deploy

Triệu chứng: Push commit mới lên GitHub nhưng tab Deployments trên Dokploy không có hoạt động build mới.

Nguyên nhân: Sai định dạng dữ liệu gửi qua Webhook hoặc IP máy chủ bị chặn bởi bộ lọc mạng.

Cách xử lý:

1. Truy cập repository GitHub > Settings > Webhooks > nhấn vào webhook của Dokploy.
2. Kéo xuống mục Recent Deliveries để xem mã phản hồi HTTP từ VPS. Nếu nhận mã 400 hoặc 500, kiểm tra lại Secret token.
3. Đảm bảo mục Content type được thiết lập chính xác là application/json (không dùng application/x-www-form-urlencoded).
4. Kiểm tra log nhận request từ Traefik bằng lệnh:

   docker service logs dokploy-traefik --tail 30

Nội dung mang tính tham khảo. Lệnh, cú pháp, đường dẫn file và tùy chọn cấu hình có thể thay đổi theo phiên bản hệ điều hành, phiên bản phần mềm và môi trường cụ thể. Nên kiểm thử, sao lưu dữ liệu và đánh giá rủi ro trước khi áp dụng lên server production.