Đóng gói ứng dụng Python bằng Docker: Dockerfile, compose
Đưa ứng dụng FastAPI vào container: Dockerfile tối ưu cache, .dockerignore, user không phải root, biến môi trường và docker compose.
Học xong bài này, bạn sẽ
- Viết Dockerfile cho ứng dụng FastAPI
- Tối ưu image: cache layer, .dockerignore, user không phải root
- Chạy kèm biến môi trường, volume bằng docker compose
Nên học trước: asyncio: async và await
Nội dung bài viết
"Máy em chạy được mà!" là câu nói quen thuộc khi code chạy tốt trên máy lập trình viên nhưng lỗi trên máy chủ: khác phiên bản Python, thiếu thư viện hệ thống, khác hệ điều hành. Docker đóng gói ứng dụng cùng mọi thứ nó cần (Python, thư viện, cấu hình) thành một image, chạy giống hệt nhau ở mọi nơi. Bài này đóng gói API quản lý công việc ở chặng 9 theo cách được khuyến nghị cho dự án dùng uv.
1. Khái niệm cơ bản
- Image: bản đóng gói chỉ đọc, gồm hệ điều hành tối giản, Python, thư viện và code. Giống "bản thiết kế".
- Container: một phiên bản đang chạy của image, có hệ thống file và mạng riêng. Từ một image có thể chạy nhiều container.
- Dockerfile: công thức từng bước để tạo image. Mỗi lệnh tạo một layer (lớp); layer không đổi được dùng lại từ cache ở lần build sau.
- Volume: vùng lưu trữ nằm ngoài container, dữ liệu còn nguyên khi container bị xóa và tạo lại.
Cài Docker Desktop (Windows, macOS) hoặc Docker Engine (Linux), kiểm tra bằng docker --version và docker run hello-world.
2. Dockerfile cho dự án uv
Đặt file Dockerfile ở thư mục gốc dự án quan-ly-cong-viec (cạnh pyproject.toml và uv.lock):
# syntax=docker/dockerfile:1
FROM python:3.14-slim
# Lấy uv từ image chính thức, ghim phiên bản để build lặp lại được
COPY --from=ghcr.io/astral-sh/uv:0.13.6 /uv /uvx /bin/
ENV UV_COMPILE_BYTECODE=1 \
UV_LINK_MODE=copy \
PYTHONUNBUFFERED=1
WORKDIR /app
# Layer 1: chỉ cài thư viện. Chỉ build lại khi pyproject.toml hoặc uv.lock đổi
RUN --mount=type=cache,target=/root/.cache/uv \
--mount=type=bind,source=uv.lock,target=uv.lock \
--mount=type=bind,source=pyproject.toml,target=pyproject.toml \
uv sync --locked --no-install-project --no-dev
# Layer 2: chép code. Sửa code chỉ build lại từ đây, rất nhanh
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --locked --no-dev
# Chạy bằng người dùng thường, không dùng root
RUN useradd --create-home --uid 10001 app && mkdir /data && chown app /data
USER app
ENV PATH="/app/.venv/bin:$PATH" \
DATABASE_URL="sqlite:////data/cong_viec.db"
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=3s \
CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/suc-khoe')"
CMD ["fastapi", "run", "app/main.py", "--port", "8000"]
Giải thích những quyết định quan trọng:
python:3.14-slim: image Python chính thức bản rút gọn (Debian tối giản), nhỏ hơn nhiều so với bản đầy đủ. Ghim phiên bản Python cụ thể, không dùnglatest.- Hai lần
uv sync: thư viện thay đổi ít, code thay đổi liên tục. Cài thư viện ở layer riêng trước khi chép code, nên mỗi lần sửa code Docker dùng lại layer thư viện từ cache, build chỉ mất vài giây.--mount=type=cachegiữ cache tải về của uv giữa các lần build. --locked: dừng build nếuuv.lockkhông khớppyproject.toml, bảo đảm image chứa đúng phiên bản đã test.--no-dev: không cài pytest, ruff, mypy vào image chạy thật.- Người dùng không phải root: nếu ứng dụng bị khai thác lỗ hổng, kẻ tấn công không có quyền root trong container. Thư mục
/datachứa file SQLite được giao cho người dùngapp. fastapi runchạy chế độ production (không tự nạp lại) và mặc định lắng nghe0.0.0.0, nhận được kết nối từ ngoài container.PYTHONUNBUFFERED=1cho log hiện ngay lập tức.HEALTHCHECKgọi endpoint/suc-khoecủa dự án; image slim không cócurlnên dùng chính Python để gọi.
3. .dockerignore
Những gì không được chép vào image (giảm kích thước, tránh lộ bí mật, tránh ghi đè môi trường ảo dựng sẵn trong image):
.venv/
__pycache__/
*.pyc
.pytest_cache/
.mypy_cache/
.ruff_cache/
.git/
*.db
.env
tests/
.venv của máy bạn phụ thuộc hệ điều hành (Windows), không chạy được trong container Linux; image tự tạo môi trường ảo riêng. .env chứa bí mật, không bao giờ đóng vào image.
4. Build và chạy
$ docker build -t quan-ly-cong-viec:1.0 .
$ docker run --rm -p 8000:8000 -e SECRET_KEY=thu-nghiem -v du_lieu_cv:/data quan-ly-cong-viec:1.0
$ docker ps # xem container đang chạy, cột STATUS có (healthy)
$ docker logs <id_container> # xem log
$ docker exec -it <id_container> bash # vào bên trong container để kiểm tra
-t ten:phien_banđặt tên và nhãn cho image.-p 8000:8000nối cổng 8000 của máy bạn với cổng 8000 trong container. Mởhttp://localhost:8000/docs.-etruyền biến môi trường: bí mật đưa vào lúc chạy, không ghi vào Dockerfile.-v du_lieu_cv:/datagắn volume têndu_lieu_cvvào/data: xóa container rồi chạy lại, dữ liệu vẫn còn.
5. docker compose: cấu hình bằng file
Gõ lệnh docker run dài mỗi lần rất dễ sai. Ghi cấu hình vào compose.yaml:
services:
api:
build: .
ports:
- "8000:8000"
environment:
SECRET_KEY: ${SECRET_KEY:?Hãy đặt SECRET_KEY trong file .env}
volumes:
- du_lieu:/data
restart: unless-stopped
volumes:
du_lieu:
$ python -c "import secrets; print('SECRET_KEY=' + secrets.token_hex(32))" > .env
$ docker compose up -d --build # build và chạy nền
$ docker compose logs -f api # theo dõi log
$ docker compose down # dừng và xóa container (volume vẫn giữ)
Docker Compose tự đọc file .env cùng thư mục để thay biến ${SECRET_KEY}; cú pháp :? làm lệnh báo lỗi ngay nếu quên đặt biến. restart: unless-stopped tự khởi động lại container khi ứng dụng sập hoặc máy khởi động lại. Khi cần PostgreSQL thay cho SQLite, chỉ cần thêm một service db vào file này và đổi DATABASE_URL.
Tóm tắt
- Image là bản đóng gói, container là bản đang chạy; Dockerfile gồm các layer được cache.
- Dự án uv: cài thư viện (
uv sync --locked --no-install-project --no-dev) trước khi chép code để tận dụng cache. - Ghim phiên bản image; chạy bằng người dùng không phải root;
.dockerignoreloại.venv,.env. - Bí mật truyền bằng biến môi trường lúc chạy; dữ liệu nằm trong volume; dùng
compose.yamlcho cấu hình lặp lại.
Bài tập
Bài 1. Đóng gói API quản lý công việc
Thêm Dockerfile và .dockerignore vào dự án chặng 9, build image, chạy container, đăng ký tài khoản và tạo công việc qua /docs. Sau đó xóa container, chạy lại với cùng volume và xác nhận dữ liệu còn.
Xem gợi ý
Trước khi build, chạy uv lock để có uv.lock (bước --locked cần nó). Xem kích thước image bằng docker images quan-ly-cong-viec. Nếu build lỗi ở bước uv sync --locked với thông báo lockfile cần cập nhật, chạy lại uv lock trên máy rồi build. Sửa một dòng code rồi build lại: các bước cài thư viện hiện CACHED, build xong trong vài giây.
Bài 2. compose với biến môi trường
Viết compose.yaml như mục 5, tạo .env chứa SECRET_KEY ngẫu nhiên, chạy docker compose up -d --build. Thử xóa dòng trong .env và chạy lại để thấy thông báo lỗi.
Xem gợi ý
Khi thiếu biến, Compose dừng ngay với thông báo có chứa câu "Hãy đặt SECRET_KEY trong file .env" bạn đã viết. Kiểm tra trạng thái sức khỏe bằng docker compose ps: sau khoảng 30 giây cột trạng thái chuyển sang healthy nhờ HEALTHCHECK. Nhớ thêm .env vào .gitignore nếu chưa có.
Nguồn tham khảo: uv: Using uv in Docker; FastAPI in Containers - Docker; Docker: Building best practices; Docker Compose: Variable interpolation; Docker Hub: python.
Bài tập thực hành
- Đóng gói API quản lý công việc ở chặng 9 thành image, chạy container và gọi thử /docs.
- Viết compose.yaml chạy API với volume giữ file SQLite và biến môi trường SECRET_KEY.
Làm xong bài tập mới chuyển sang bài tiếp theo: tự viết code là cách duy nhất để nhớ lâu.


