# Python Docker Entrypoint Writing > Используй при создании, изменении и ревью Dockerfile, Docker ENTRYPOINT/CMD и контейнерного запуска Python-сервиса с одним или несколькими процессами. Скил унифицирует выбор Python entrypoint-модулей, способ запуска из установленного окружения, передачу аргументов, сигналов и кодов завершения, непривилегированного пользователя, сборку зависимостей и process-specific healthcheck. Не применять для внутреннего устройства FastAPI, фонового runtime, consumer/publisher или application-логики. - Skill: `nemagu/python-docker-entrypoint-writing` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add nemagu/python-docker-entrypoint-writing` - Raw SKILL.md: https://api.skillmd.com/api/skills/nemagu/python-docker-entrypoint-writing/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: Nemagu (https://skillmd.com/u/nemagu) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/nemagu/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.` для каждого независимо запускаемого процесса. - Оставлять в модуле минимальную композицию: загрузка конфигурации, 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-проверки контейнера проходят.