Як відкрити shell у контейнері через Docker Compose
Дізнайтеся, як виконати docker compose exec web bash у запущеному сервісі та коли використати docker compose run для нового контейнера.
Отримайте інтерактивну оболонку за допомогою docker compose exec
docker compose exec web bash відкриває інтерактивну оболонку всередині контейнера, який уже запущений як сервіс web. Ім’я після exec — це ім’я сервісу з вашого compose.yaml, а не ім’я контейнера. Якщо в образі немає bash, замість нього вкажіть sh.
docker compose ps
docker compose exec web bashСпочатку виконайте docker compose ps. Команда має показати web зі станом running. Потім друга команда відкриє запрошення оболонки всередині контейнера, а exit або Ctrl-D поверне вас на хост. Після виходу сервіс продовжує працювати, оскільки exec запускає другий процес поруч з основним. Закриття оболонки не впливає на PID 1 (ідентифікатор процесу 1) — процес, для запуску якого було створено контейнер.
Це один із двох способів підключитися. exec підключається до контейнера, який уже існує. docker compose run створює новий контейнер на основі того самого визначення сервісу. Майже все інше в цьому посібнику випливає з цієї єдиної відмінності.
Чому -it є необов’язковим у Compose, але потрібен у звичайному docker
Два прапорці керують інтерактивною частиною сеансу. -i залишає stdin відкритим, тому введені вами дані надходять до процесу. -t виділяє псевдотермінал, який називається TTY, тому оболонка виводить запрошення та обробляє клавіші зі стрілками. Звичайний docker exec за замовчуванням вимикає обидва параметри, тому в кожному наведеному прикладі вказано docker exec -it. docker compose exec вмикає обидва параметри, тому docker compose exec -it web bash і docker compose exec web bash виконують ту саму дію. Compose також приймає -it, щоб зберегти звичний синтаксис для старих команд.
Відсутність TTY помітна за кілька секунд. Оболонка запускається, але не виводить запрошення, а Ctrl-C не надходить до процесу. Зворотний випадок, коли потрібно попросити Compose не виділяти TTY, має окремий прапорець і власний розділ нижче.
Що робити, якщо в образі немає bash
Якщо в образі на базі Alpine запросити bash, команда exec завершиться помилкою:
OCI runtime exec failed: exec failed: unable to start container process: exec: "bash": executable file not found in $PATH: unknownЦе повідомлення не означає проблему з exec. Воно означає, що в каталогах, перелічених у PATH контейнера, не знайдено bash. Для оболонки це майже завжди означає, що образ її не містить. Alpine постачається з BusyBox, який надає ash як /bin/sh, але не містить bash. Тому запросіть sh:
docker compose exec web shОбрази на базі Debian і Ubuntu, зокрема теги -slim, містять bash. bash також надає історію команд і розширене автодоповнення. Тому спочатку спробуйте bash, а якщо його немає — sh. sh є майже в кожному образі загального призначення.
У деяких образах немає оболонки взагалі. Distroless-образи та образи, зібрані FROM scratch, навмисно містять лише бінарний файл застосунку і його бібліотеки. Відсутню оболонку неможливо використати проти вас. У таких образах sh завершується тим самим повідомленням, і більше пробувати нічого. Є два робочі підходи. Distroless-образи Google публікують теги :debug, які додають оболонку BusyBox. Тимчасово змінивши тег, можна отримати доступ до контейнера. Або запустіть окремий контейнер у просторах імен цільового контейнера:
CID=$(docker compose ps -q web)
docker run --rm -it --network "container:$CID" --pid "container:$CID" nicolaka/netshootТепер інструменти netshoot працюють у мережевому просторі імен застосунку, тому curl localhost:8080 і ss -lntp поводяться так, ніби ви перебуваєте всередині нього. Файлова система, яку ви бачите, належить netshoot, а не застосунку. Оскільки простір імен процесів спільний, /proc/1/root/ вказує на файлову систему процесу цільового контейнера. Однак ls /proc/1/root/ має пройти перевірку дозволів ptrace у ядрі. Запуск обох процесів від імені root недостатній: перевірка також враховує облікові дані, capabilities, атрибут dumpable цільового процесу та модулі безпеки. Значення dumpable, відмінне від 1, блокує доступ, якщо викликач не має CAP_SYS_PTRACE у просторі імен користувачів цільового процесу. Docker не надає SYS_PTRACE за замовчуванням. Додавання --cap-add SYS_PTRACE до рядка docker run усуває перевірки облікових даних і dumpability, але модулі безпеки все одно можуть заборонити доступ.
Коли сервіс не запущений, використовуйте docker compose run --rm
exec потребує запущеного контейнера. Якщо вказати зупинений сервіс, команда завершиться помилкою:
service "web" is not runningВона не запустить нічого автоматично. docker compose run:
docker compose run --rm web bashКоманда run створює новий контейнер на основі опису сервісу web, використовуючи той самий image, оточення, томи та мережі, і замінює команду сервісу на вказану вами. --rm видаляє цей контейнер після виходу. Якщо не вказати --rm, непотрібні контейнери накопичуватимуться під іменами на кшталт myproject-web-run-4f1c2b. Команда docker compose ps -a покаже їх, а docker compose rm видалить їх разом з іншими зупиненими контейнерами сервісу.
Дві особливості run часто дивують користувачів. Команда не публікує порти сервісу, якщо не додати --service-ports або не зіставити порт вручну за допомогою -p. Це зроблено навмисно: другий контейнер не зможе прив’язати порт хоста 8080, доки перший контейнер його використовує, і виникне помилка bind: address already in use. Команда також запускає все, що сервіс перелічує в depends_on, перш ніж ви побачите оболонку. Тому навіть швидка перевірка контейнера може запустити базу даних і кеш. --no-deps вимикає цю поведінку.
run проходить через ENTRYPOINT image, а exec — ні. exec безпосередньо запускає вашу команду в наявному контейнері, тому скрипт entrypoint її не отримує. У разі run ваш bash передається цьому скрипту як аргументи. Багато офіційних image завершують свій entrypoint за допомогою exec "$@", тому команда передається без змін і ви отримуєте оболонку. Скрипт, який сам обробляє аргументи, може виконати з ними іншу дію. У такому разі замініть entrypoint для цього запуску:
docker compose run --rm --entrypoint sh webЦе найпоширеніша причина, через яку команда, що працює з exec, поводиться інакше з run. Розподіл між командою та entrypoint пояснює, яку саме частину конфігурації image ви замінюєте щоразу.
exec або run: як вибрати
- Для
execпотрібен запущений контейнер.runцього не потребує, іrunможе запустити залежності. execбачить поточний список процесів і файли в їхньому фактичному стані, зокрема все, що застосунок записав після запуску.runотримує чистий доступний для запису шар з image, але named volumes і bind mounts усе одно надають доступ до наявних даних сервісу.execпропускає entrypoint.runзапускає його.runзалишає контейнер після завершення, якщо не передати--rm.
Використовуйте exec, щоб перевірити, що відбувається насправді. Використовуйте run --rm для одноразової копії того самого середовища, виконання разової команди міграції або коли реальний сервіс не працює достатньо довго, щоб виконати в ньому exec.
Корисні параметри exec: користувач, робочий каталог і репліки
Більшість образів переходять на непривілейованого користувача, тому встановлення діагностичного інструмента в оболонці exec зупиняється на цьому етапі:
E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)-u root відкриває root-оболонку в тому самому контейнері:
docker compose exec -u root web sh-w /srv/app задає робочий каталог лише для цієї команди. -e KEY=value додає змінну середовища до вашого сеансу, але не до сервісу. Якщо сервіс працює з кількома репліками, --index 2 визначає, до якого контейнера ви підключитеся. Якщо ви з’ясовуєте причину проблеми з власником файлів у змонтованому каталозі, у матеріалі PUID і PGID в образах контейнерів пояснюється, чому саме числові ідентифікатори, а не імена користувачів, визначають, хто може записувати дані в цей каталог.
Отримайте оболонку psql або mysql усередині контейнера бази даних
Клієнт уже міститься в образі бази даних, тому не потрібно встановлювати його на хості та не потрібно публікувати порт:
docker compose exec db psql -U postgres -d app
docker compose exec db mariadb -u root -pОбрази Postgres містять psql, образи MySQL — mysql, а образи MariaDB — mariadb. Підключення встановлюється з контейнера, тому це працює, навіть якщо compose-файл взагалі не публікує порт бази даних. Це безпечніша схема для стандартної bridge-мережі Docker: зовнішні хости не можуть безпосередньо звертатися до непублікованого порту бази даних, хоча хост Docker і контейнери в тій самій мережі все одно мають до нього доступ.
Одна помилка може забрати кілька годин. Оболонка розгортає змінні на хості ще до того, як Docker отримує команду, тому -U "$POSTGRES_USER" передає порожній рядок, якщо ця змінна існує лише всередині контейнера. Одинарні лапки та оболонка всередині контейнера розгортають її в правильному місці:
docker compose exec db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"'Не запускайте docker compose run --rm db без команди в цьому випадку. Це запускає другий сервер Postgres із тим самим томом даних, і він відмовляється запускатися:
FATAL: lock file "postmaster.pid" already existsФайл блокування працює як належить, оскільки два сервери, які записують в один каталог даних, пошкодили б його. Поки база даних працює, виконайте exec у запущеному контейнері. Чи має база даних взагалі працювати в Compose — окреме питання; у матеріалі про запуск бази даних у Docker або на хості наведено відповідні компроміси.
Сервіси, яким потрібна консоль під час запуску: stdin_open і tty
exec і run стосуються оболонок, які ви відкриваєте вручну. Для сервісу, основний процес якого за своєю природою є інтерактивним, у compose-файлі потрібні два ключі:
services:
console:
image: python:3.12-slim
command: python
stdin_open: true
tty: truestdin_open: true — це docker run -i, а tty: true — це docker run -t. Без них контейнер запускається та одразу завершує роботу з кодом 0, а docker compose ps -a показує Exited (0). Збою не сталося. python без термінала в stdin одразу отримує ознаку кінця файлу та штатно завершує роботу. Це правильна поведінка для програми, з якою ніхто не взаємодіє через введення.
Якщо встановлено обидва ключі, під’єднайтеся до запущеного процесу:
docker attach $(docker compose ps -q console)Від’єднайтеся за допомогою Ctrl-P, а потім Ctrl-Q. Процес при цьому продовжить працювати. Ця послідовність працює лише тоді, коли контейнер має TTY і відкритий stdin. Натомість Ctrl-C надсилає сигнал переривання (SIGINT) до PID 1. Це зупиняє сервіс лише якщо програму запрограмовано завершувати роботу після SIGINT, оскільки Linux не застосовує стандартну обробку сигналів до PID 1. Тому не використовуйте Ctrl-C для від’єднання.
Для звичайних сервісів залишайте обидва ключі вимкненими. Вебсервер ніколи не читає stdin, а tty: true змушує багато програм перемикатися на кольоровий вивід і буферизацію рядків, оскільки вони вважають, що за ними спостерігає користувач. Унаслідок цього docker compose logs заповнюється escape-кодами.
Чому виконання скриптів у cron і CI завершується помилкою: прапорець -T
Команда exec, яка працює в терміналі, може завершитися помилкою, коли її запускає скрипт, завдання cron, runner безперервної інтеграції (CI) або конвеєр:
the input device is not a TTYCompose запитує псевдотермінал, коли його власний вивід спрямовано до термінала. Якщо stdin також не є терміналом, цей запит завершується помилкою ще до запуску команди. У сучасному вихідному коді Docker CLI цю саму помилку сформульовано як cannot attach stdin to a TTY-enabled container because stdin is not a terminal. Поточна версія Compose самостійно не надсилає цей запит, коли вивід перенаправлено або передано через pipe, як це зазвичай відбувається в cron. Деякі попередні версії надсилали запит у будь-якому разі, а cat dump.sql | docker compose exec db psql, введений у вашому запрошенні командного рядка, і сьогодні спричиняє цю помилку. -T вимикає запит у всіх випадках, тому додавайте його до скриптів і не покладайтеся на автоматичне визначення:
0 3 * * * docker compose -f /srv/app/compose.yaml exec -T db pg_dump -U postgres -Fc app > /srv/backups/app.dump-T важливий і з іншої причини. TTY змінює потік байтів під час виведення, тому стиснений дамп, який проходить через нього, надходить пошкодженим. Явно передавайте -T для будь-якого перенаправленого виводу або виводу через pipe.
Є ще дві особливості cron. Передавайте -f з абсолютним шляхом, оскільки cron запускає завдання з домашнього каталогу, де немає compose-файлу. Тоді Compose завершує роботу з помилкою no configuration file provided: not found. Крім того, exec повертає код завершення команди, яку він запустив. Тому помилка pg_dump спричиняє помилку скрипту в режимі set -e, а не створення порожньої резервної копії зі звітом про успішне виконання. Решту повсякденних команд зібрано в шпаргалці з команд Compose, яку варто тримати поруч із цими скриптами.
Чому зміни, внесені всередині контейнера, зникають
Ви встановлюєте інструмент за допомогою exec, редагуєте файл конфігурації, усуваєте проблему, а через тиждень виправлення зникає. Це writable layer контейнера, яка працює саме так. docker compose up -d після будь-якої зміни image tag або service definition видаляє старий контейнер і створює новий на основі image, тому всі ручні зміни залишаються у старому контейнері.
docker compose restart працює інакше. Вона зупиняє та запускає той самий контейнер, тому ручні зміни зберігаються. Через це може здаватися, що ручне виправлення працює тижнями, а потім воно зникає під час іншого оновлення. Named volumes і bind mounts переживають обидві операції, оскільки їхні дані зберігаються поза контейнером; у матеріалі bind mounts і named volumes описано, який варіант вибрати для даних, які потрібно зберегти.
Тому сприймайте shell, запущений через exec, як місце для перевірки та тестування. Коли ви визначили потрібне виправлення, запишіть його там, де воно зберігатиметься: пакет — у Dockerfile, параметр — у compose file. Потім docker compose up -d, щоб застосувати зміни, і виконайте ще один exec, щоб переконатися, що новий контейнер справді містить це виправлення.
FAQ
Яка різниця між docker compose exec і docker compose run?
exec виконує команду всередині вже запущеного контейнера, поруч із головним процесом, і пропускає entrypoint образу. run створює новий контейнер із того самого визначення сервісу та з тим самим образом, середовищем, томами й мережами, передає вашу команду через entrypoint і спочатку запускає всі depends_on сервіси. run також не публікує порти сервісу, якщо не додати --service-ports або зіставлення -p. Використовуйте exec, щоб перевірити роботу сервісу. Використовуйте run --rm, якщо сервіс зупинений або потрібен окремий контейнер, але пам’ятайте, що іменовані томи та bind mounts є спільними.
Чому docker compose exec повідомляє, що сервіс не запущений?
exec під’єднується до наявного контейнера й не може створити новий, тому зупинений або аварійно завершений сервіс повертає service "web" is not running. Перевірте docker compose ps -a. Команда показує контейнери, робота яких завершилася, зі статусом на кшталт Exited (1). Причину зупинки можна знайти в docker compose logs web. Щоб у будь-якому разі отримати shell, виконайте docker compose run --rm --entrypoint sh web. Ця команда створює новий контейнер із того самого визначення сервісу, не запускаючи несправну команду старту.
Як відкрити shell, якщо в образі немає bash?
Помилка exec: "bash": executable file not found in $PATH під час виконання docker compose exec web bash означає, що в каталогах зі змінної PATH контейнера не знайдено bash. Майже завжди це означає, що образ не містить bash. Для образів на базі Alpine це нормально. Використовуйте docker compose exec web sh, оскільки BusyBox надає /bin/sh. Якщо в образі немає shell, exec не зможе відкрити shell, але все одно запускатиме виконувані файли, які містить образ. Перейдіть на тег :debug образу, якщо видавець його надає, або запустіть debug-контейнер у просторах імен цільового контейнера за допомогою docker run --rm -it --network "container:$CID" --pid "container:$CID" nicolaka/netshoot, де $CID походить із docker compose ps -q web.
Чому моя команда exec у cron завершується помилкою "the input device is not a TTY"?
docker compose exec запитує псевдотермінал, коли вивід спрямовується до термінала. Запит завершується помилкою, якщо stdin також не є терміналом. Поточна версія Compose самостійно пропускає цей запит, коли вивід перенаправлено, що зазвичай відбувається в cron. Однак деякі попередні версії робили цей запит у будь-якому разі, а передавання даних через pipe до exec з інтерактивного shell усе ще спричиняє цю помилку. Додайте -T, щоб вимкнути цей режим: docker compose exec -T db pg_dump -U postgres app. Для будь-якого перенаправленого або переданого через pipe виводу також використовуйте -T, оскільки TTY змінює потік байтів і пошкоджує двійковий дамп. У cron також передайте -f з абсолютним шляхом до compose-файлу. Інакше Compose завершиться з помилкою no configuration file provided: not found.
Чи зберігаються зміни, внесені всередині контейнера за допомогою exec, після перезапуску?
Вони зберігаються після docker compose restart, оскільки використовується той самий контейнер. Після docker compose up -d вони втрачаються за будь-якої зміни образу або конфігурації, оскільки контейнер створюється заново з образу, а його доступний для запису шар видаляється. Дані, записані в іменовані томи або bind mounts, зберігаються в обох випадках, оскільки вони розташовані за межами контейнера. Діагностичні зміни вносьте за допомогою exec, а остаточну версію додавайте до Dockerfile або compose-файлу.