Разница между command и entrypoint в Docker Compose
Узнайте, как правильно использовать command и entrypoint в docker-compose.yml. Разбираем четыре комбинации переопределения и почему установка entrypoint очищает CMD.
Разница между command и entrypoint в Docker Compose: единое правило
В Docker Compose entrypoint: задает программу, которая будет запущена, а command: определяет аргументы, передаваемые этой программе. Процесс контейнера формируется путем добавления списка command к списку entrypoint. Все остальные особенности поведения, описанные на этой странице, вытекают из этого утверждения.
Эти два ключа соответствуют двум инструкциям Dockerfile. entrypoint: заменяет ENTRYPOINT образа. command: заменяет CMD образа. Они не являются независимыми, и именно здесь часто возникают сложности: установка entrypoint: также отменяет CMD образа. Спецификация Compose прямо указывает на это. Если entrypoint не является пустым, Compose игнорирует любую команду по умолчанию, заданную в образе.
Изучение параметров образа
Прежде чем переопределять настройки, изучите, что именно поставляется в составе образа.
docker image inspect --format '{{json .Config.Entrypoint}}' postgres:16
docker image inspect --format '{{json .Config.Cmd}}' postgres:16Вы получаете ["docker-entrypoint.sh"] и ["postgres"], поэтому контейнер запускает docker-entrypoint.sh postgres. Этот скрипт при первом запуске создает каталог данных, считывает переменные POSTGRES_*, понижает привилегии до пользователя postgres и в конечном итоге выполняет переданные ему аргументы. Ключевой момент — понять, какую именно часть процесса вы хотите изменить. Чтобы передать флаг базе данных, замените command:. Если вы замените entrypoint:, то вся процедура инициализации не будет выполнена вовсе.
Четыре комбинации, показанные на миниатюрном изображении
Создайте образ, единственная задача которого — вывести список аргументов, с которыми он был запущен.
FROM alpine:3.20
ENTRYPOINT ["/bin/echo", "ep"]
CMD ["cmd"]docker build -t argdemo .services:
demo:
image: argdemoЗапускайте docker compose up после каждого изменения и читайте единственную строку, которую он записывает в лог.
- Ни один ключ не задан. Процесс —
/bin/echo ep cmd, а в логе отображаетсяep cmd. - Только
command: ["cmd2"]. Процесс —/bin/echo ep cmd2. Точка входа (entrypoint) остается нетронутой, изменяются только аргументы. - Только
entrypoint: ["/bin/echo", "ep2"]. Процесс —/bin/echo ep2, а в логе отображаетсяep2.cmdиз образа исчезает, и система не выдает никаких предупреждений. - Оба ключа заданы. Процесс —
/bin/echo ep2 cmd2. Это единственный случай, когда вы полностью контролируете список аргументов.
Почему установка entrypoint очищает CMD образа
CMD образа записывается как список аргументов по умолчанию для ENTRYPOINT этого образа. Если вы заменяете entrypoint, эти аргументы начинают относиться к программе, которая больше не запущена, поэтому Compose отбрасывает их вместо того, чтобы формировать командную строку, которую автор образа не планировал. docker run --entrypoint ведет себя так же, поэтому это поведение Docker, а не особенность Compose.
Последствия этого вполне конкретны. nginx:1.27 объявляет ENTRYPOINT ["/docker-entrypoint.sh"] и CMD ["nginx", "-g", "daemon off;"]. Установите entrypoint: /custom-init.sh, и ваш скрипт запустится с пустым списком аргументов. Скрипт, который заканчивается стандартным exec "$@", в таком случае не имеет ничего для выполнения, поэтому exec ничего не делает, скрипт доходит до последней строки, и контейнер завершает работу с кодом 0 без каких-либо сообщений об ошибках. Добавьте аргументы обратно самостоятельно:
services:
web:
image: nginx:1.27
entrypoint: /custom-init.sh
command: ["nginx", "-g", "daemon off;"]Правило, которое нужно запомнить: всякий раз, когда вы устанавливаете entrypoint:, сразу решайте, каким должен быть command:.
Exec-форма и shell-форма: различия в Docker и Compose
Dockerfile поддерживает два синтаксиса. CMD ["nginx", "-g", "daemon off;"] — это exec-форма: бинарный файл запускается напрямую, без участия оболочки. CMD nginx -g "daemon off;" — это shell-форма: Docker переписывает её как /bin/sh -c 'nginx -g "daemon off;"', поэтому сначала запускается оболочка, а ваша программа становится её дочерним процессом.
Compose не копирует это правило, что часто становится неожиданностью. Строка в command: разбивается на аргументы и выполняется напрямую, без обертки /bin/sh -c. Справочная документация Compose прямо указывает на это: поле command не выполняется в контексте SHELL, заданном в образе, поэтому при необходимости использования функций оболочки вы должны вызвать её самостоятельно.
Именно поэтому command: echo "hello $$HOSTNAME" выводит буквальный текст hello $HOSTNAME. Оболочка не обрабатывала эту строку, поэтому переменные не были раскрыты. Запрашивайте оболочку, если она вам нужна:
services:
demo:
image: alpine:3.20
command: /bin/sh -c 'echo "hello $$HOSTNAME"'Сигналы, PID 1 и корректное завершение docker compose down
docker compose stop и docker compose down отправляют сигнал остановки процессам с PID 1 внутри каждого контейнера. По умолчанию используется сигнал SIGTERM, если в STOPSIGNAL образа или в stop_signal: сервиса не задано иное. После этого Compose ожидает завершения в течение stop_grace_period и отправляет SIGKILL, только если контейнер всё ещё работает. Стандартный период ожидания составляет 10 секунд.
В Linux процесс с PID 1 обладает особыми свойствами. Ядро не применяет стандартные действия для сигналов к PID 1, поэтому процесс без обработчика SIGTERM просто игнорирует SIGTERM, если он запущен как PID 1. Он будет ожидать окончания периода ожидания, после чего будет принудительно завершён, что приведёт к обрыву соединений или потере незафиксированных транзакций.
Использование оболочки (shell) перед запуском программы повышает вероятность такой проблемы, так как оболочка становится PID 1 и большинство оболочек не пересылают сигналы дочерним процессам. Некоторые оболочки заменяют себя финальной командой в строке -c, поэтому иногда программа всё же получает PID 1. Это зависит от типа оболочки и конкретной строки запуска, поэтому не стоит полагаться на догадки. Проверьте это:
docker compose exec -T web cat /proc/1/cmdline | tr '\0' ' '; echoЕсли в качестве PID 1 отображается /bin/sh -c ..., а не ваша программа, есть два способа исправления. Используйте exec-форму в образе или оставьте оболочку и передайте управление процессом с помощью exec:
services:
web:
image: myapp:1.4
command: /bin/sh -c 'exec myapp --config /etc/myapp.toml'exec заменяет процесс оболочки вашей программой вместо создания дочернего процесса, поэтому ваша программа получает PID 1 и принимает сигналы.
Некоторые программы порождают дочерние процессы и не завершают их, что приводит к появлению процессов-зомби, так как PID 1 также отвечает за сбор завершённых процессов (reaping). В Compose для этого есть специальный параметр:
services:
web:
image: myapp:1.4
init: true
stop_grace_period: 30sinit: true запускает небольшой процесс init в качестве PID 1, который пересылает сигналы вашему процессу и собирает дочерние процессы. stop_grace_period даёт больше времени для корректного завершения медленных процессов. Если ваша программа ожидает другой сигнал, stop_signal: SIGQUIT позволяет изменить сигнал, отправляемый Compose. Узнать, какой сигнал запрашивает образ, можно с помощью docker image inspect --format '{{.Config.StopSignal}}' nginx:1.27.
Если стек, где docker compose down всегда тратит десять секунд на каждый сервис, сигнализирует о том, что ничто не обрабатывает SIGTERM, исправьте это, прежде чем винить инструменты. См. разницу между docker compose down и stop, чтобы понять, какие ресурсы удаляет каждая из этих подкоманд.
Такое же различие между exec-формой и оболочкой встречается ещё в одном месте. Healthcheck, написанный как test: ["CMD", "curl", "-f", "http://localhost/"], запускает бинарный файл напрямую, тогда как test: ["CMD-SHELL", "curl -f http://localhost/ || exit 1"] запускается через оболочку, чтобы || имел смысл. В написании healthcheck для Compose, которые завершаются корректно подробно описаны остальные аспекты этой темы.
Добавление флага к официальному образу
Это именно то, зачем пришло большинство читателей. Вам нужен один дополнительный флаг для postgres, и при этом нельзя нарушить работу скрипта инициализации.
services:
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- pgdata:/var/lib/postgresql/data
command: postgres -c max_connections=200 -c shared_buffers=256MB
volumes:
pgdata:Изменился только command:, поэтому docker-entrypoint.sh по-прежнему выполняется и запускает то, что вы ему передали. Проверьте результат, вместо того чтобы полагаться на предположения:
docker compose up -d db
docker compose exec -T db psql -U postgres -c 'show max_connections;'В выводе должно отобразиться 200. Если там по-прежнему 100, выполните docker compose config и убедитесь, что ожидаемый вами command присутствует в объединенной конфигурации. Compose объединяет файлы переопределения, полностью заменяя command, а не добавляя к нему данные, поэтому второй файл, который также задает command:, молча перекроет первый.
Переменная ${POSTGRES_PASSWORD} выше раскрывается Compose на хосте из вашего файла .env до того, как контейнер будет создан. В разделе Файлы окружения и секреты в Compose описано, где безопасно хранить такие значения.
Запуск разовой миграции с помощью docker compose run
docker compose run создает новый контейнер на основе того же определения сервиса и заменяет команду на ту, которую вы вводите после имени сервиса. Entrypoint образа продолжает работать, поэтому контейнер подготавливается точно так же, как и постоянно работающий экземпляр.
docker compose run --rm app python manage.py migrate--rmудаляет контейнер после завершения выполнения команды. Без этого флага каждый запуск оставляет после себя остановленный контейнер, который будет виден вdocker compose ps -a.- Порты не публикуются. Контейнер
runигнорирует настройкиports:сервиса, если вы не добавите--service-ports, поэтому он не может конфликтовать с уже запущенным сервисом. - Зависимости запускаются первыми. Все, что указано в
depends_on, запускается перед вашей командой, а--no-depsпропускает этот этап. - Контейнер получает сгенерированное имя, например
myproject-app-run-9f2c1a, поэтому он никогда не конфликтует с контейнером сервиса.
Чтобы также заменить entrypoint, существует специальный флаг:
docker compose run --rm --entrypoint /bin/sh app -c 'python manage.py migrate'Результирующий список аргументов — /bin/sh -c 'python manage.py migrate', так как слова после имени сервиса по-прежнему считаются командой. docker compose exec — это другой инструмент, который работает иначе: он запускает процесс внутри уже работающего контейнера и полностью игнорирует как entrypoint:, так и command:. Используйте run для задачи, требующей свежего контейнера, и exec для проверки работающего. В шпаргалке по командам Compose остальные подкоманды приведены для сравнения.
Почему мой контейнер немедленно завершает работу?
Начните с кода завершения, так как он быстро сужает круг возможных причин.
docker compose ps -a
docker compose logs appКод завершения 0 и отсутствие вывода. Команда была выполнена и завершена. Самая частая причина — переопределение entrypoint:, которое удалило CMD образа, из-за чего точка входа (entrypoint) запустилась с пустым списком аргументов и ей нечего было передать на исполнение.
Ошибка, заканчивающаяся на permission denied. У скрипта внутри образа нет бита исполнения, обычно потому, что этот бит не был установлен для файла в репозитории. Установите его на этапе сборки с помощью COPY --chmod=0755 entrypoint.sh /entrypoint.sh.
Ошибка, заканчивающаяся на no such file or directory для файла, который вы явно видите в образе. У скрипта окончания строк в формате Windows. Его первая строка читается как #!/bin/sh плюс байт возврата каретки, поэтому ядро ищет интерпретатор с этим байтом в имени и ничего не находит. Выполните dos2unix entrypoint.sh, затем добавьте * text eol=lf в .gitattributes, чтобы проблема не возникла снова.
executable file not found in $PATH. Программа, указанная в command:, отсутствует в любом из каталогов в PATH контейнера. Либо образа её не содержит, либо она установлена где-то вне PATH (укажите полный путь), либо вы написали встроенную команду оболочки, такую как cd, там, где должна быть только реальная программа.
Получение доступа к оболочке образа, у которого завершается entrypoint
Если entrypoint завершается до того, как вы успели что-либо проверить, замените его:
docker compose run --rm --entrypoint /bin/sh appЕсли эта команда завершается с ошибкой stat /bin/sh: no such file or directory, значит, в образе отсутствует /bin/sh. В образах Distroless и на базе scratch оболочка часто вообще отсутствует. Вы всё равно можете прочитать файловую систему снаружи, не запуская entrypoint:
docker create --name probe myapp:1.4
docker export probe | tar -tv | head -40
docker rm probeЕсли вам нужно, чтобы контейнер оставался запущенным для многократного подключения, переведите его на процесс, который никогда не завершается. Добавьте это в файл переопределения, который вы не будете коммитить:
services:
app:
entrypoint: ["tail", "-f", "/dev/null"]
command: []Параметр command: [] не является строго обязательным, так как установка entrypoint: уже очистила CMD образа, но его указание фиксирует намерение для того, кто будет читать файл в будущем. Запустите контейнер и войдите внутрь:
docker compose -f compose.yaml -f compose.debug.yaml up -d app
docker compose exec app /bin/shТеперь запустите реальный entrypoint вручную и наблюдайте, на каком этапе он останавливается. Это позволит увидеть сообщение об ошибке прямо в терминале, а не в контейнере, который завершился полсекунды назад. Если вы только собираете свой первый стек, в разделе первый стек Compose на VPS описана структура файлов, на которую опирается всё вышесказанное.
FAQ
Почему мой контейнер завершается сразу после docker compose up?
Проверьте docker compose ps -a, чтобы узнать код завершения. Код 0 без вывода обычно означает, что вы задали entrypoint: для сервиса, что также очистило CMD образа, поэтому entrypoint выполнился с пустым списком аргументов и завершился. Добавьте аргументы обратно с помощью command:. Ошибка, заканчивающаяся на permission denied, означает, что у скрипта entrypoint отсутствует бит исполнения. Ошибка no such file or directory для существующего файла означает, что в скрипте используются символы переноса строки в формате Windows, из-за чего в строке shebang указан несуществующий интерпретатор.
Удаляет ли установка entrypoint в Compose команду CMD из образа?
Да. Если entrypoint не является пустым, Compose игнорирует любую команду по умолчанию, объявленную в образе. Это задокументированное поведение, соответствующее docker run --entrypoint. Причина в том, что CMD образа записывается как аргументы для ENTRYPOINT этого же образа, поэтому после замены entrypoint старые аргументы теряют смысл. Укажите command: в том же сервисе, если новому entrypoint требуются аргументы.
Выполняется ли строка в команде Compose через оболочку (shell)?
Нет. В отличие от CMD в Dockerfile, строка в command: в Compose разбивается на аргументы и выполняется напрямую, без оболочки /bin/sh -c. Поэтому Compose никогда не запускает shell внутри контейнера для раскрытия $VARIABLE. Вызывайте shell самостоятельно, когда он вам нужен, как в command: /bin/sh -c 'echo "hello $$HOSTNAME"'. Удвоенный знак $$ экранирует знак доллара, чтобы Compose передал его в контейнер, а не раскрывал на хосте.
Почему docker compose down занимает десять секунд для одного контейнера?
Compose отправляет сигнал остановки PID 1 (SIGTERM, если в образе или сервисе не задано иное), ждёт до stop_grace_period (по умолчанию 10 секунд), а затем отправляет SIGKILL, если контейнер всё ещё работает. Ядро не применяет стандартные действия по сигналу к PID 1, поэтому программа без обработчика SIGTERM игнорирует сигнал и всегда ожидает истечения полного периода. Узнайте, что именно является PID 1, с помощью docker compose exec -T app cat /proc/1/cmdline | tr '\0' ' '. Если это shell, переключите образ на exec-форму или напишите exec внутри строки shell. Если процесс порождает дочерние процессы, которые он не завершает, установите init: true для сервиса.