Docker Compose: шпаргалка команд для сервера

Команди Compose, які ви справді використовуєте

Docker Compose має понад сорок підкоманд. У щоденній роботі на сервері використовують приблизно дюжину. На цій сторінці вони згруповані за завданнями. Для кожної наведено коротке пояснення. Також указано посилання на докладний матеріал, якщо команда має неочевидні особливості.

Усе нижче стосується Compose V2: docker compose із пробілом, а не старого скрипту docker-compose. V2 — це плагін Go, який установлюється разом із Docker Engine. V1 вилучено з поточних пакетів, тому повідомлення docker-compose: command not found на щойно встановленій системі Ubuntu станом на July 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 очікує, доки кожна служба з оголошеною перевіркою стану не повідомить про стан healthy, і завершується з ненульовим кодом, якщо цього не відбувається. Ефективність цього прапорця залежить від перевірки, яку він використовує, тому спочатку створіть перевірку стану, якій Compose може довіряти, а вже потім використовуйте її в автоматизації.

stop зупиняє контейнери, але зберігає їх. Тому start запускає ті самі контейнери з тим самим доступним для запису шаром. down зупиняє контейнери, а потім видаляє їх і мережу проєкту. Усе, що записано всередині контейнера, але поза межами тому, буде втрачено разом із контейнерами. Це найпоширеніше й найдорожче непорозуміння щодо Compose. У повному поясненні різниці між down і stop описано, де саме воно виникає.

restart не перезавантажує конфігурацію. Команда зупиняє та запускає той самий контейнер із наявною конфігурацією. Тому змінна середовища, новий тег образу або змінене зіставлення портів не матимуть жодного ефекту. Щоб застосувати зміни у файлі, знову виконайте up -d. Compose порівнює кожну службу з її запущеним контейнером і повторно створює лише ті контейнери, конфігурація яких змінилася.

Застосування зміни: повторне створення, завантаження або повторна збірка

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 виявляє, що ідентифікатор образу служби більше не відповідає її запущеному контейнеру, і повторно створює його. Якщо пропустити завантаження, 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 на хості разом із їхнім станом. Так можна знайти стек, який ви запустили три місяці тому.

Отримання shell-доступу всередині сервісу

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: і змінних shell. Якщо значення неправильне, зазвичай причина полягає в порядку об’єднання. У матеріалі як Compose визначає пріоритет env-файлів і секретів пояснено, яке джерело має перевагу.

Мережі, порти та розпізнавання імен

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. Тому він не приймає пакети від іншого контейнера. Докладніше цю модель описано в матеріалі як працюють мережі Compose і DNS служб.

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 видаляє ці іменовані томи разом із контейнерами. Це правильна команда для видалення тестового стека та неправильна — для об’єктів, що містять потрібні вам дані, оскільки команда не запитує підтвердження і скасувати її неможливо. Прив’язані монтування зберігаються, оскільки вони розташовані у файловій системі хоста. Ця відмінність у масштабі наслідків є однією з причин свідомо обирати між прив’язаними монтуваннями та іменованими томами.

Очищення, яке звільняє місце на диску без втрати даних

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 повторно створює кожен сервіс, ідентифікатор образу якого більше не відповідає його контейнеру. Самостійний запуск 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 підключається до активного процесу й показує фактичний стан сервісу.