Dockerfile: собираем образ по шагам

Dockerfile: собираем образ по шагам

Dockerfile - это рецепт сборки образа. Каждая строка - инструкция, каждая инструкция - шаг сборки: RUN, COPY и ADD создают новый слой, остальные меняют метаданные образа. Понимание слоёв и кэша - ключ к быстрым сборкам.

Анатомия Dockerfile

# базовый образ
FROM python:3.12-slim
# без буфера stdout: иначе логи в docker logs идут с задержкой
ENV PYTHONUNBUFFERED=1
# рабочая директория
WORKDIR /app
# копируем список зависимостей
COPY requirements.txt .
# устанавливаем зависимости
RUN pip install --no-cache-dir -r requirements.txt
# копируем остальной код
COPY . .
# документируем порт
EXPOSE 8000
# команда запуска
CMD ["python", "app.py"]

# в Dockerfile - комментарий только в начале строки: хвост FROM ... # ... Docker воспримет как аргументы инструкции, поэтому комментарии пишут отдельной строкой над ней.

Основные инструкции

ИнструкцияКогда выполняетсяЧто делает
FROMСборкаЗадаёт базовый образ
WORKDIRСборкаУстанавливает рабочую директорию
COPYСборкаКопирует файлы с хоста в образ
RUNСборкаВыполняет команду (создаёт слой)
CMDЗапускКоманда по умолчанию при docker run
ENTRYPOINTЗапускФиксированная команда (CMD - аргументы)
EXPOSEДокументацияУказывает порт (не пробрасывает!)
ENVСборка + ЗапускУстанавливает переменную окружения
ARGТолько сборкаBuild-time аргумент

⚠️ EXPOSE не пробрасывает порт

EXPOSE 8080 - это только документация для человека. Чтобы реально пробросить порт, нужен -p 8080:8080 при docker run. Без -p порт снаружи недоступен. А если -p падает с «port is already allocated», виновника ищут на хосте через ss -tlnp - как читать этот вывод, показано в уроке про процессы и порты Linux.

Слои и кэш

Dockerfile превращается в стек слоёв: RUN/COPY/ADD дают слои, WORKDIR и CMD - метаданные, контейнер добавляет writable layer сверху

Каждая инструкция FROM, COPY, RUN создаёт слой. Docker кэширует слои и переиспользует их при повторной сборке - пока входные данные не изменились.

# Плохо: любое изменение кода сбрасывает кэш pip install
FROM python:3.12-slim
WORKDIR /app
# <-- тут кэш слетает при любом изменении
COPY . .
# переустановка каждый раз
RUN pip install --no-cache-dir -r requirements.txt

# Хорошо: зависимости кэшируются отдельно от кода
FROM python:3.12-slim
WORKDIR /app
# меняется редко
COPY requirements.txt .
# кэшируется!
RUN pip install --no-cache-dir -r requirements.txt
# меняется часто - но pip install уже закэширован
COPY . .

ℹ️ Правило кэша

Ставь то, что меняется редко, в начало Dockerfile (зависимости), а то, что меняется часто (код) - в конец. Тогда Docker переиспользует верхние слои.

Интерпретируемому приложению компилятор не нужен: код копируется как есть, и одного образа хватает. У компилируемых языков этот же приём разворачивается в полноценный multi-stage build: сначала кэшируем зависимости и собираем бинарник в образе с компилятором, потом переносим только бинарник в чистый runtime - как это делается для Go.

Правильный порядок инструкций ускоряет повторную сборку в 10+ раз

.dockerignore

Файл .dockerignore работает как .gitignore - синтаксис шаблонов тот же, только исключает файлы не из коммита, а из контекста сборки. Без него COPY . . отправит в Docker всё, включая .venv, .git, .env:

# .dockerignore
__pycache__/
*.pyc
.venv/
.pytest_cache/
.git
.env
.env.*
*.log
.DS_Store

Зачем:

  • Скорость - Docker не копирует сотни мегабайт локального .venv
  • Безопасность - .env с секретами не попадает в образ
  • Кэш - изменения в .git не инвалидируют кэш COPY . .

COPY vs ADD

COPYADD
Копирует файлыДаДа
Распаковывает tar.gzНетДа (автоматически)
Скачивает по URLНетДа
ПредсказуемостьВысокаяНизкая (неявное поведение)
РекомендацияИспользуй по умолчаниюРаспаковка tar или скачивание с --checksum

В 99% случаев используй COPY. ADD - только если нужно распаковать локальный архив в одну инструкцию или скачать удалённый артефакт с проверкой хеша (ADD --checksum=sha256:... <url> /dest): так кеш сборки точнее, чем у RUN curl.

CMD vs ENTRYPOINT

# CMD - команда по умолчанию, легко заменить при run
CMD ["python", "app.py"]
# docker run myapp                     → python app.py
# docker run myapp python --version    → python --version (CMD заменён)

# ENTRYPOINT - фиксированная команда, CMD добавляет аргументы
ENTRYPOINT ["python"]
CMD ["app.py"]
# docker run myapp               → python app.py
# docker run myapp migrate.py    → python migrate.py (только аргумент заменён)

ℹ️ Exec-форма vs shell-форма

Всегда используй exec-форму (массив): CMD ["python", "app.py"]. Shell-форма CMD python app.py запускает команду через /bin/sh -c, что создаёт лишний процесс и мешает graceful shutdown (SIGTERM не доходит до приложения). Что приложение должно делать с этим сигналом - дождаться активных запросов и закрыть соединения - показано в graceful shutdown Go-сервера.

Non-root пользователь

По умолчанию процесс в контейнере работает от root. Это небезопасно - если злоумышленник эксплуатирует уязвимость, он получит root:

FROM python:3.12-slim
WORKDIR /app

# Создаём системного пользователя
RUN groupadd --system appgroup && useradd --system --gid appgroup appuser

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

COPY . .

# Переключаемся на non-root
USER appuser

CMD ["python", "app.py"]

⚠️ USER и права на файлы

Переключай USER после COPY и RUN, которым нужны права записи. Если pip install запущен от appuser, он упрётся в права на системный site-packages: либо Permission denied, либо пакеты молча уедут в домашний каталог пользователя. Откуда вообще берётся Permission denied и как устроены владелец, группа и биты rwx - в уроке про права доступа в Linux: внутри контейнера действуют ровно те же правила.

Best practices: чеклист

  1. Один процесс - один контейнер (не засовывай nginx + приложение + postgres в один образ)
  2. Сначала зависимости, потом код (кэш слоёв)
  3. .dockerignore - исключай .venv, __pycache__, .git, .env
  4. Минимальный базовый образ - slim или alpine вместо полного ubuntu (alpine 5 МБ vs 70 МБ). Оговорка для Python: на alpine (musl) часть колёс не подходит и собирается из исходников, поэтому для Python чаще берут slim
  5. Non-root USER - безопасность
  6. Exec-форма CMD - CMD ["python", "app.py"], не CMD python app.py
  7. COPY вместо ADD - предсказуемость

Насколько далеко стоит идти в урезании образа (после alpine есть distroless и scratch) и чем за это платишь - тем, что внутри не остаётся ни sh, ни wget, и обычный docker exec sh перестаёт работать - разбираем в уроке про отладку, healthcheck и размер образа.

Мини-задание

  • Создай Dockerfile для простого Python-приложения (hello world на http.server, как в мини-практике ниже)
  • Добавь .dockerignore с __pycache__/, .venv/, .git, .env
  • Собери: docker build -t myapp .
  • Запусти: docker run --rm -p 8000:8000 myapp
  • Проверь размер образа: docker images myapp
  • Добавь USER - пересобери и проверь: docker run --rm myapp whoami

Итог

  • Dockerfile - рецепт: каждая инструкция создаёт слой, слои кэшируются.
  • Порядок инструкций определяет эффективность кэша: зависимости → код.
  • .dockerignore = безопасность + скорость + стабильный кэш.
  • COPY > ADD, exec-форма CMD > shell-форма, non-root USER > root.
  • Один контейнер = один процесс. Не мешай сервисы в одном образе.

Типичная ошибка

Самая частая - COPY . . перед pip install/go mod download. Результат: любое изменение в коде (даже пробел в README) сбрасывает кэш зависимостей. Сборка из 10 секунд превращается в 2 минуты.

Вторая ошибка - забыть .dockerignore. Без него COPY . . копирует .venv (сотни МБ), .git (весь репозиторий) и .env (секреты прямо в образе).

Мини-практика (10-15 минут)

Проверь влияние порядка инструкций на кэш:

# 1. Создай простое приложение с requirements.txt
mkdir /tmp/docker-test && cd /tmp/docker-test
echo 'requests==2.32.3' > requirements.txt
cat > app.py <<'EOF'
import signal
from http.server import BaseHTTPRequestHandler, HTTPServer
from types import FrameType


class Hello(BaseHTTPRequestHandler):
    def do_GET(self) -> None:
        """Отвечает на любой GET строкой hello."""
        body = b"hello\n"
        self.send_response(200)
        self.send_header("Content-Type", "text/plain")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)


def stop(signum: int, frame: FrameType | None) -> None:
    """SIGTERM от docker stop: выходим штатно, а не ждём SIGKILL."""
    raise SystemExit(0)


if __name__ == "__main__":
    signal.signal(signal.SIGTERM, stop)
    # 0.0.0.0, а не localhost: иначе снаружи контейнера порт недоступен
    HTTPServer(("0.0.0.0", 8000), Hello).serve_forever()
EOF

# 2. Напиши Dockerfile (правильный порядок)
cat > Dockerfile <<'EOF'
FROM python:3.12-slim
# без буфера stdout: иначе логи в docker logs идут с задержкой
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "app.py"]
EOF

# 3. Собери дважды - второй раз мгновенно (кэш)
docker build -t test1 .
docker build -t test1 .   # шаги помечены CACHED

# 4. Измени app.py и собери - pip install закэширован
echo '# changed' >> app.py
docker build -t test1 .   # pip install из кэша!

Обработчик SIGTERM в app.py не для красоты: процесс с PID 1 без своего обработчика сигнал игнорирует, и docker stop ждёт 10 секунд до SIGKILL. Проверь: docker run -d --name t1 -p 8000:8000 test1, curl localhost:8000, затем time docker stop t1 - остановка мгновенная.

Поэкспериментируй: поставь COPY . . перед RUN pip install и сравни время сборки.

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.