Dockerfile 101: FROM, RUN, COPY, CMD, ENTRYPOINT và build cache 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 mô tả một bước build và Docker dùng kết quả các bước đó để tạo layer/cache artifact. Tôi sẽ build một Node.js HTTP server cực nhỏ. Ví dụ đơn giản 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à tại sao
.dockerignore
quan trọng hơn nhiều người nghĩ. ## Lab source tối giản Tạo thư mục
dockerfile-101
với ba file sau.
package.json
:
json { "name": "dockerfile-101", "private": true, "type": "module", "scripts": { "start": "node server.js" } }
server.js
:
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
:
text node_modules .git .env npm-debug.log* coverage
Dockerfile:
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:
bash 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 tự xóa container sau khi process thoát. Image
dockerfile-101:local
vẫn còn và có thể tạo container mới. ## FROM: chọn runtime base, không chỉ chọn kích thước
FROM node:24-bookworm-slim
là base image. Từ đó các instruction sau được áp dụng. Base image quyết định OS userspace, package manager, libc, CA certificates và khả năng chạy native dependency.
slim
thường giảm bớt package không cần cho runtime, nhưng không đồng nghĩa luôn dùng Alpine. Nhiều Node package có native module. Alpine dùng musl libc, còn Debian dùng glibc. Trước khi đổi base image, cần build/test native dependency và image processing thật. Pin version ít nhất theo major/minor khi cần reproducibility. Production release nên có policy rõ cho base image update và security patch, không dùng tag mơ hồ chỉ vì nó ngắn. ## WORKDIR: đặt context của instruction sau
WORKDIR /app
tạo/chuyển working directory cho
RUN
,
COPY
,
CMD
dạng shell và runtime process sau nó. Không cần
RUN mkdir -p /app
trước.
dockerfile WORKDIR /app COPY package.json ./
Sau lệnh này, file sẽ là
/app/package.json
trong image. ## RUN: chạy khi build image
RUN
chạy trong build stage, tạo filesystem delta cho image. Nó không chạy mỗi lần container start.
dockerfile RUN npm install --omit=dev
Sau build, dependency đã nằm trong image layer. Nếu app cần migrate database ở runtime, không nên viết migration dưới
RUN
; build machine không có quyền và cũng không nên kết nối production database. Một lỗi layer phổ biến:
dockerfile RUN apt-get update RUN apt-get install -y curl
Tốt hơn:
dockerfile RUN apt-get update \ && apt-get install -y --no-install-recommends curl \ && rm -rf /var/lib/apt/lists/*
Lý do là apt index nằm trong cùng layer tạo ra nó. Xóa ở layer sau không làm layer trước nhỏ lại. ## COPY: đưa build context vào image
COPY
lấy file từ build context, không phải từ toàn bộ host filesystem.
dockerfile COPY package.json ./ COPY server.js ./
Build context là thư mục cuối trong command
docker build ... .
.
.dockerignore
lọc thứ được gửi vào Docker daemon/buildkit trước khi
COPY
chạy. Nếu thiếu
.dockerignore
,
node_modules
,
.git
,
.env
, build artifact, backup và log có thể bị gửi vào build context. Hậu quả gồm build chậm, cache khó đoán, image phình và rủi ro secret bị đưa vào layer. [HÌNH 1 — Build context] Tên file gợi ý:
docker-build-context-and-ignore.webp
text project directory |-- source files --------> Docker build context ------> COPY vào image |-- .env --------------X .dockerignore loại bỏ |-- node_modules ------X |-- .git --------------X
.dockerignore
không phải secret manager. Nó là lớp chặn build context. Secret phải không nằm trong source repository, không được
COPY
vào image và không được hardcode qua Dockerfile
ENV
. ## CMD: default command có thể bị override
CMD
là command mặc định khi container chạy nếu user không truyền command khác.
dockerfile CMD ["npm", "start"]
Dạng JSON array là exec form. Docker chạy process trực tiếp, không thông qua shell. Điều này giúp signal handling rõ hơn. Override command:
bash docker run --rm dockerfile-101:local node --version
Container vẫn dùng image, nhưng
node --version
thay
CMD
. ## ENTRYPOINT: biến image thành executable cố định
ENTRYPOINT
định nghĩa executable chính. Các argument từ
docker run image arg1
thường được append vào ENTRYPOINT exec form.
dockerfile ENTRYPOINT ["node"] CMD ["server.js"]
Lúc này:
bash docker run --rm example-image --version
tương đương
node --version
. ENTRYPOINT phù hợp cho image đóng gói một CLI hoặc wrapper cố định. Nhưng nó cũng làm debug khó hơn nếu không cho override. Với application web thông thường, chỉ
CMD
thường dễ hiểu hơn. Nếu cần script entrypoint để render config, chạy permission setup hoặc validate env, script phải kết thúc bằng
exec
để application nhận SIGTERM trực tiếp.
sh #!/bin/sh set -eu # setup ngắn, không chạy migration destructive ở đây exec node server.js
Build cache: thứ tự Dockerfile là performance design Docker xem instruction và input của instruction đó để quyết định reuse cache. Dockerfile lab copy package manifest trước, install dependency sau, rồi mới copy application source.
dockerfile COPY package.json ./ RUN npm install --omit=dev COPY server.js ./
Nếu chỉ sửa
server.js
,
npm install
cache có thể được reuse. Nếu sửa
package.json
, dependency layer phải chạy lại, đó là điều hợp lý. Để thấy sự khác nhau:
bash 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 .
[HÌNH 2 — Cache hit và cache invalidation] Tên file gợi ý:
dockerfile-cache-hit.webp
Alt text:
Sửa application source chỉ làm rebuild layer COPY source trở xuống; sửa package manifest làm dependency install chạy lại.
Build cache không được dùng như lý do để bỏ
npm ci
. Cache tối ưu tốc độ, lockfile mới đảm bảo dependency resolution tái lập được. ## ENV, ARG và secret
ENV
tạo environment variable còn tồn tại trong image/container runtime:
dockerfile ENV NODE_ENV=production
ARG
chỉ có trong build stage nếu không được copy sang ENV:
dockerfile ARG APP_VERSION LABEL org.opencontainers.image.revision=$APP_VERSION
Không truyền API key qua
ARG
rồi nghĩ nó an toàn. Build arg có thể xuất hiện trong build history/metadata hoặc layer tùy cách dùng. Không
COPY .env
vào image. Secret runtime thuộc về Docker secret, CI secret, Secrets Manager/SSM hoặc workload identity flow tùy platform. ## EXPOSE là documentation, không phải firewall
dockerfile EXPOSE 3000
EXPOSE
ghi metadata rằng image dự kiến listen port 3000. Nó không tự publish port ra host.
docker run -p 3000:3000
hoặc Compose
ports:
mới tạo host binding. ## Kiểm tra image sau build
bash docker image ls dockerfile-101:local docker history dockerfile-101:local docker image inspect dockerfile-101:local
Nhìn history để xem layer có bất thường không. Nhưng đừng dùng
docker history
để chứng minh image secure. Nó không scan CVE, không chạy test application và không biết runtime secret configuration. ## Những lỗi cần tránh ###
COPY . .
trước dependency install Mọi source change invalidates dependency cache. Copy lockfile/package manifest trước. ### Bỏ
.dockerignore
Local
node_modules
,
.env
,
.git
,
.next
hoặc test artifact có thể bị copy/ship vào build context. ### Dùng shell form khi không cần
dockerfile CMD npm start
Shell form đôi khi cần expansion hoặc shell feature, nhưng thêm
/bin/sh -c
làm signal forwarding phức tạp hơn. Ưu tiên exec form khi có thể. ### Chạy app bằng root vì “local chạy được” Runtime user nên non-root. Phần hardening sau sẽ đi sâu vào user, writable path và shutdown. ## Checklist cuối bài - [ ] Biết
RUN
chạy lúc build,
CMD
chạy lúc container start. - [ ] Biết
COPY
chỉ thấy build context đã qua
.dockerignore
. - [ ] Đặt dependency manifest trước application source để tận dụng cache. - [ ] Phân biệt CMD và ENTRYPOINT. - [ ] Không đưa
.env
hay secret vào build context/image. - [ ] Hiểu
EXPOSE
không publish port. ## Bài tiếp theo Bài tiếp theo so sánh
single-stage và multi-stage build
. Tôi sẽ dùng cùng Node app để nhìn dependency build-time bị leak vào runtime image như thế nào và tách nó bằng Docker stage.