Dockerfile là công thức để tạo image — nó không phải shell script chạy trên host, cũng không phải file cấu hình runtime hoàn chỉnh. Mỗi instruction chỉ mô tả một bước build, và Docker dùng kết quả của từng bước đó để tạo ra layer/cache artifact tương ứng.
Ở bài này, mình sẽ build một Node.js HTTP server cực nhỏ. Một ví dụ đơn giản như vậy giúp thấy rõ instruction nào chạy lúc build, instruction nào chỉ có tác dụng lúc container start, và vì sao .dockerignore lại quan trọng hơn nhiều người nghĩ.
Bộ khung của một Dockerfile
Trước khi vào lab cụ thể, hãy nhìn qua ba quyết định nền tảng mà bất kỳ Dockerfile nào cũng phải đưa ra: build trên nền gì, đưa file vào bằng cách nào, và có nên tách build ra khỏi runtime hay không.
A. Base image: chọn theo nhu cầu, không phải theo thói quen
Không phải base image nào cũng đúng cho mọi tình huống. Bốn nhóm phổ biến:
- alpine — cực nhỏ (~5MB), dùng musl libc thay vì glibc. Rất hợp với Go (binary tĩnh, không phụ thuộc libc runtime), nhưng dễ gây rắc rối với Node/Python nếu package có native module biên dịch sẵn cho glibc.
-
slim — nền Debian đã lược bớt package không cần cho runtime. Cân bằng tốt giữa kích thước và khả năng tương thích — đây cũng là lựa chọn lab ở bài này đang dùng (
node:24-bookworm-slim). - full (không có suffix) — đầy đủ Debian/Ubuntu. Nặng hơn hẳn nhưng hầu như không bao giờ thiếu thư viện hệ thống, phù hợp khi cần debug nhiều hoặc khi dependency quá phức tạp để chạy trên slim/alpine.
-
distroless — dòng image tối giản của Google: không shell, không package manager, gần như không có gì ngoài runtime cần thiết. Bề mặt tấn công (attack surface) nhỏ nhất trong 4 loại, nhưng đổi lại gần như không thể
docker execvào để debug trực tiếp.
Nguyên tắc chọn: alpine khi ứng dụng không có native dependency nhạy cảm với libc (điển hình: Go, hoặc app JS/Python thuần không cần build native module), slim khi cần cân bằng, full khi đang trong giai đoạn phát triển cần debug nhiều, và distroless khi image đã ổn định và ưu tiên bảo mật lên hàng đầu.
B.COPYhayADD: vì saoCOPYnên là mặc định
COPY package.json . COPY src/ ./src/ COPY chỉ làm đúng một việc: sao chép file/thư mục từ build context vào image, tường minh và dễ đoán. ADD làm được thêm hai việc: tự động giải nén tarball, và fetch file trực tiếp từ URL: dockerfile # COPY: sao chép nguyên trạng file .tar.gz vào image COPY app.tar.gz /app/ # ADD: tự động giải nén ngay trong lúc copy ADD app.tar.gz /app/
Vấn đề của ADD không nằm ở việc nó "sai", mà ở việc hành vi ẩn đó (tự giải nén, tự tải file) khiến người đọc Dockerfile sau này khó đoán được chuyện gì đang thực sự xảy ra nếu chỉ nhìn lướt qua. Nguyên tắc chung: mặc định dùng COPY, chỉ chuyển sang ADD khi thật sự cần đúng hai tính năng đặc biệt đó — không dùng ADD chỉ vì nó "làm được nhiều hơn".
C. Multi-stage build: tách build-time ra khỏi runtime
BuildKit cache mount (sẽ nói ở phần sau) giúp build nhanh hơn. Nhưng có một câu hỏi khác hoàn toàn: image chạy production có cần mọi thứ mà bước build cần hay không? Thường là không.
Với Node.js, một Dockerfile "một stage" như trong lab sẽ đóng gói luôn devDependencies, cache của npm, và đôi khi cả toolchain build native module vào chung image chạy production. Multi-stage build giải quyết việc này bằng cách dùng nhiều FROM trong cùng một Dockerfile, mỗi stage có vai trò riêng, và chỉ copy đúng phần cần thiết sang stage cuối:
# Stage 1: cài dependency FROM node:24-bookworm-slim AS deps WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci --omit=dev # Stage 2: image chạy production FROM node:24-bookworm-slim WORKDIR /app COPY --from=deps /app/node_modules ./node_modules COPY . . USER node EXPOSE 3000 CMD ["node", "server.js"]
Điểm mấu chốt nằm ở COPY --from=deps — lệnh này chỉ lấy đúng thư mục node_modules đã được cài ở stage 1, không kéo theo bất kỳ artifact build nào khác (build log, cache npm, source phụ trợ...). Image cuối cùng chỉ chứa những gì runtime thật sự cần.
Với ứng dụng cần compile (TypeScript, native addon, hay ngôn ngữ biên dịch như Go/Rust), lợi ích còn rõ hơn nữa: stage build có thể chứa toàn bộ compiler/toolchain nặng nề, còn stage cuối chỉ cần copy đúng file binary hoặc bundle đã build xong — toolchain build hoàn toàn không xuất hiện trong image chạy production, vừa giảm kích thước vừa thu hẹp bề mặt tấn công.
Đây cũng là lý do multi-stage build và distroless (nói ở phần A) thường đi cùng nhau: khi build tool đã bị loại khỏi stage cuối, dùng một base image tối giản như distroless cho stage đó trở nên khả thi mà không lo thiếu dependency.
Lab source tối giản
Tạo thư mục dockerfile-101 với ba file sau.
package.json:
{
"name": "dockerfile-101",
"private": true,
"type": "module",
"scripts": {
"start": "node server.js"
}
}
server.js:
import http from "node:http";
const port = Number(process.env.PORT || 3000);
const server = http.createServer((request, response) => {
response.writeHead(200, { "content-type": "application/json" });
response.end(JSON.stringify({ ok: true, path: request.url }));
});
server.listen(port, "0.0.0.0", () => {
console.log(`listening on ${port}`);
});
.dockerignore:
node_modules .git .env npm-debug.log* coverage
Dockerfile:
FROM node:24-bookworm-slim WORKDIR /app COPY package.json ./ RUN npm install --omit=dev COPY server.js ./ ENV NODE_ENV=production EXPOSE 3000 CMD ["npm", "start"]
Build và chạy:
docker build --tag dockerfile-101:local . docker run --rm --name dockerfile-101 -p 3000:3000 dockerfile-101:local # Terminal khác curl -fsS http://127.0.0.1:3000/health
Dừng container bằng Ctrl+C. Vì dùng --rm, Docker sẽ tự xóa container ngay sau khi process thoát. Image dockerfile-101:local thì vẫn còn nguyên và có thể dùng để tạo container mới bất cứ lúc nào.
FROM: chọn runtime base, không chỉ chọn kích thước
FROM node:24-bookworm-slim chính là base image — mọi instruction phía sau đều được áp dụng dựa trên nền này. Base image quyết định OS userspace, package manager, libc, CA certificates, và cả khả năng chạy được native dependency hay không.
Bốn nhóm base image phổ biến (alpine/slim/full/distroless) và tiêu chí chọn giữa chúng đã nói ở mục "Bộ khung của một Dockerfile" phía trên.
slim thường giảm bớt những package không cần cho runtime, nhưng điều đó không đồng nghĩa với việc nên luôn đổi sang Alpine. Khá nhiều package Node có native module, mà Alpine lại dùng musl libc trong khi Debian dùng glibc. Vì vậy, trước khi đổi base image, mình cần build và test kỹ native dependency cùng phần image processing thật, chứ không chỉ dựa vào con số benchmark image size.
Nên pin version ít nhất theo major/minor khi cần đảm bảo reproducibility. Với production release, cần có policy rõ ràng cho việc update base image và vá security patch, thay vì dùng một tag mơ hồ chỉ vì nó ngắn gọn.
WORKDIR: đặt context cho các instruction phía sau
WORKDIR /app sẽ tạo (nếu chưa có) và chuyển working directory cho RUN, COPY, cho CMD dạng shell, và cho cả runtime process chạy sau nó. Mình không cần thêm RUN mkdir -p /app trước đó.
WORKDIR /app COPY package.json ./
Sau lệnh này, file trong image sẽ nằm ở đúng /app/package.json.
RUN: chạy khi build image
RUN chạy ngay trong build stage, tạo ra filesystem delta cho image — nó không chạy lại mỗi lần container start.
RUN npm install --omit=dev
Sau khi build xong, dependency đã nằm sẵn trong layer của image. Nếu app cần chạy migration database ở runtime, mình không nên viết migration đó dưới dạng RUN, vì build machine không có quyền truy cập, và cũng không nên kết nối tới production database ngay trong lúc build.
Một lỗi layer khá phổ biến:
RUN apt-get update RUN apt-get install -y curl
Cách viết tốt hơn:
RUN apt-get update \ && apt-get install -y --no-install-recommends curl \ && rm -rf /var/lib/apt/lists/*
Lý do là apt index được tạo ra và nằm trong cùng một layer với chính nó. Nếu xóa ở layer sau, layer trước vẫn giữ nguyên kích thước — dồn tất cả vào cùng một RUN mới thật sự giảm được dung lượng.
Tăng tốc RUN bằng BuildKit cache mount
Với BuildKit (mặc định từ Docker khá gần đây), mình có thể giữ lại cache của package manager giữa các lần build, mà không cần bake nó vào layer:
# syntax=docker/dockerfile:1
FROM node:24-bookworm-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
npm ci --omit=dev
--mount=type=cache gắn một cache riêng cho BuildKit, tồn tại xuyên suốt nhiều lần build khác nhau nhưng không bị đóng gói vào image cuối cùng. Với server build CI chạy nhiều lần mỗi ngày, cách này giúp npm ci nhanh hơn đáng kể mà vẫn giữ image sạch.
COPY: đưa build context vào image
COPY lấy file từ build context, chứ không phải từ toàn bộ host filesystem.
COPY package.json ./ COPY server.js ./
Khác biệt giữa
COPY
và
ADD
, cùng lý do nên mặc định dùng
COPY
, đã nói ở mục "Bộ khung của một Dockerfile" phía trên.
Build context chính là thư mục cuối cùng trong lệnh docker build ... .. .dockerignore sẽ lọc bớt những gì được gửi vào Docker daemon/BuildKit trước khi COPY thực sự chạy.
Nếu thiếu .dockerignore, node_modules, .git, .env, build artifact, file backup hay log có thể vô tình bị gửi vào build context. Hậu quả là build chậm hơn, cache khó đoán hơn, image phình to, và có rủi ro secret bị lọt vào layer.
.dockerignore không phải là secret manager — nó chỉ là một lớp chặn build context. Secret vẫn phải không nằm trong source repository, không được COPY vào image, và không được hardcode qua ENV trong Dockerfile.

Build cache: thứ tự Dockerfile là một quyết định về performance
Docker nhìn vào từng instruction và input của nó để quyết định có reuse cache hay không. Dockerfile trong lab copy package manifest trước, install dependency sau, rồi mới copy application source vào sau cùng.
COPY package.json ./ RUN npm install --omit=dev COPY server.js ./
Nếu chỉ sửa server.js, cache của npm install vẫn có thể được tái sử dụng. Nếu sửa package.json, layer dependency bắt buộc phải chạy lại — đây là điều hợp lý, vì dependency thật sự đã thay đổi.
Để thấy rõ sự khác biệt:
docker build --progress=plain --tag dockerfile-101:local . # sửa một dòng response trong server.js docker build --progress=plain --tag dockerfile-101:local .

Build cache không nên được dùng như lý do để bỏ qua npm ci. Cache giúp tối ưu tốc độ build, còn lockfile mới là thứ đảm bảo dependency resolution có thể tái lập lại đúng y hệt ở mọi lần build.
CMD: default command có thể bị override
CMD là command mặc định khi container chạy, nếu người dùng không truyền command khác.
CMD ["npm", "start"]
Dạng JSON array này là exec form — Docker chạy process trực tiếp, không thông qua shell trung gian. Điều này giúp việc forward signal rõ ràng hơn.
Override command:
docker run --rm dockerfile-101:local node --version
Container vẫn dùng đúng image, nhưng node --version sẽ thay thế cho CMD ban đầu.
ENTRYPOINT: biến image thành executable cố định
ENTRYPOINT định nghĩa executable chính của image. Argument truyền từ docker run image arg1 thường được nối thêm vào sau ENTRYPOINT (khi ENTRYPOINT ở exec form).
ENTRYPOINT ["node"] CMD ["server.js"]
Lúc này:
docker run --rm example-image --version
sẽ tương đương với node --version.
ENTRYPOINT phù hợp khi image đóng gói một CLI hay một wrapper cố định. Nhưng nó cũng khiến việc debug khó hơn nếu không cho phép override dễ dàng. Với một application web thông thường, chỉ dùng CMD thường dễ hiểu hơn. Nếu cần một entrypoint script để render config, chạy permission setup, hoặc validate biến môi trường, script đó cần kết thúc bằng exec để application nhận trực tiếp SIGTERM từ Docker, thay vì bị script cha giữ lại.
#!/bin/sh set -eu # setup ngắn, không chạy migration destructive ở đây exec node server.js
Vì sao "npm start" không phải lựa chọn tốt nhất cho signal handling
Trong lab ở trên, mình dùng CMD ["npm", "start"] cho đơn giản, nhưng cần biết rõ một điểm: npm sẽ spawn ra một process con là node server.js, và bản thân npm mới là process nhận PID 1 bên trong container. Một số phiên bản npm không forward SIGTERM xuống đúng process con một cách đáng tin cậy, khiến docker stop phải chờ hết timeout rồi mới kill cứng, thay vì để app tự tắt êm.
Hai cách xử lý phổ biến:
# Cách 1: bỏ qua npm, gọi thẳng node CMD ["node", "server.js"] # Cách 2: giữ npm nhưng dùng init process nhẹ để forward signal đúng cách RUN apt-get update \ && apt-get install -y --no-install-recommends tini \ && rm -rf /var/lib/apt/lists/* ENTRYPOINT ["/usr/bin/tini", "--"] CMD ["npm", "start"]
Với ứng dụng chỉ có một entrypoint là Node, cách 1 vừa đơn giản vừa tránh hẳn vấn đề. tini (hoặc dumb-init) chỉ thật sự cần khi mình bắt buộc phải giữ một process manager ở giữa mà không thể bỏ qua.
ENV, ARG và secret
ENV tạo ra một environment variable còn tồn tại xuyên suốt cả image lẫn container runtime:
ENV NODE_ENV=production
ARG thì chỉ tồn tại trong build stage, trừ khi được copy sang ENV:
ARG APP_VERSION LABEL org.opencontainers.image.revision=$APP_VERSION
Mình không nên truyền API key qua ARG rồi nghĩ rằng nó đã an toàn. Build arg có thể xuất hiện lại trong build history/metadata hoặc trong layer tùy theo cách dùng. Cũng không nên COPY .env vào image. Secret ở runtime nên thuộc về Docker secret, CI secret, Secrets Manager/SSM, hoặc cơ chế workload identity tùy theo platform đang triển khai.
HEALTHCHECK: cho Docker biết khi nào container thật sự "khỏe"
Container ở trạng thái Up chỉ có nghĩa là process chưa exit, không có nghĩa là service bên trong đã sẵn sàng nhận request. HEALTHCHECK cho phép Docker tự kiểm tra định kỳ:
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
CMD node -e "require('http').get('http://127.0.0.1:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"
Sau khi build lại image với instruction này, docker ps sẽ hiển thị thêm trạng thái healthy/unhealthy cho container:
docker build --tag dockerfile-101:local .
docker run -d --rm --name dockerfile-101 -p 3000:3000 dockerfile-101:local
docker ps --filter name=dockerfile-101
docker inspect dockerfile-101 --format '{{json .State.Health}}'
Đây chính là thông tin mà Compose dùng cho depends_on: condition: service_healthy (đã nhắc ở bài Volume và network), và cũng là nền tảng cho readiness/liveness probe khi loạt bài đi tới Kubernetes.
USER: đừng để app chạy bằng root chỉ vì "local chạy được"
Mặc định, nếu Dockerfile không khai báo USER, process bên trong container sẽ chạy bằng root. Điều này chạy được, nhưng root bên trong container vẫn là một quyền hạn không cần thiết cho một HTTP server chỉ đọc file và trả JSON.
FROM node:24-bookworm-slim WORKDIR /app COPY package.json ./ RUN npm install --omit=dev COPY server.js ./ RUN groupadd --system app && useradd --system --gid app --home /app app \ && chown -R app:app /app USER app ENV NODE_ENV=production EXPOSE 3000 CMD ["node", "server.js"]
Vài điểm cần lưu ý khi thêm USER:
-
chowncần chạy trước khiUSERchuyển sang, nếu không user mới sẽ không có quyền ghi vào thư mục ứng dụng. - Một số image base (như
node:*-alpine) đã có sẵn usernodekhông cần tạo lại — chỉ cầnUSER node. - Nếu app cần ghi file ở một path cụ thể lúc runtime (ví dụ thư mục cache tạm), path đó cũng cần được
chownđúng cho user non-root, hoặc mount volume với quyền phù hợp như đã nói ở bài trước.
EXPOSE là documentation, không phải firewall
EXPOSE 3000
EXPOSE chỉ ghi lại metadata rằng image này dự kiến sẽ listen ở port 3000 — nó không tự publish port ra host. docker run -p 3000:3000 hoặc ports: trong Compose mới thật sự tạo ra host binding.
Kiểm tra image sau build
docker image ls dockerfile-101:local docker history dockerfile-101:local docker image inspect dockerfile-101:local
Nhìn vào history để phát hiện layer nào bất thường về kích thước. Nhưng đừng dùng docker history để "chứng minh" image an toàn — nó không scan CVE, không chạy test application, và cũng không biết gì về cấu hình secret ở runtime.
Để thật sự kiểm tra lỗ hổng bảo mật, cần một bước riêng bằng công cụ scan CVE, ví dụ:
docker scout cves dockerfile-101:local
hoặc các công cụ tương đương như Trivy, Snyk, Grype. Bước này nên là một stage bắt buộc trong CI, chạy ngay sau khi build xong và trước khi image được phép push lên registry — không phải việc "làm khi rảnh".
Những lỗi cần tránh
COPY . . trước dependency install Bất kỳ thay đổi nào trong source cũng sẽ làm invalid cache của bước cài dependency. Luôn copy lockfile/package manifest trước.
Bỏ.dockerignore node_modules, .env, .git, .next, hay test artifact ở local có thể bị copy/ship nhầm vào build context nếu thiếu file này.
Dùng shell form khi không thật sự cần
CMD npm start
Shell form đôi khi cần thiết cho việc expansion hoặc dùng shell feature, nhưng việc thêm /bin/sh -c phía sau khiến signal forwarding phức tạp hơn. Nên ưu tiên exec form khi có thể.
Chạy app bằng root vì "local chạy được" Runtime user nên là non-root ngay từ Dockerfile, như phần USER ở trên, thay vì để tới lúc hardening mới quay lại sửa.
Bỏ qua HEALTHCHECK vì "container chạy là được rồi" Thiếu healthcheck khiến orchestrator (Compose hay Kubernetes sau này) không có cách nào phân biệt được một container đang thật sự phục vụ request với một container đã treo nhưng process chưa crash.
Tổng kết
Nhìn lại toàn bộ instruction đã đi qua, có một ranh giới xuyên suốt mọi quyết định trong bài: thứ gì thuộc về build-time, thứ gì thuộc về runtime. FROM, WORKDIR, RUN, COPY tạo ra filesystem của image — chạy một lần, đóng băng lại thành layer. CMD, ENTRYPOINT, ENV (khi không bị ARG che khuất), và HEALTHCHECK mới là thứ quyết định container sống ra sao sau khi image đã build xong. Nhầm lẫn giữa hai thế giới này — chạy migration bằng RUN, hay tưởng ARG là nơi giấu secret an toàn — là nguồn gốc của phần lớn lỗi khó hiểu khi làm việc với Docker.
Ba nguyên tắc "mỏ neo" nên luôn mang theo khi viết hoặc review một Dockerfile:
-
Cache order không phải chi tiết vặt, mà là thiết kế. Copy thứ ít đổi trước, thứ hay đổi sau. Một Dockerfile đặt
COPY . .trướcnpm installkhông sai về mặt chức năng, nhưng sai về mặt tư duy — nó biến build cache, vốn là công cụ tiết kiệm thời gian, thành vô dụng. -
Build-time không phải nơi cất secret, và root không phải trạng thái mặc định chấp nhận được.
ARGkhông phải secret manager,.envkhông nên nằm trong build context, và USER non-root nên là lựa chọn đầu tiên chứ không phải bước "hardening" làm sau cùng khi rảnh. - Image nhỏ và image an toàn là hai mục tiêu riêng, cùng chung một công cụ. Multi-stage build giúp cả hai: bớt kích thước bằng cách bỏ toolchain build khỏi stage cuối, và bớt bề mặt tấn công bằng cách stage cuối không còn compiler hay dependency thừa để kẻ tấn công lợi dụng.
Một Dockerfile viết tốt không chỉ build ra image chạy được — nó còn ghi lại rõ ràng: image này build từ nền gì, cache được tổ chức ra sao để không lãng phí thời gian CI, ai được quyền chạy process bên trong, và Docker biết dựa vào đâu để xác nhận container đang "khỏe" chứ không chỉ "còn sống". Từ những layer riêng lẻ này, bước tiếp theo tự nhiên là để Compose (đã nói ở bài trước) và sau này là Kubernetes, phối hợp nhiều image như vậy lại thành một hệ thống hoàn chỉnh.