⭐ Python Developer · Chặng 10Bài 4/6Bài học~60 phút

Đó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.

Đóng gói ứng dụng Python bằng Docker: Dockerfile, 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
  1. 1. Khái niệm cơ bản
  2. 2. Dockerfile cho dự án uv
  3. 3. .dockerignore
  4. 4. Build và chạy
  5. 5. docker compose: cấu hình bằng file
  6. Tóm tắt
  7. Bài tập

"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ùng latest.
  • 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=cache giữ cache tải về của uv giữa các lần build.
  • --locked: dừng build nếu uv.lock không khớp pyproject.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 /data chứa file SQLite được giao cho người dùng app.
  • fastapi run chạy chế độ production (không tự nạp lại) và mặc định lắng nghe 0.0.0.0, nhận được kết nối từ ngoài container. PYTHONUNBUFFERED=1 cho log hiện ngay lập tức.
  • HEALTHCHECK gọi endpoint /suc-khoe của dự án; image slim không có curl nê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:8000 nối cổng 8000 của máy bạn với cổng 8000 trong container. Mở http://localhost:8000/docs.
  • -e truyề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:/data gắn volume tên du_lieu_cv và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.

SQLite trong containerSQLite phù hợp khi chạy đúng một container. Muốn chạy nhiều bản sao ứng dụng song song (nhiều container, nhiều máy), chuyển sang PostgreSQL hoặc MySQL: nhiều tiến trình cùng ghi một file SQLite qua volume mạng sẽ gặp lỗi khóa và có thể hỏng dữ liệu.

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; .dockerignore loạ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.yaml cho 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

  1. Đó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.
  2. 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.

Bài tiếp theo
Ban biên tập HocFree

Chúng tôi viết những bài hướng dẫn dễ hiểu, thực tế để ai cũng có thể tự học lập trình và AI, hoàn toàn miễn phí.