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