Python Docker Entrypoint Writing

Запуск Python-сервиса через Docker ENTRYPOINT

Связать один образ сервиса с явными Python entrypoint-модулями процессов, не перенося их lifecycle и прикладную подготовку в shell или Dockerfile.

Порядок работы

1. Изучить Dockerfile, .dockerignore, dependency manifest и lock-файл, структуру пакетов, существующие команды разработки, CI и deployment-файлы.
2. Найти все запускаемые процессы и их Python entrypoint-модули: API, consumer, publisher, scheduler, миграции, healthcheck и другие фактически заданные процессы.
3. Определить реально доступные в образе способы запуска Python-модуля исходя из базового образа, менеджера окружения, способа установки зависимостей и проекта.
4. До изменения Dockerfile предложить пользователю применимые варианты запуска, кратко объяснить их последствия и получить выбор. Не ограничивать варианты заранее заданным перечнем. Например, репозиторий может допускать прямой вызов интерпретатора окружения, uv run, другой environment runner или установленный console script.
5. После выбора согласовать стабильную часть ENTRYPOINT, процесс по умолчанию в CMD и команды запуска остальных процессов.
6. Реализовать образ и обновить связанные deployment/CI-примеры только в согласованном объёме.
7. Собрать образ и проверить default-процесс, переопределение процесса, передачу аргументов, код завершения и доставку сигнала остановки.

Контракт процессов

• Использовать отдельный импортируемый Python-модуль entrypoints.<process> для каждого независимо запускаемого процесса.
• Оставлять в модуле минимальную композицию: загрузка конфигурации, startup preflight/bootstrap, сборка профильного worker-а и запуск.
• Завершать CLI/background/healthcheck через raise SystemExit(main()), если main возвращает код. API entrypoint может возвращать None, если сервер сам владеет процессом.
• Не выбирать процесс через неявную переменную окружения, когда его можно явно передать аргументом контейнера.
• Не помещать миграции, readiness-логику и бизнес-операции в shell entrypoint. Вызывать их из Python bootstrap согласно профильным скилам.

Внутреннее устройство процессов определяют $python-fastapi-api-worker, $python-background-worker-runtime-writing и специализированные worker-скилы.

ENTRYPOINT и CMD

• Делать ENTRYPOINT общей стабильной командой запуска Python-модуля, выбранной после анализа репозитория и согласования с пользователем.
• Делать CMD изменяемой частью: модулем процесса по умолчанию и, при необходимости, его аргументами.
• Использовать exec-form JSON для ENTRYPOINT и CMD, чтобы не добавлять shell между container runtime и процессом без необходимости.
• Проверять, как выбранный runner создаёт дочерний процесс, передаёт SIGTERM и возвращает exit code. Не считать это корректным только по синтаксису команды.
• Не фиксировать абсолютный путь к Python, расположение virtualenv или конкретный runner до исследования репозитория и выбора пользователя.
• Добавлять shell-обёртку только для нескольких действительно обязательных операций, которые нельзя выразить Python bootstrap. В ней использовать exec для финального процесса и не реализовывать диспетчеризацию через хрупкий набор строковых условий.

Сборка образа

• Использовать lock-файл и воспроизводимую установку зависимостей.
• Разделять копирование dependency metadata и исходного кода для кеширования.
• Не устанавливать dev/test/lint-зависимости в production stage.
• Запускать процесс от непривилегированного пользователя; заранее создавать и назначать ему каталоги, требуемые для runtime-файлов.
• Не встраивать конфигурацию, секреты и environment-specific файлы в образ.
• Использовать multi-stage build только когда он уменьшает runtime-образ или исключает build-инструменты; не добавлять его механически.
• Не полагаться на EXPOSE как на публикацию порта или контракт процесса.

Несколько процессов из одного образа

• Собирать один образ, если процессы используют один код и совместимый набор runtime-зависимостей.
• Показывать точные команды переопределения CMD для каждого найденного процесса.
• Не запускать несколько долгоживущих процессов внутри одного контейнера без отдельного требования; один контейнер должен владеть одним главным процессом.
• Если процессы требуют несовместимых зависимостей или системных библиотек, предложить отдельные target stages или образы и согласовать это отдельно.

Healthcheck

• Определять liveness/readiness командой конкретного процесса и его профильным контрактом наблюдаемости.
• Для общего многопроцессного образа не задавать в Dockerfile один HEALTHCHECK, который корректен только для процесса по умолчанию. Настраивать probe в deployment/container definition либо использовать согласованный универсальный healthcheck entrypoint с явным именем процесса и типом проверки.
• Не поднимать HTTP-сервер в background worker-е только ради healthcheck, если профильный runtime использует файловый или другой согласованный механизм.

Проверка результата

• Все заданные процессы запускаются из одного образа явными командами.
• Выбранный способ запуска следует устройству репозитория и подтверждён пользователем.
• ENTRYPOINT стабилен, CMD переопределяет процесс без shell-магии.
• Главный процесс получает сигналы и возвращает исходный exit code.
• Контейнер работает без root и не содержит dev-зависимостей или секретов.
• Для каждого процесса определена подходящая команда healthcheck либо явно указано, что probe задаётся внешним оркестратором.
• Сборка и smoke-проверки контейнера проходят.