Шпаргалка Docker Compose для работы на сервере

Команды Compose, которые действительно нужны

Docker Compose включает более сорока подкоманд. В повседневной работе на сервере используется около дюжины. На этой странице они сгруппированы по выполняемым задачам, для каждой приведена одна простая причина использования, а также указаны ссылки на подробные руководства, если команда содержит скрытые нюансы.

Все описанное здесь относится к Compose V2: docker compose через пробел, а не к старому скрипту docker-compose. V2 — это плагин на языке Go, который устанавливается вместе с Docker Engine, а V1 больше не входит в актуальные пакеты, поэтому docker-compose: command not found на свежей системе Ubuntu по состоянию на июль 2026 года — это ожидаемое поведение, а не ошибка. Проверьте версию с помощью docker compose version. Если команда ничего не выводит, установите пакет docker-compose-plugin.

Каждая приведенная ниже команда выполняется из каталога, в котором находится ваш compose.yaml, так как Compose берет имя проекта из этого каталога и ищет файл относительно него. Запустите ту же команду на уровень выше, и Compose завершит работу с ошибкой no configuration file provided: not found. Если формат файла для вас в новинку, начните с первого файла Compose на VPS и вернитесь сюда за командами.

Жизненный цикл: четыре команды для запуска и одна для удаления контейнеров

docker compose up -d
docker compose up -d --wait
docker compose stop
docker compose start
docker compose restart web
docker compose down

up -d создает сеть, создает контейнеры, запускает их и завершает работу. Команда возвращает управление сразу после создания контейнеров, поэтому скрипт развертывания, который сразу после этого выполняет проверку curl, часто завершается ошибкой при первой попытке. up -d --wait блокирует выполнение до тех пор, пока каждая служба, для которой определена проверка работоспособности, не сообщит о своем нормальном состоянии; если этого не происходит, команда завершается с ненулевым кодом. Эффективность этого флага зависит от качества самой проверки, поэтому перед использованием в автоматизации настройте проверку работоспособности, которой может доверять Compose.

stop останавливает контейнеры, но сохраняет их, поэтому start позволяет вернуть те же самые контейнеры с тем же записываемым слоем. down останавливает, а затем удаляет контейнеры и сеть проекта. Все данные, записанные внутри контейнера вне томов, будут удалены вместе с ним. Это самое распространенное и дорогостоящее заблуждение при работе с Compose, и в статье полная разница между down и stop подробно описано, в каких случаях это приводит к проблемам.

restart — это не перезагрузка. Команда останавливает и запускает тот же самый контейнер с уже имеющейся конфигурацией, поэтому изменение переменной окружения, новый тег образа или отредактированное сопоставление портов не дадут никакого эффекта. Чтобы применить изменения в файле, запустите up -d еще раз. Compose сравнивает каждую службу с запущенным контейнером и пересоздает только те, конфигурация которых изменилась.

Применение изменений: recreate, pull или rebuild

docker compose up -d --force-recreate
docker compose pull && docker compose up -d
docker compose build --no-cache web
docker compose up -d --build web

Команда up -d сама по себе ничего не делает, если изменений нет, поэтому ее безопасно запускать многократно. Флаг --force-recreate отменяет это сравнение и заменяет каждый контейнер, даже если конфигурация идентична, поэтому это самый быстрый способ очистить некорректное состояние внутри контейнера.

Обновление образа требует двух команд, так как они выполняют разные действия. pull загружает актуальный образ для каждого тега, указанного в файле. Затем up -d обнаруживает, что ID образа сервиса больше не совпадает с запущенным контейнером, и пересоздает его. Если пропустить pull, up -d продолжит работу с latest за прошлый месяц без ошибок.

Команда build применяется к сервисам, в которых объявлена секция build: вместо image:. up -d --build выполняет сборку и запуск за один шаг; это стандартный цикл работы при изменении кода. Используйте --no-cache только тогда, когда кэшированный слой явно устарел, так как эта команда пересобирает каждый слой с нуля.

Просмотр запущенных процессов

docker compose ps
docker compose ps -a
docker compose logs -f --tail=100
docker compose logs --since 15m --timestamps db
docker compose top
docker compose ls

ps выводит список только запущенных контейнеров. Служба, которая завершилась аварийно во время запуска, не будет видна в этом списке, пока вы не добавите -a. Поэтому отсутствие контейнера в выводе ps при том, что ps -a показывает его статус как Exited (1), является стандартным признаком ошибки при запуске. Проверьте код завершения, а затем изучите логи.

logs -f выводит логи всех служб одновременно, добавляя префикс с именем службы к каждой строке. Это представление необходимо, когда службы взаимодействуют друг с другом и важна последовательность событий. Укажите имя службы, чтобы сузить область поиска. Флаг --tail=100 важен для контейнера, который работает уже месяц, так как по умолчанию выводится вся история, что переполняет терминал. --since 15m отвечает на типичный вопрос о том, что произошло во время только что выполненного перезапуска.

top выводит список процессов внутри каждого контейнера. Это позволяет разграничить состояния «контейнер запущен» и «процесс внутри него запущен». ls позволяет выйти за пределы текущего каталога и вывести список всех проектов Compose на хосте с их статусами, что помогает найти стек, запущенный несколько месяцев назад.

Получение доступа к оболочке внутри службы

docker compose exec web sh
docker compose exec -u root web sh
docker compose run --rm web env
docker compose run --rm --no-deps web sh

exec выполняет команду внутри уже запущенного контейнера. run запускает новый контейнер на основе того же определения службы; это необходимо, если служба завершает работу слишком быстро для использования exec. Всегда используйте run вместе с --rm, так как без этого каждый вызов оставляет после себя остановленный контейнер, и их накопление делает вывод docker compose ps -a нечитаемым.

Попробуйте sh перед bash. Образы на базе Alpine не содержат bash, и в случае ошибки вы увидите exec: "bash": executable file not found in $PATH. Добавление --no-deps к run позволяет пропустить зависимости службы, что предотвращает запуск всей базы данных при простой проверке конфигурации.

run --rm web env — это самый быстрый способ увидеть среду, которую служба получила в действительности после объединения всех файлов .env, блоков environment: и переменных оболочки. Если значение неверно, причиной обычно является порядок объединения, а в том, как Compose разрешает файлы окружения и секреты описано, какой источник имеет приоритет.

Сети, порты и разрешение имен

docker compose port web 80
docker compose exec web getent hosts db
docker compose config --networks

Compose помещает каждый сервис в одну проектную сеть, где имя каждого сервиса является DNS-именем. Запуск getent hosts db внутри web выводит IP-адрес контейнера, если разрешение имен работает, и не выводит ничего, если оно не работает. Это позволяет за две секунды ответить на вопрос, «видят ли контейнеры друг друга». Если имя разрешается, но в соединении отказано, значит процесс внутри db привязан к 127.0.0.1, а не к 0.0.0.0, поэтому он не принимает пакеты от других контейнеров. Подробности этой модели описаны в как работают сети и DNS сервисов в Compose.

port web 80 выводит адрес хоста и порт, на котором опубликован порт контейнера. Это избавляет от необходимости угадывать, если отображение было задано через переменную. Публикация порта также создает правило брандмауэра, которым Docker управляет самостоятельно. Это правило располагается перед вашими собственными правилами, поэтому сервис, который вы считали закрытым, может оказаться доступным из интернета. Этот случай описан в почему опубликованные порты Docker обходят ufw.

Тома и данные

docker compose config --volumes
docker compose cp db:/etc/postgresql/pg_hba.conf ./pg_hba.conf
docker compose down -v

config --volumes выводит список именованных томов, объявленных в проекте, по одному на строку. Этот список необходимо использовать для резервного копирования. cp копирует файл в контейнер или из него без открытия оболочки, используя формат service:path для той стороны, которая является контейнером.

down -v удаляет эти именованные тома вместе с контейнерами. Это подходящая команда для развертывания тестового стека, но она не подходит для любых данных, которые вам важны, так как запрос подтверждения отсутствует, а отмена действия невозможна. Привязанные монтирования (bind mounts) сохраняются после этой команды, так как они находятся в файловой системе хоста. Эта разница в зоне поражения — одна из причин осознанно выбирать между привязанными монтированиями и именованными томами.

Очистка дискового пространства без потери данных

docker compose down --remove-orphans
docker system df
docker image prune -a
docker builder prune

--remove-orphans удаляет контейнеры, которые относятся к проекту, но больше не указаны в файле конфигурации; именно это происходит после переименования службы. Без этой команды такие контейнеры продолжают работать, оставаясь невидимыми для docker compose ps.

docker system df показывает, куда расходуется дисковое пространство, прежде чем вы что-либо удалите, разделяя образы, контейнеры, локальные тома и кэш сборки с указанием объема, который можно освободить для каждого из них. image prune -a удаляет все образы, на которые не указывает ни один тег; на сервере, где было загружено несколько версий большого образа, это обычно дает наибольший выигрыш. builder prune очищает кэш сборки, который незаметно растет на любом сервере, где выполняется сборка собственных образов.

Ни одна из этих команд не затрагивает именованные тома. Это делают только docker volume prune и docker compose down -v.

Проверка файла перед внесением изменений

docker compose config --quiet
docker compose config --services
docker compose --dry-run up -d

config --quiet выполняет проверку и не выводит ничего при успешном завершении, поэтому эту команду следует использовать на этапе перед развертыванием или в git hook. Обычная команда config выводит полностью объединенный и интерполированный файл; это позволяет убедиться, что переменная была разрешена, а файл переопределения применился ожидаемым образом. Неустановленная переменная отображается там как пустое значение рядом с предупреждением The "X" variable is not set. Defaulting to a blank string..

--dry-run — это глобальный флаг, а не флаг подкоманды, поэтому он указывается перед up. Он выводит все действия, которые выполнит Compose, не внося при этом никаких изменений. Это тридцать секунд, которые стоит потратить перед выполнением down для важного стека.

Работа с файлами, профилями и проектами

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose --profile debug up -d
docker compose -p staging up -d

Несколько флагов -f объединяются в порядке их следования, при этом последующие файлы переопределяют предыдущие по каждому ключу. Это стандартный способ использования базового файла с небольшим переопределением для production-среды. Однако правила для списков и карт различаются, поэтому ознакомьтесь с тем, как Compose объединяет несколько файлов, прежде чем приступать к отладке неожиданных результатов.

--profile запускает службы, помеченные этим профилем, наряду с теми, у которых меток нет. Это позволяет исключить инструменты отладки из стандартного up. -p задает имя проекта, благодаря чему две копии одного стека могут работать параллельно, используя отдельные сети и тома. Восстановление стека после перезагрузки не требует ввода команд вручную; это выполняется системным модулем, описание которого приведено в запуске стеков Compose при загрузке.

FAQ

Чем заменили docker-compose с дефисом?

Compose V2, который вызывается как docker compose через пробел. Это плагин, поставляемый в составе Docker Engine, а инструмент V1 на языке Python больше не устанавливается современными пакетами. Если команда с пробелом не выводит результат, установите пакет docker-compose-plugin для вашего дистрибутива. Обновите старые скрипты, используя вариант с пробелом, вместо создания псевдонима, так как в V2 есть флаги, которых не было в V1.

Почему docker compose restart не применяет изменения в конфигурации?

Команда restart останавливает и запускает существующий контейнер с той конфигурацией, с которой он был создан, и никогда не перечитывает compose.yaml. Любое изменение переменных окружения, портов, томов или тега образа требует выполнения docker compose up -d, которая сравнивает каждый сервис с его запущенным контейнером и пересоздает те, что отличаются. Добавьте --force-recreate, если хотите принудительно выполнить замену, даже если содержимое файла не изменилось.

Как обновить сервис до более новой версии образа?

Выполните docker compose pull, а затем docker compose up -d. Команда pull загружает актуальный образ для каждого тега, указанного в файле, а up -d пересоздает любой сервис, ID образа которого больше не совпадает с ID в контейнере. Запуск up -d без предварительной загрузки использует образ, который уже находится на диске; именно поэтому стек, закрепленный за latest, может месяцами работать на старой сборке без вывода ошибок.

Какие команды очистки безопасны на рабочем сервере?

docker system df, docker image prune -a и docker builder prune удаляют только образы и кэш, поэтому запущенные сервисы продолжают работать, а именованные тома остаются нетронутыми. Опасная пара — это docker compose down -v и docker volume prune, которые удаляют именованные тома без запроса подтверждения. Сначала выполните docker compose config --volumes, чтобы оценить возможные риски.

Можно ли запустить одну команду, не запуская весь стек целиком?

Да. docker compose run --rm --no-deps web sh запускает отдельный контейнер на основе определения сервиса web, игнорирует его зависимости и удаляет контейнер после завершения работы. Используйте exec, если контейнер уже запущен, так как exec подключается к работающему процессу и показывает реальное состояние сервиса.