Cách cài Docker Compose trên VPS Linux

SSH vào VPS mới, cài xong Docker Engine rồi gõ docker-compose --version mà nhận lại command not found, đó là tình huống mình gặp khá nhiều khi nhận bàn giao server từ người khác. Nguyên nhân thường không phải bạn cài sai, mà là Docker Compose giờ đã là plugin tích hợp sẵn trong Docker Engine, lệnh đúng phải là docker compose (không có dấu gạch ngang). Bài này sẽ hướng dẫn cách cài Docker Compose trên VPS Linux cho ba distro phổ biến nhất: Ubuntu 24.04 LTS, Debian 12 và AlmaLinux 9.

Yêu cầu trước khi bắt đầu

Để làm theo bài này, bạn cần chuẩn bị sẵn:

• Một VPS chạy Ubuntu 24.04 LTS, Debian 12 hoặc AlmaLinux 9. Nếu chưa có, bạn có thể thuê VPS Linux với quyền full root từ các nhà cung cấp trong nước có IPv4 Việt Nam để latency thấp khi truy cập từ Việt Nam.
• Quyền sudo hoặc tài khoản root.
• Đã cài sẵn Docker Engine. Nếu chưa, hãy cài Docker trước, vì Docker Compose bản mới chạy như một plugin của Docker.
• Kiến thức cơ bản về dòng lệnh Linux và file YAML.

Vì sao nên dùng docker compose thay vì docker-compose?

Docker Compose v2 được viết lại hoàn toàn bằng Go, thay thế bản cũ viết bằng Python. Từ giữa năm 2023, lệnh docker-compose (có gạch ngang) chính thức ngừng nhận cập nhật tính năng mới. Bản v2 được phân phối như một plugin của Docker CLI, nghĩa là khi bạn cài Docker Engine theo cách chính thức, bạn có thể cài thêm plugin compose mà không cần tải riêng binary từ GitHub.

Cú pháp cũng đơn giản hơn: thay vì gõ docker-compose up -d thì giờ chỉ cần docker compose up -d. Quan trọng hơn, tốc độ parse file YAML nhanh hơn đáng kể, đặc biệt khi bạn có nhiều service trong một file cấu hình. Đây là lý do mình khuyên bạn nên làm quen với cú pháp mới ngay từ đầu, đừng học theo các tutorial cũ vẫn dùng docker-compose.

Bước 1 - Kiểm tra Docker Engine đã cài chưa

Trước khi cài Compose, cần chắc chắn Docker Engine đã hoạt động. Chạy lệnh sau trên cả ba distro:

sudo docker info --format '{{.ServerVersion}}'

Nếu nhận được số phiên bản (ví dụ 29.7.1), Docker đã sẵn sàng. Nếu báo lỗi hoặc không tìm thấy lệnh docker, bạn cần cài Docker Engine trước. Trên Ubuntu và Debian, dùng lệnh sau để cài từ kho chính thức:

sudo apt update
sudo apt install docker.io -y
sudo systemctl enable --now docker

Trên AlmaLinux 9, dùng dnf:

sudo dnf install -y docker
sudo systemctl enable --now docker

Lưu ý: gói docker.io trong kho Ubuntu/Debian có thể không phải bản mới nhất. Nếu muốn bản mới nhất, cài theo tài liệu chính thức của Docker bằng script get.docker.com. Cách đó hoạt động tốt trên cả ba distro.

Bước 2 - Cài Docker Compose plugin

Cách cài Docker Compose trên VPS Linux phụ thuộc vào cách bạn đã cài Docker Engine.

Trường hợp 1: Docker cài từ script chính thức

Nếu bạn cài Docker bằng script get.docker.com, plugin compose đã được cài sẵn. Kiểm tra nhanh:

docker compose version

Bạn sẽ thấy output dạng Docker Compose version v5.3.1 hoặc tương tự, tùy bản mới nhất tại thời điểm đọc. Không cần làm gì thêm.

Trường hợp 2: Docker cài từ kho apt/dnf của distro

Trên Ubuntu 24.04 và Debian 12, cài plugin compose bằng apt:

sudo apt update
sudo apt install -y docker-compose-v2

Trên AlmaLinux 9, dùng dnf:

sudo dnf install -y docker-compose-plugin

Sau khi cài, xác nhận plugin đã được Docker CLI nhận:

docker compose version

Kết quả mong đợi:

Docker Compose version v5.3.1

Nếu lệnh docker compose báo lỗi unknown command, bạn cần kiểm tra lại thư mục plugin của Docker. Trên Linux, plugin nằm tại /usr/libexec/docker/cli-plugins/ hoặc /usr/local/lib/docker/cli-plugins/.

Bước 3 - Cách cài Docker Compose bằng binary (phương án dự phòng)

Trong trường hợp bạn dùng distro không có gói docker-compose-v2, hoặc muốn kiểm soát chính xác phiên bản, bạn vẫn có thể tải binary trực tiếp từ GitHub. Cách này mình dùng khi cài trên CentOS Stream hoặc các bản Linux khác.

sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Lưu ý cách này cài binary thành lệnh docker-compose (có gạch ngang), không phải plugin docker compose. Nó vẫn hoạt động tốt, nhưng không nhận được cập nhật tự động khi bạn nâng cấp Docker. Nếu đã có plugin v2, bạn không cần phương án này.

Để xác nhận, chạy:

sudo docker-compose --version

Kết quả mong đợi dạng Docker Compose version v5.3.1.

Bước 4 - Tạo file docker-compose.yml đầu tiên và chạy thử

Cài xong là phải chạy thử mới yên tâm. Tạo một thư mục làm việc và file compose tối thiểu:

mkdir -p ~/test-compose
cd ~/test-compose
nano docker-compose.yml

Dán nội dung sau vào file:

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
  redis:
    image: redis:7-alpine

File này định nghĩa hai service: một web server Nginx và một Redis. Lưu file lại rồi chạy:

docker compose up -d

Docker sẽ tải image về và khởi động cả hai container. Kiểm tra trạng thái:

docker compose ps

Bạn sẽ thấy cả hai service đều ở trạng thái running. Giờ truy cập thử Nginx:

curl -I http://localhost:8080

Nếu nhận HTTP/1.1 200 OK, Docker Compose đã hoạt động hoàn chỉnh. Dọn dẹp sau khi thử:

docker compose down

Xử lý lỗi thường gặp khi cài Docker Compose

Dưới đây là ba lỗi mình gặp nhiều nhất khi hỗ trợ khách hàng thuê VPS cài Docker Compose:

Lỗi 1: docker: 'compose' is not a docker command

Nghĩa là plugin chưa được cài hoặc Docker CLI không tìm thấy. Kiểm tra lại bằng lệnh docker compose version. Nếu vẫn lỗi, cài lại plugin theo Bước 2 hoặc kiểm tra đường dẫn plugin:

ls -la /usr/libexec/docker/cli-plugins/ /usr/local/lib/docker/cli-plugins/

Nếu thư mục trống, tải plugin thủ công:

sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo curl -SL "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/lib/docker/cli-plugins/docker-compose
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose

Lỗi 2: Permission denied khi chạy docker compose

User hiện tại chưa nằm trong group docker. Thêm user vào group rồi đăng xuất, đăng nhập lại (hoặc chạy newgrp docker):

sudo usermod -aG docker $USER
newgrp docker

Lỗi 3: Version trong file compose quá cũ

File compose có dòng version: '3.8' ở đầu. Compose v2 bỏ qua dòng này và tự suy ra cấu trúc mới nhất, nhưng nếu file có cấu trúc cũ với version: '2' thì có thể báo lỗi. Giải pháp: xóa dòng version: khỏi file, cấu trúc service giờ đã là chuẩn.

Câu hỏi thường gặp

Bài viết liên quan

• Cách cài Docker trên VPS Ubuntu chi tiết từ A đến Z
• Chạy nhiều site trên 1 VPS với Docker và Nginx proxy
• Quản lý Docker volume và backup dữ liệu container