docker run là công cụ tuyệt vời để làm quen với việc khởi chạy một container đơn lẻ. Nhưng chỉ cần ứng dụng lớn thêm một chút — có App, có Database, có hàng tá biến môi trường cần truyền vào, có volume cần mount, có network cần cấu hình, và có thứ tự khởi động không thể tuỳ tiện — thì dòng lệnh terminal sẽ nhanh chóng phình to thành một chuỗi tham số dài dằng dặc mà chính bạn cũng ngại đọc lại sau một tuần.
Đó chính là lúc Docker Compose bước vào cuộc chơi.
File Compose không thay thế Dockerfile, mà bổ sung cho nó. Nếu Dockerfile trả lời câu hỏi "đóng gói (build) image như thế nào", thì Docker Compose (YAML) trả lời câu hỏi "các container vận hành (run) cùng nhau ra sao": dùng image nào, gắn ổ đĩa (volume) ở đâu, giao tiếp qua network nào, ai khởi động trước — ai khởi động sau.
Trước khi bước vào ví dụ thực tế, hãy điểm qua những khái niệm nền tảng làm nên "xương sống" của Compose.
Ba khái niệm cốt lõi trong Docker Compose
Mở bất kỳ file compose.yaml (hay docker-compose.yml) nào ra, bạn sẽ luôn thấy ba thành phần cấp cao (top-level elements) sau:
Services (Dịch vụ) — đơn vị runtime trung tâm của Compose. Một service mô tả cách một (hoặc nhiều) container được chạy. Chẳng hạn: service frontend chạy React, service backend chạy Node.js, service database chạy PostgreSQL.
Networks (Mạng lưới) — về bản chất, container sinh ra đã bị cô lập với nhau. Networks định nghĩa luật chơi cho việc giao tiếp giữa chúng. Compose tự động tạo một network nội bộ riêng cho project, nhờ đó các service có thể gọi nhau bằng tên (qua DNS nội bộ) thay vì phải nhớ địa chỉ IP tĩnh.
Volumes (Không gian lưu trữ) — khi một container bị xoá, mọi dữ liệu bên trong nó cũng biến mất theo. Volumes cho phép dữ liệu (như các bản ghi database) tồn tại độc lập với vòng đời của container: dù bạn có dừng, xoá, hay tạo lại container bao nhiêu lần, dữ liệu gắn vào volume vẫn nguyên vẹn.
Bộ khung của một file Compose
Trước khi lao vào lab, hãy nhìn tổng thể "bộ khung" mà mọi file Compose đều tuân theo:
services: service-name: # Định nghĩa service volumes: volume-name: # Cấu hình volume networks: network-name: # Cấu hình network
Trong ba khối này, chỉ services là bắt buộc — volumes và networks chỉ xuất hiện khi bạn cần khai báo tường minh (ví dụ named volume, hoặc network cô lập ngoài network mặc định). Đây cũng là lý do vì sao rất nhiều file Compose "tối giản" ngoài thực tế chỉ có mỗi services: mà vẫn chạy tốt.
A.imagehaybuild: lấy sẵn hay tự đóng gói?
Mỗi service cần một nguồn image, và có hai lựa chọn:
services: db: image: postgres:16-alpine # dùng image có sẵn từ registry api: build: ./api # tự build từ Dockerfile trong thư mục ./api
Với những thành phần hạ tầng chuẩn (database, cache, message queue...), gần như luôn nên dùng image có sẵn — không có lý do gì để tự build lại PostgreSQL. build chỉ dành cho code của chính bạn. Khi cần kiểm soát sâu hơn (build args, Dockerfile khác tên mặc định, build context riêng), build có thể mở rộng thành object:
services: api: build: context: ./api dockerfile: Dockerfile.prod args: - NODE_ENV=production
B.ports: publish ra ngoài như thế nào
Ở phần Lab phía sau, bạn sẽ thấy service postgres không có ports: — đó là lựa chọn có chủ đích. Nhưng khi một service thực sự cần publish (như App HTTP), cú pháp có vài biến thể đáng nhớ:
services:
web:
ports:
- "8080:80" # host:container — cố định cổng host
- "3000" # chỉ định cổng container, Docker tự chọn cổng host ngẫu nhiên
- "127.0.0.1:8080:80" # chỉ bind vào localhost của host, không lộ ra mạng ngoài
Biến thể thứ ba (127.0.0.1:...) đáng chú ý nhất về mặt bảo mật: nó cho phép bạn debug từ chính máy host mà không vô tình mở port ra toàn bộ mạng — một lựa chọn trung gian giữa "publish hoàn toàn" và "không publish gì" như DB trong lab.
C. Environment variables: inline hayenv_file
services:
api:
environment:
- NODE_ENV=production
- DB_HOST=db
Cách viết inline phù hợp với vài biến ít thay đổi. Nhưng khi số lượng biến tăng lên, hoặc bạn cần tách biệt giá trị theo môi trường (dev/staging/prod) mà không sửa trực tiếp file YAML, env_file là lựa chọn sạch hơn:
services:
api:
env_file:
- .env
- .env.local
Lưu ý: env_file chỉ nên chứa cấu hình không nhạy cảm, hoặc secret ở dạng đã được quản lý qua .gitignore nghiêm ngặt — nguyên tắc "không đưa secret vào Git" ở phần Lab áp dụng y hệt cho .env.
D. Volumes: named volume và bind mount là hai thứ khác nhau
Đây là điểm rất dễ gây nhầm lẫn với người mới:
services:
db:
volumes:
- pgdata:/var/lib/postgresql/data # named volume
- ./init.sql:/docker-entrypoint-initdb.d/init.sql # bind mount
volumes:
pgdata: # named volume phải được khai báo ở top-level
Named volume (pgdata:...) do Docker quản lý hoàn toàn — bạn không cần (và không nên) quan tâm dữ liệu vật lý nằm ở đâu trên host. Đây là lựa chọn đúng cho dữ liệu cần bền vững như database, đúng như phân tích ở phần D của mục Lab bên dưới.
Bind mount (./init.sql:...) lại ánh xạ trực tiếp một file/thư mục cụ thể từ host vào container. Nó hữu ích để inject file cấu hình, script khởi tạo, hoặc — trong môi trường dev — đồng bộ code trực tiếp từ host vào container để có hot-reload. Nhưng bind mount không phù hợp cho dữ liệu sống còn, vì nó gắn chặt với đường dẫn vật lý trên host, không portable.
Ghi nhớ ngắn gọn: named volume dùng cho state cần Docker quản lý, bind mount dùng cho file cần bạn quản lý.
Lab App + Database
Để thấy rõ ba khái niệm trên phối hợp với nhau như thế nào, chúng ta sẽ dựng một stack nhỏ: một Node.js HTTP App gọi tới PostgreSQL. Lab này đủ gọn để chạy trên máy local, nhưng vẫn được thiết kế có healthcheck, named volume và private database network — đúng tinh thần của một hệ thống production thu nhỏ.
Cấu trúc lab:
compose-101/ ├── compose.yaml ├── Dockerfile ├── package.json ├── package-lock.json └── server.js
package.json:
{
"name": "compose-101",
"private": true,
"type": "module",
"scripts": {
"start": "node server.js"
},
"dependencies": {
"pg": "8.16.0"
}
}
server.js:
import http from "node:http"; import pg from "pg"; const { Pool } = pg; const port = Number(process.env.PORT || 3000); const pool = new Pool({ connectionString: process.env.DATABASE_URL }); async function databaseReady() { await pool.query("select 1"); } const server = http.createServer(async (request, response) => { if (request.url === "/livez") { response.writeHead(200).end("ok"); return; } if (request.url === "/readyz") { try { await databaseReady(); response.writeHead(200).end("ready"); } catch { response.writeHead(503).end("database unavailable"); } return; } response.writeHead(200, { "content-type": "application/json" }); response.end(JSON.stringify({ ok: true })); }); server.listen(port, "0.0.0.0", () => console.log(`listening on ${port}`));
Dockerfile:
FROM node:24-bookworm-slim WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci --omit=dev COPY server.js ./ USER node EXPOSE 3000 CMD ["node", "server.js"]
Compose file tối giản nhưng có dependency đúng
compose.yaml:
services:
app:
build:
context: .
environment:
NODE_ENV: production
PORT: "3000"
DATABASE_URL: postgres://demo:change-me-locally@postgres:5432/demo
depends_on:
postgres:
condition: service_healthy
ports:
- "127.0.0.1:3000:3000"
healthcheck:
test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/livez').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
interval: 15s
timeout: 3s
retries: 5
start_period: 10s
networks:
- internal
postgres:
image: postgres:16-alpine
environment:
POSTGRES_DB: demo
POSTGRES_USER: demo
POSTGRES_PASSWORD: change-me-locally
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
interval: 10s
timeout: 3s
retries: 10
start_period: 10s
networks:
- internal
volumes:
postgres_data:
networks:
internal:
Password trong lab chỉ tồn tại để ví dụ chạy được ngay. Không copy pattern này sang production .env hoặc Git repository. Production secret cần được inject từ secret mechanism của runtime (Vault, secret manager của cloud provider, hoặc Docker/Kubernetes secret).
Phân tích cấu hình trong Lab
Nhìn lướt qua, file YAML này có vẻ rất đơn giản. Nhưng phía sau từng dòng cấu hình là một quyết định mang tính kiến trúc.
A. Network & Service Discovery
Compose đặt tên network, volume và container dựa theo tên project (mặc định là tên thư mục chứa file compose).
Cả app và postgres cùng nằm trong một network nội bộ. Compose tự động sinh bản ghi DNS theo tên service, nên thay vì dò IP, app có thể gọi thẳng tới database qua URL dạng postgres://user:pass@postgres:5432/db.
Nguyên tắc vàng: không dùng localhost trong chuỗi kết nối của container App. Bên trong container App, localhost chính là bản thân nó — không phải là database.
Để ý rằng service postgres hoàn toàn không có mục ports:. Điều đó có nghĩa máy host (laptop/VPS của bạn) không thể kết nối tới cổng 5432 từ bên ngoài. Đây là một ranh giới bảo mật rất đẹp: database không cần "phơi" ra ngoài, chỉ những service cùng network (như App) mới gọi được tới nó.
B. Lifecycle:depends_onkhông đơn thuần là thứ tự trên giấy
Nếu chỉ viết:
depends_on: - postgres
thì Compose chỉ đảm bảo container Postgres được lệnh khởi động trước App — chứ không đảm bảo "container đang chạy" đồng nghĩa với "database đã sẵn sàng nhận query". Postgres vẫn cần vài giây để khởi tạo data directory trước khi thực sự phục vụ.
Vì vậy chúng ta cần condition: service_healthy. Compose sẽ chờ đến khi healthcheck của Postgres báo pass (tức là đã truy vấn được thật sự) rồi mới cho App khởi động.
Sự thật cần nhìn thẳng: ngay cả service_healthy cũng không thay thế được logic retry ở tầng ứng dụng. Mạng chập chờn, DB restart giữa chừng — những tình huống này vẫn có thể xảy ra bất cứ lúc nào. depends_on chỉ giải quyết được thứ tự lúc startup; còn việc xử lý dependency failure lúc runtime vẫn là trách nhiệm của chính ứng dụng.
C. Healthcheck: "Sống" khác với "Sẵn sàng"
Lab của chúng ta có hai endpoint để minh hoạ sự khác biệt này:
-
/livez: xác nhận Node process đang sống và còn tiếp nhận HTTP request (đây là endpoint Docker healthcheck đang sử dụng). -
/readyz: xác nhận Node process thực sự truy vấn được database tại đúng thời điểm kiểm tra.
Không có endpoint nào "đúng" cho mọi tình huống. Nếu bạn để readiness check bắt buộc phải kèm theo DB healthy, thì khi DB tạm thời gián đoạn, App của bạn sẽ bị Load Balancer loại khỏi nhóm phục vụ ngay lập tức — dù lúc đó App vẫn hoàn toàn có thể trả về một trang "Bảo trì" hợp lệ. Chọn endpoint nào cho readiness check là một quyết định phụ thuộc vào yêu cầu vận hành thực tế của sản phẩm, không có công thức chung.
D. Bảo toàn dữ liệu với Named Volume
Dữ liệu của Postgres được lưu vào một Named Volume. Nhờ vậy, dù bạn cập nhật image hay thay đổi cấu hình khiến container bị tạo lại, dữ liệu vẫn được giữ nguyên.
volumes: - postgres_data:/var/lib/postgresql/data
docker compose config --volumes docker volume ls
Lệnh nguy hiểm cần tránh: đừng bao giờ chạy docker compose down -v nếu bạn muốn giữ lại dữ liệu. Cờ -v sẽ xoá sạch mọi Named Volume thuộc project. Trong lab, việc này giúp "dọn dẹp nhanh gọn" — nhưng ở môi trường có dữ liệu thật, đó là một hành động phá huỷ không thể vãn hồi.
docker compose config
Trước khi chạy up, hãy tập thói quen chạy lệnh config trước. File Compose thường không đứng một mình — nó có thể bị chi phối bởi biến môi trường (.env), file override, v.v. Chỉ đọc YAML gốc chưa chắc bạn đã thấy đúng cấu hình mà Docker thực sự sẽ áp dụng.
docker compose config # full configuration render docker compose config --services # list services docker compose config --volumes # list volumes docker compose config --quiet # syntax validation - quiet mode
Khởi động lab:
docker compose up --build -d docker compose ps docker compose logs --tail=100 app postgres curl -i http://127.0.0.1:3000/livez curl -i http://127.0.0.1:3000/readyz
Dọn lab nhưng giữ data:
docker compose down
Dọn lab và xóa database data, chỉ dùng khi cố ý reset:
docker compose down -v
Command cheatsheet
Ngoài up, down và config đã nhắc ở trên, đây là bộ lệnh Compose bạn sẽ gõ gần như mỗi ngày khi làm việc với lab hay hệ thống thật.
Khởi động & build
docker compose up # chạy foreground, thấy log trực tiếp, Ctrl+C để dừng docker compose up -d # chạy nền (detached) docker compose up --build # build lại image trước khi khởi động
Dừng & dọn dẹp
docker compose down # dừng và xoá container, giữ nguyên volume docker compose down -v # xoá luôn named volume — cẩn trọng như đã nói ở phần D docker compose down --rmi all # xoá luôn cả image đã build/pull
Quan sát hệ thống
docker compose ps # xem trạng thái từng service docker compose logs # xem log toàn bộ services docker compose logs -f api # theo dõi log real-time của riêng service api docker compose logs --tail 100 # chỉ xem 100 dòng log gần nhất
Vào bên trong container
docker compose exec api bash docker compose exec db psql -U taskuser
Chạy lệnh một lần
docker compose run api npm test # tạo container mới chỉ để chạy lệnh này docker compose run --rm api npm test # tương tự, nhưng tự xoá container sau khi xong
exec và run dễ bị dùng lẫn lộn: exec chạy lệnh trong một container đang sống, còn run tạo một container mới chỉ để thực thi lệnh rồi thôi — dùng đúng ngữ cảnh sẽ tránh được tình trạng container test rác tồn đọng theo thời gian.
Scale service
docker compose up -d --scale worker=3 # chạy 3 instance của service worker
Đây là cách nhanh nhất để mô phỏng việc scale ngang ngay trên local, dù tất nhiên không thay thế được orchestration thật sự (Kubernetes, Swarm) ở production.
restartpolicy không phải HA
Compose hỗ trợ restart policy để Docker tự khởi động lại container khi process crash hoặc daemon restart:
services:
api:
restart: unless-stopped
Có 4 giá trị hợp lệ, mỗi giá trị mang một "triết lý" khác nhau:
-
no(mặc định): không tự restart trong bất kỳ trường hợp nào. Phù hợp cho các one-off job hoặc script chạy một lần. -
always: luôn restart, kể cả khi bạn chủ động dừng bằngdocker stoprồi khởi động lại Docker daemon. Ít dùng vì có thể "hồi sinh" cả những container bạn cố tình tắt. -
on-failure: chỉ restart khi container thoát với exit code khác 0 (tức là crash thật sự), không restart khi bạn chủ động dừng. -
unless-stopped: restart trong hầu hết trường hợp — kể cả khi Docker daemon restart — trừ khi bạn chủ độngdocker stopcontainer đó.
Trong lab và phần lớn service production, unless-stopped là lựa chọn cân bằng nhất.
Nhưng restart policy chỉ hoạt động ở một tầng rất hẹp: nó hữu ích trên một host đơn lẻ, không tạo ra multi-host availability, không replicate database, và không chống được sự cố hỏng ổ cứng của chính host đó.
Đừng dùng restart loop để che giấu lỗi cấu hình ứng dụng. Nếu process crash vì migration lỗi, secret sai, hay schema database không tương thích, restart policy chỉ tạo ra một vòng lặp log noise cho tới khi disk đầy hoặc có người can thiệp thủ công.
Những bẫy cần tránh
Khi đứng trước một file Compose dài 500 dòng ở môi trường production, bạn không cần thuộc lòng từng dòng YAML. Thay vào đó, hãy đi theo mạch câu hỏi kiến trúc sau:
- Service nào mở port ra ngoài, service nào ẩn hoàn toàn bên trong?
- Volume nào chứa dữ liệu sống còn (source of truth), volume nào chỉ đơn thuần là cache?
- Ai đang chờ ai (healthcheck)?
- Restart policy có đang che giấu một lỗi crash lặp đi lặp lại của ứng dụng hay không? (Lưu ý: các restart policy như
unless-stoppedkhông phải là High Availability — chúng không chống được sự cố hỏng ổ cứng hay thay thế cho việc replicate database.)
3 lỗi thường gặp:
-
Tin tưởng tuyệt đối vào
depends_on: ứng dụng vẫn cần có timeout/retry logic riêng, thay vì phó mặc hoàn toàn cho Compose. -
In
docker compose configra public CI log: hành động này có thể vô tình làm lộ secret lấy từ.env. - Publish port của database ra ngoài một cách bừa bãi: chỉ vì "app không kết nối được" mà nhiều người vội mở thẳng port DB ra public, thay vì kiểm tra lại tên service trong network nội bộ trước.
Một lưu ý thêm: giới hạn tài nguyên
File Compose trong lab (và phần lớn ví dụ học tập) thường không giới hạn CPU/memory cho từng service — container có thể ăn tài nguyên vô tội vạ nếu code có bug (leak, vòng lặp vô hạn...). Ở production, nên khai báo giới hạn tường minh:
services:
api:
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
reservations:
memory: 256M
limits là trần tối đa container được phép dùng — vượt quá, container có thể bị OOM kill. reservations là mức tài nguyên tối thiểu được đảm bảo dành riêng cho service đó. Thiếu resource limits không gây lỗi ngay lập tức, nhưng là nguyên nhân phổ biến của những sự cố kiểu "một container ăn hết RAM làm sập cả node" — loại lỗi rất khó debug nếu không nhìn đúng chỗ ngay từ đầu.
Tổng kết
Docker Compose vượt xa vai trò của một công cụ gộp các lệnh docker run cho đỡ mỏi tay. Nó giúp document hoá toàn bộ topology của ứng dụng — từ network isolation, mount point, cho đến startup lifecycle — thành một bản thiết kế có thể đọc lại bất cứ lúc nào.
Nhưng Compose chỉ quản lý ở tầng infrastructure cục bộ. Để ứng dụng thực sự "production-ready", tư duy của người kỹ sư cần đi xa hơn nội dung file YAML. Ba nguyên tắc "mỏ neo" nên luôn mang theo:
- Lifecycle Order không thay thế Application Resilience.
- Default Secure với network nội bộ.
-
Cẩn trọng tuyệt đối với State (đặc biệt là cờ
-v).
Khi đã nắm vững những lăng kính phân tích này — ai gọi ai, ai đợi ai, ai lưu cái gì, ai phơi ra ngoài — thì việc làm chủ Docker Compose không còn dừng ở việc đọc đúng cú pháp, mà trở thành hành trình thiết kế có chủ ý từng mắt xích của một hệ thống.