การ Dockerize Python App

Node Dockerfile ที่คุณรู้จักอยู่แล้ว

ถ้าคุณเคย containerize Node/TypeScript app มาก่อน คุณรู้ pattern: copy package.json, รัน npm ci, copy source, build และรัน Python Dockerfile ตาม multi-stage logic เดียวกัน — แต่มี best practices เฉพาะ Python บางอย่างที่คุณต้องเข้าใจ

เทียบกันชัดๆ: Node vs Python Dockerfile

TypeScript

# ---- Node / TypeScript multi-stage Dockerfile ----
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser
EXPOSE 3000
CMD ["node", "dist/main.js"]

Python

# ---- Python multi-stage Dockerfile ----
FROM python:3.14-slim AS builder
WORKDIR /app

# ติดตั้ง build tools แล้วสร้าง venv ภายใน image
RUN python -m venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM python:3.14-slim AS runner
WORKDIR /app

# Copy pre-built venv จาก builder
COPY --from=builder /app/.venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"

# Copy application source
COPY src/ ./src/

# รันด้วย non-root user
RUN addgroup --system appgroup && adduser --system --ingroup appgroup appuser
USER appuser

EXPOSE 8000
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

เวอร์ชันที่ใช้ uv

ถ้าโปรเจกต์ใช้ uv (ดู venv, pip, uv และ Poetry) ให้ copy ตัว binary ของ uv มาจาก official image แล้วให้มันสร้าง environment จาก lock file วิธีนี้เร็วที่สุดและทำให้ image ตอน runtime ไม่มีเครื่องมือ build ติดไปด้วย

TypeScript

# ---- Node / TypeScript multi-stage Dockerfile ----
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser
EXPOSE 3000
CMD ["node", "dist/main.js"]

Python

# ---- uv multi-stage Dockerfile ----
FROM python:3.14-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app

ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy

# ติดตั้ง dependency ก่อน — cache ไว้จนกว่า lock file จะเปลี่ยน
COPY pyproject.toml uv.lock ./
RUN uv sync --locked --no-install-project --no-dev

COPY src/ ./src/
RUN uv sync --locked --no-dev

FROM python:3.14-slim AS runner
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY --from=builder /app/src ./src
ENV PATH="/app/.venv/bin:$PATH"

RUN addgroup --system appgroup && adduser --system --ingroup appgroup appuser
USER appuser

EXPOSE 8000
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

--locked ทำให้ build ล้มเหลวถ้า uv.lock ไม่ตรงกับ pyproject.toml แทนที่จะ resolve เวอร์ชันใหม่เงียบ ๆ เทียบได้กับ npm ci ที่ไม่ยอมให้หลุดจาก package-lock.json

Python Dockerfile แบบ production เต็มรูปแบบ พร้อม comment

# syntax=docker/dockerfile:1

# ---- Stage 1: Build / dependency installation ----
FROM python:3.14-slim AS builder

WORKDIR /app

# PYTHONDONTWRITEBYTECODE: don't write .pyc files (saves space)
# PYTHONUNBUFFERED: log output immediately (12-Factor: log to stdout)
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

# Create the virtual environment INSIDE the image
# This lets us copy the entire /app/.venv to the final stage
RUN python -m venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"

# Copy dependency manifest first (Docker layer caching)
COPY pyproject.toml uv.lock* requirements.txt* ./

# Install dependencies — no cache to keep image small
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

# ---- Stage 2: Runtime image ----
FROM python:3.14-slim AS runner

WORKDIR /app

# Copy the fully-populated venv from builder
COPY --from=builder /app/.venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH" \
    PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

# Copy application source (after deps — better cache hit on rebuilds)
COPY src/ ./src/

# Create and switch to a non-root user (security best practice)
RUN addgroup --system appgroup && \
    adduser --system --ingroup appgroup --no-create-home appuser
USER appuser

# Expose the port the app listens on
EXPOSE 8000

# CMD uses exec form (no shell wrapper — signals go directly to process)
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

ทำไมต้องสร้าง venv ภายใน Docker image?

รันในเทอร์มินัลของคุณเพื่อ build และรัน:

docker build -t my-python-app .
docker run -p 8000:8000 my-python-app

# Or with docker compose:
# docker compose up --build

🟦 PYTHONUNBUFFERED และ PYTHONDONTWRITEBYTECODE อธิบาย

สอง env vars นี้เป็นมาตรฐานใน Python Dockerfile ทุก production:

PYTHONUNBUFFERED=1 — ปกติ Python จะ buffer stdout/stderr ไว้ พออยู่ใน container จึงอาจไม่เห็น log โผล่มาเลยเพราะยังค้างอยู่ใน buffer ตั้งเป็น 1 เพื่อบังคับให้ flush ทันที ตรงตามข้อกำหนด 12-Factor ที่ให้ “log ออก stdout”

PYTHONDONTWRITEBYTECODE=1 — ปกติ Python เขียนไฟล์ .pyc ที่ compile แล้ววางคู่กับ source .py เพื่อให้ startup เร็วขึ้น แต่ใน container กลายเป็นขยะ เพราะกินพื้นที่ layer และอาจพา stale-cache bug มาด้วย ปิดทิ้งไปแล้ว image สะอาดกว่า

นักพัฒนา Node ไม่ต้องการ flags เหล่านี้เพราะ runtime model ของ Node ทำงานต่างกัน — นี่คือ footgun เฉพาะ Python

.dockerignore

เหมือน .gitignore สำหรับ Docker สร้างเสมอเพื่อหลีกเลี่ยงการ copy venv, cache และ secrets ลงใน image:

.venv/
__pycache__/
*.pyc
*.pyo
.pytest_cache/
.mypy_cache/
.ruff_cache/
.env
.env.*
*.log

ทำไมจึงควรสร้าง virtual environment ภายใน Docker image แทนที่จะใช้ system Python?

Docker กำหนดให้ทำตาม specification venv ภายใน image ให้เรา copy dependency set ที่ isolated ทั้งหมดอย่างสะอาดระหว่าง build และ runtime stages System Python ไม่มีใน slim images pip ปฏิเสธที่จะติดตั้งหากไม่มี venv

PYTHONUNBUFFERED=1 รับประกันอะไรใน containerized Python app?

Python รันเร็วขึ้นด้วยการข้าม GIL Python flush log ออก stdout ทันที ไม่ค้างไว้ใน buffer Python ข้ามการเขียนไฟล์ .pyc bytecode uvicorn รับฟังบน network interfaces ทั้งหมด

ใน multi-stage Dockerfile คุณนำ installed packages จาก builder stage เข้าสู่ runner stage อย่างไร?

RUN pip install อีกครั้งใน runner stage COPY --from=builder /app/.venv /app/.venv ADD venv /app/.venv Docker รวม layers ระหว่าง stages อัตโนมัติ

Submit

Mark as complete