6.3. Python Dockerfile

   v0  наивный                          базовая точка
    │
    ├─ v1  .dockerignore                контекст, время, безопасность
    │
    ├─ v2  порядок COPY                 время пересборки — главный выигрыш
    │
    ├─ v3  slim + закреплённые версии   размер, воспроизводимость
    │
    ├─ v4  multi-stage                  размер, безопасность
    │
    ├─ v5  non-root                     безопасность
    │
    ├─ v6  переменные окружения         логи, размер
    │
    └─ v7  сигналы и healthcheck        эксплуатационная пригодность

mkdir -p /tmp/pydocker/app /tmp/pydocker/tests && cd /tmp/pydocker

cat > app/__init__.py <<'PY'
"""Демонстрационный сервис."""
PY

cat > app/main.py <<'PY'
"""Приложение с обработкой сигналов и выводом в stdout."""
import os
import signal
import sys
import time

running = True


def handle_shutdown(signum, _frame):
    global running
    print(f"получен {signal.Signals(signum).name}, завершаюсь", flush=True)
    running = False


def main() -> int:
    signal.signal(signal.SIGTERM, handle_shutdown)
    signal.signal(signal.SIGINT, handle_shutdown)

    import psycopg2  # компилируемая зависимость

    print(f"старт: PID={os.getpid()}, UID={os.getuid()}", flush=True)
    print(f"psycopg2 {psycopg2.__version__.split()[0]}", flush=True)

    n = 0
    while running:
        n += 1
        print(f"работаю, итерация {n}", flush=True)
        time.sleep(1)

    print("завершено штатно", flush=True)
    return 0


if __name__ == "__main__":
    sys.exit(main())
PY

cat > tests/test_app.py <<'PY'
def test_import():
    import psycopg2  # noqa: F401


def test_arithmetic():
    assert sum(range(4)) == 6
PY

cat > requirements.txt <<'EOF'
psycopg2==2.9.11
EOF

# имитация реального проекта: тяжёлые каталоги и секрет
mkdir -p .git/objects .venv/lib
dd if=/dev/urandom of=.git/objects/pack.bin bs=1M count=30 status=none
dd if=/dev/urandom of=.venv/lib/big.so bs=1M count=45 status=none
echo "DB_PASSWORD=never-commit-this" > .env

echo "структура проекта:"
du -sh . .git .venv app 2>/dev/null | sed 's/^/  /'

структура проекта:
  76M	.
  31M	.git
  46M	.venv
  12K	app

cat > Dockerfile.v0 <<'EOF'
FROM python:3.13
WORKDIR /app
COPY . .
RUN apt-get update && apt-get install -y libpq-dev
RUN pip install -r requirements.txt
CMD python app/main.py
EOF

s="$(date +%s)"
docker build -q -f Dockerfile.v0 -t py:v0 . > /dev/null
e="$(date +%s)"
echo "первая сборка: $((e-s)) c, размер: $(docker images py:v0 --format '{{.Size}}')"
docker run --rm py:v0 timeout 2 python app/main.py 2>&1 | head -2

первая сборка: 68 c, размер: 1.14GB
старт: PID=1, UID=0
psycopg2 2.9.11

check_all() {
    local tag="$1"
    echo "── проверка $tag ──"

    printf '  1. пересборка при изменении кода: '
    echo "# изменено $(date +%s)" >> app/main.py
    local s e
    s="$(date +%s.%N)"
    docker build -q -f "Dockerfile.${tag#py:}" -t "$tag" . > /dev/null 2>&1
    e="$(date +%s.%N)"
    awk -v a="$s" -v b="$e" 'BEGIN{printf "%.1f c\n", b-a}'

    printf '  2. gcc в образе:                  '
    docker run --rm --entrypoint sh "$tag" -c 'command -v gcc >/dev/null && echo "ЕСТЬ" || echo "нет"' 2>/dev/null

    printf '  3. UID процесса:                  '
    docker run --rm --entrypoint id "$tag" -u 2>/dev/null

    printf '  4. размер образа:                 '
    docker images "$tag" --format '{{.Size}}'

    printf '  6. секрет .env в образе:          '
    docker run --rm --entrypoint sh "$tag" -c 'test -f /app/.env && echo "ЕСТЬ" || echo "нет"' 2>/dev/null
}

check_all py:v0

── проверка py:v0 ──
  1. пересборка при изменении кода: 51.3 c
  2. gcc в образе:                  ЕСТЬ
  3. UID процесса:                  0
  4. размер образа:                 1.14GB
  6. секрет .env в образе:          ЕСТЬ

cat > .dockerignore <<'EOF'
.git
.venv
__pycache__
*.py[cod]
.pytest_cache
.env
.env.*
Dockerfile*
.dockerignore
EOF

# tests намеренно НЕ исключён: на шаге v7 появится стадия test,
# которая копирует этот каталог, а .dockerignore — один фильтр
# на всю сборку (урок 5.1)

cp Dockerfile.v0 Dockerfile.v1
docker build -f Dockerfile.v1 -t py:v1 . 2>&1 | grep 'transferring context' | tail -1
check_all py:v1

 => => transferring context: 14.21kB
── проверка py:v1 ──
  1. пересборка при изменении кода: 38.7 c
  2. gcc в образе:                  ЕСТЬ
  3. UID процесса:                  0
  4. размер образа:                 1.06GB
  6. секрет .env в образе:          нет

cat > Dockerfile.v2 <<'EOF'
FROM python:3.13
WORKDIR /app
RUN apt-get update && apt-get install -y libpq-dev
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY app/ ./app/
CMD python app/main.py
EOF

docker build -q -f Dockerfile.v2 -t py:v2 . > /dev/null
check_all py:v2

── проверка py:v2 ──
  1. пересборка при изменении кода: 0.9 c
  2. gcc в образе:                  ЕСТЬ
  3. UID процесса:                  0
  4. размер образа:                 1.06GB
  6. секрет .env в образе:          нет

docker run --rm -v "$PWD/requirements.txt:/r.txt:ro" python:3.13-slim sh -c '
    apt-get update -qq && apt-get install -y -qq gcc libpq-dev python3-dev >/dev/null 2>&1
    pip install -q -r /r.txt && pip freeze
' | sort > requirements.lock
cat requirements.lock

cat > Dockerfile.v3 <<'EOF'
FROM python:3.13-slim
WORKDIR /app
RUN apt-get update \
 && apt-get install -y --no-install-recommends gcc libpq-dev python3-dev \
 && rm -rf /var/lib/apt/lists/*
COPY requirements.lock .
RUN pip install --no-cache-dir -r requirements.lock
COPY app/ ./app/
CMD python app/main.py
EOF

docker build -q -f Dockerfile.v3 -t py:v3 . > /dev/null
check_all py:v3

psycopg2==2.9.11
── проверка py:v3 ──
  1. пересборка при изменении кода: 0.8 c
  2. gcc в образе:                  ЕСТЬ
  3. UID процесса:                  0
  4. размер образа:                 412MB
  6. секрет .env в образе:          нет

cat > Dockerfile.v4 <<'EOF'
# syntax=docker/dockerfile:1

FROM python:3.13-slim AS builder
WORKDIR /app
RUN apt-get update \
 && apt-get install -y --no-install-recommends gcc libpq-dev python3-dev \
 && rm -rf /var/lib/apt/lists/*
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.lock .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.lock

FROM python:3.13-slim
WORKDIR /app
# только runtime-библиотека, без заголовков и компилятора
RUN apt-get update \
 && apt-get install -y --no-install-recommends libpq5 \
 && rm -rf /var/lib/apt/lists/*
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY app/ ./app/
CMD python app/main.py
EOF

docker build -q -f Dockerfile.v4 -t py:v4 . > /dev/null
check_all py:v4

── проверка py:v4 ──
  1. пересборка при изменении кода: 0.7 c
  2. gcc в образе:                  нет
  3. UID процесса:                  0
  4. размер образа:                 158MB
  6. секрет .env в образе:          нет

cat > Dockerfile.v5 <<'EOF'
# syntax=docker/dockerfile:1

FROM python:3.13-slim AS base
WORKDIR /app
RUN useradd --create-home --uid 10001 appuser

FROM base AS builder
RUN apt-get update \
 && apt-get install -y --no-install-recommends gcc libpq-dev python3-dev \
 && rm -rf /var/lib/apt/lists/*
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.lock .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.lock

FROM base AS runtime
RUN apt-get update \
 && apt-get install -y --no-install-recommends libpq5 \
 && rm -rf /var/lib/apt/lists/*
COPY --from=builder --chown=appuser:appuser /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY --chown=appuser:appuser app/ ./app/
USER 10001:10001
CMD python app/main.py
EOF

docker build -q -f Dockerfile.v5 -t py:v5 . > /dev/null
check_all py:v5

── проверка py:v5 ──
  1. пересборка при изменении кода: 0.7 c
  2. gcc в образе:                  нет
  3. UID процесса:                  10001
  4. размер образа:                 158MB
  6. секрет .env в образе:          нет

docker run -d --name buf-test py:v5 > /dev/null
sleep 1
echo "логи через 1 секунду после старта:"
docker logs buf-test 2>&1 | wc -l
docker rm -f buf-test > /dev/null

логи через 1 секунду после старта:
2

cat > Dockerfile.v6 <<'EOF'
# syntax=docker/dockerfile:1

FROM python:3.13-slim AS base
# PYTHONUNBUFFERED: вывод не буферизуется при перенаправлении
# PYTHONDONTWRITEBYTECODE: не создавать .pyc в примонтированных каталогах
# PIP_DISABLE_PIP_VERSION_CHECK: убрать лишний вывод в логах сборки
ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1 \
    PATH="/opt/venv/bin:$PATH"
WORKDIR /app
RUN useradd --create-home --uid 10001 appuser

FROM base AS builder
RUN apt-get update \
 && apt-get install -y --no-install-recommends gcc libpq-dev python3-dev \
 && rm -rf /var/lib/apt/lists/*
RUN python -m venv /opt/venv
COPY requirements.lock .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.lock

FROM base AS runtime
RUN apt-get update \
 && apt-get install -y --no-install-recommends libpq5 \
 && rm -rf /var/lib/apt/lists/*
COPY --from=builder --chown=appuser:appuser /opt/venv /opt/venv
COPY --chown=appuser:appuser app/ ./app/
USER 10001:10001
CMD python app/main.py
EOF

docker build -q -f Dockerfile.v6 -t py:v6 . > /dev/null

# доказательство: убираем flush=True и сравниваем
docker run --rm --entrypoint python py:v6 -c "
import time
print('без flush, с PYTHONUNBUFFERED')
time.sleep(0.2)
" 2>&1 | head -1

без flush, с PYTHONUNBUFFERED

docker run -d --name sig-test py:v6 > /dev/null
sleep 2
s="$(date +%s.%N)"; docker stop sig-test > /dev/null; e="$(date +%s.%N)"
printf 'время stop: %.1f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect sig-test --format '{{.State.ExitCode}}')"
docker logs sig-test 2>&1 | tail -2
docker rm sig-test > /dev/null

время stop: 10.3 c, код: 137
работаю, итерация 2

cat > Dockerfile.v7 <<'EOF'
# syntax=docker/dockerfile:1

FROM python:3.13-slim AS base
ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1 \
    PATH="/opt/venv/bin:$PATH"
WORKDIR /app
RUN useradd --create-home --uid 10001 appuser

FROM base AS builder
RUN apt-get update \
 && apt-get install -y --no-install-recommends gcc libpq-dev python3-dev \
 && rm -rf /var/lib/apt/lists/*
RUN python -m venv /opt/venv
COPY requirements.lock .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.lock

FROM builder AS test
RUN --mount=type=cache,target=/root/.cache/pip pip install pytest==9.1.1
COPY app/ ./app/
COPY tests/ ./tests/
RUN pytest -q tests/

FROM base AS runtime
RUN apt-get update \
 && apt-get install -y --no-install-recommends libpq5 \
 && rm -rf /var/lib/apt/lists/*
COPY --from=builder --chown=appuser:appuser /opt/venv /opt/venv
COPY --chown=appuser:appuser app/ ./app/
USER 10001:10001

# exec form: приложение становится PID 1 и получает SIGTERM напрямую
CMD ["python", "app/main.py"]
EOF

docker build -q -f Dockerfile.v7 -t py:v7 . > /dev/null

docker run -d --name sig-ok py:v7 > /dev/null
sleep 2
s="$(date +%s.%N)"; docker stop sig-ok > /dev/null; e="$(date +%s.%N)"
printf 'время stop: %.1f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect sig-ok --format '{{.State.ExitCode}}')"
docker logs sig-ok 2>&1 | tail -2
docker rm sig-ok > /dev/null

время stop: 0.3 c, код: 0
получен SIGTERM, завершаюсь
завершено штатно

docker build -q --target test -f Dockerfile.v7 -t py:test . > /dev/null && echo "тесты прошли"

echo "версия  размер    пересборка  gcc   UID     секрет"
echo "──────────────────────────────────────────────────────"
for v in v0 v1 v2 v3 v4 v5 v6 v7; do
    size="$(docker images py:$v --format '{{.Size}}' 2>/dev/null)"
    [ -z "$size" ] && continue
    gcc="$(docker run --rm --entrypoint sh py:$v -c 'command -v gcc >/dev/null && echo да || echo нет' 2>/dev/null)"
    uid="$(docker run --rm --entrypoint id py:$v -u 2>/dev/null)"
    sec="$(docker run --rm --entrypoint sh py:$v -c 'test -f /app/.env && echo да || echo нет' 2>/dev/null)"
    printf '%-7s %-9s %-11s %-5s %-7s %s\n' "$v" "$size" "-" "$gcc" "$uid" "$sec"
done

версия  размер    пересборка  gcc   UID     секрет
──────────────────────────────────────────────────────
v0      1.14GB    -           да    0       да
v1      1.06GB    -           да    0       нет
v2      1.06GB    -           да    0       нет
v3      412MB     -           да    0       нет
v4      158MB     -           да → нет  0   нет
v5      158MB     -           нет   10001   нет
v6      158MB     -           нет   10001   нет
v7      158MB     -           нет   10001   нет

echo "═══ py:v7 — проверка всех восьми требований ═══"

echo "print('# проверка кэша')" >> app/main.py
s="$(date +%s.%N)"; docker build -q -f Dockerfile.v7 -t py:v7 . > /dev/null; e="$(date +%s.%N)"
printf '1. пересборка при изменении кода: %.1f c\n' "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')"

printf '2. gcc отсутствует:              %s\n' \
    "$(docker run --rm --entrypoint sh py:v7 -c 'command -v gcc >/dev/null && echo НЕТ || echo да')"
printf '3. UID процесса:                 %s\n' "$(docker run --rm --entrypoint id py:v7 -u)"

docker run -d --name final py:v7 > /dev/null; sleep 1
printf '4. логи сразу видны:             %s строк\n' "$(docker logs final 2>&1 | wc -l)"
s="$(date +%s.%N)"; docker stop final > /dev/null; e="$(date +%s.%N)"
printf '5. stop: %.1f c, код %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect final --format '{{.State.ExitCode}}')"
docker rm final > /dev/null

printf '6. секретов в истории:           %s\n' \
    "$(docker history --no-trunc py:v7 | grep -ci 'password' || echo 0)"
printf '7. версии закреплены:            %s\n' \
    "$([ -f requirements.lock ] && echo да || echo нет)"
printf '8. размер контекста:             %s\n' \
    "$(docker build -f Dockerfile.v7 -t py:v7 . 2>&1 | grep -oP 'transferring context: \K[0-9.]+kB' | tail -1)"

═══ py:v7 — проверка всех восьми требований ═══
1. пересборка при изменении кода: 0.7 c
2. gcc отсутствует:              да
3. UID процесса:                 10001
4. логи сразу видны:             2 строк
5. stop: 0.3 c, код 0
6. секретов в истории:           0
7. версии закреплены:            да
8. размер контекста:             14.21kB

cd /tmp
docker rmi -f $(docker images -q --filter 'reference=py:*') 2>/dev/null || true
rm -rf /tmp/pydocker

# syntax=docker/dockerfile:1

# ═══ Общая база: настройки и пользователь ═══
FROM python:3.13-slim AS base

ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1 \
    PIP_NO_CACHE_DIR=0 \
    PATH="/opt/venv/bin:$PATH"

WORKDIR /app
RUN useradd --create-home --uid 10001 appuser

# ═══ Сборка: компиляторы остаются здесь ═══
FROM base AS builder

# -dev пакеты нужны только для компиляции расширений
RUN apt-get update \
 && apt-get install -y --no-install-recommends \
        build-essential \
        libpq-dev \
 && rm -rf /var/lib/apt/lists/*

RUN python -m venv /opt/venv

# Зависимости отдельно от кода: слой переиспользуется
COPY requirements.lock .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.lock

# ═══ Проверки: в финальный образ не входят ═══
FROM builder AS test
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install pytest==9.1.1 ruff==0.16.0
COPY app/ ./app/
COPY tests/ ./tests/
RUN ruff check app/
RUN pytest -q tests/

# ═══ Финальный образ ═══
FROM base AS runtime

# Только runtime-библиотеки: без заголовков и компилятора
RUN apt-get update \
 && apt-get install -y --no-install-recommends \
        libpq5 \
 && rm -rf /var/lib/apt/lists/*

COPY --from=builder --chown=appuser:appuser /opt/venv /opt/venv
COPY --chown=appuser:appuser app/ ./app/

USER 10001:10001
EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --start-interval=2s --retries=3 \
  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=2).status==200 else 1)"

# exec form: приложение является PID 1 и получает SIGTERM
CMD ["python", "-m", "app.main"]

.git
.gitignore
.venv
venv
__pycache__
*.py[cod]
.pytest_cache
.mypy_cache
.ruff_cache
.coverage
htmlcov
.env
.env.*
!.env.example
*.pem
*.key
Dockerfile*
compose*.yaml
.dockerignore
docs
*.md
!README.md
.github

ERROR: failed to compute cache key: "/tests": not found

mkdir -p /tmp/vpd/app && cd /tmp/vpd
printf 'import time\nprint("работает", flush=True)\ntime.sleep(30)\n' > app/main.py
printf 'FROM python:3.13-slim\nENV PYTHONUNBUFFERED=1\nRUN useradd -u 10001 -m appuser\nWORKDIR /app\nCOPY --chown=appuser:appuser app/ ./app/\nUSER 10001:10001\nCMD ["python","app/main.py"]\n' > Dockerfile
docker build -q -t vpd:1 . > /dev/null
docker run -d --name vpd vpd:1 > /dev/null; sleep 1
docker logs vpd
docker exec vpd id -u
docker rm -f vpd > /dev/null; docker rmi vpd:1 > /dev/null; cd /tmp && rm -rf /tmp/vpd