Compose v2 на Ubuntu и Debian ставится пакетом docker-compose-plugin из официального репозитория Docker и вызывается подкомандой docker compose, с пробелом. Standalone-бинарник docker-compose, с дефисом, приходит из другого источника: его либо скачивают вручную с GitHub, либо ставят пакетом из репозитория дистрибутива. Два механизма на одной машине дают разный результат на одинаковых compose-файлах, и это самая частая причина путаницы.
Проверка рабочего окружения укладывается в три шага. docker compose version показывает ветку v2. docker compose config в каталоге с compose-файлом разбирает конфигурацию и выводит ошибки синтаксиса. docker ps без sudo подтверждает, что у пользователя есть доступ к демону.
Дальше разбираем, почему плагин предпочтительнее, как подключить репозиторий и поставить пакет, что учесть на Astra Linux, как вычистить старый бинарник и по каким симптомам искать причину сбоя.
Зачем ставить Compose v2 плагином, а не standalone-бинарником
Плагин расширяет Docker CLI: исполняемый файл лежит в каталоге cli-plugins, CLI находит его по стандартным путям и подключает как подкоманду. У вас одна точка входа, docker, и не нужно держать в голове, какой именно compose установлен и откуда он взялся.
Чем docker compose отличается от docker-compose
Разница в имени команды отражает разницу в архитектуре. docker compose запускает плагин, который поставляется вместе с экосистемой Docker. docker-compose запускает отдельный исполняемый файл, найденный в PATH, и этот файл может быть версией v1 либо вручную установленной v2.
| Признак | docker compose (плагин) | docker-compose (standalone) |
|---|---|---|
| Что это | подкоманда Docker CLI | отдельный исполняемый файл |
| Откуда берется | пакет docker-compose-plugin из репозитория Docker | ручное скачивание или пакет docker-compose из дистрибутива |
| Обновление | вместе с пакетами Docker через apt | замена бинарника вручную |
| Типичная версия | v2 | v1 либо скачанная v2 |
| Чем проверять | docker compose version | which -a docker-compose, docker-compose version |
Проверяйте фактическое состояние машины, а не ожидания. Три команды дают полную картину: which -a docker-compose покажет все найденные бинарники, docker-compose version объяснит, что запускается по старому имени, docker compose version подтвердит, виден ли плагин.
Практическое следствие: одинаковый compose-файл ведет себя по-разному. Верхнеуровневый ключ version в Compose-файле объявлен устаревшим: он носит информативный характер, при его использовании выводится предупреждение, а Compose всегда применяет самую свежую схему для валидации файла независимо от поля version. Если файл написан с полями более новой версии спецификации, Compose предупредит о неизвестных полях. Старый бинарник на том же файле может вести себя иначе, и отладка уходит в сторону от реальной проблемы.
Почему плагин удобнее в поддержке
- Обновление идет вместе с Docker через apt, отдельный бинарник помнить не нужно.
- Нет ручного скачивания с GitHub, а значит, нет риска взять файл не той архитектуры или из непроверенного зеркала.
- Путь установки одинаков на всех машинах, поэтому поведение в CI и на ноутбуке разработчика совпадает.
- Версия пакета видна в apt и dpkg, что упрощает аудит и фиксацию состояния.
Границы применимости: если политика безопасности запрещает сторонние репозитории, способ установки согласуют с ответственными за инфраструктуру. В закрытом контуре допустим перенос пакетов из доверенного внутреннего зеркала, тогда версию и источник фиксируют отдельно.
Подготовка системы и подключение официального репозитория Docker
Пакет docker-compose-plugin распространяется в официальном репозитории Docker, в репозиториях дистрибутивов он обычно отстает по версии или отсутствует. Маршрут для Ubuntu и Debian одинаков: поставить зависимости, добавить ключ, добавить строку репозитория, обновить индексы.
Обновите индексы командой sudo apt update, затем поставьте пакеты для работы apt по HTTPS: sudo apt install ca-certificates curl gnupg. Каталог для ключей создайте заранее: sudo install -m 0755 -d /etc/apt/keyrings. Ключ и строку репозитория берите из актуальной инструкции Docker для вашей версии дистрибутива: адреса, имена файлов и формат ключа меняются между релизами и между ветками Debian.
Если Docker Engine на машине еще не установлен, начните с полного руководства по установке Docker и вернитесь к этому шагу: пакет плагина ставится поверх работающего Engine. Источники не смешивайте: docker.io из репозитория дистрибутива и docker-ce из репозитория Docker конфликтуют по файлам на одной машине.
Зависимости и ключ репозитория
Для apt по HTTPS обычно хватает трех пакетов: ca-certificates, curl, gnupg. Первый нужен для проверки TLS-сертификатов, второй для скачивания ключа, третий для работы с подписями.
Если apt ругается на подпись или пишет, что ключ отсутствует, проверьте два момента: ключ скачан с официального адреса из инструкции Docker и параметр signed-by в строке sources.list указывает на тот же файл. После правки ключа или строки выполните sudo apt update и прочитайте вывод целиком: ошибки подключения видны именно там, а не в момент установки пакета.
Проверка доступной версии пакета
Команда apt-cache policy docker-compose-plugin показывает установленную версию, кандидата на установку и репозиторий, из которого кандидат пришел. Если в ответе сообщение о том, что пакет не найден, смотрите причину: не выполнен apt update, репозиторий не подключен или его ветка не совпадает с версией дистрибутива.
Полезная добавка: apt-cache madison docker-compose-plugin перечисляет версии, доступные в подключенных репозиториях. Так видно, приходит свежая ветка v2 или пакет тянется из старого зеркала.
Установка docker-compose-plugin на Ubuntu и Debian
Основная команда из официальной инструкции Docker для Ubuntu и Debian: sudo apt-get install docker-compose-plugin. Пакет небольшой, ставится за секунды, compose-файлы и существующие контейнеры не затрагивает.
Сразу после установки проверьте вывод docker compose version: он должен содержать ветку v2. Если команда не найдена, смотрите раздел о типичных ошибках: чаще всего Docker CLI не установлен или плагин лег в каталог, который CLI не просматривает.
Что делает пакет docker-compose-plugin
Пакет кладет исполняемый файл плагина в каталог cli-plugins. Точный путь зависит от сборки и версии пакета, поэтому проверяйте фактическое расположение через ls по каталогу и настройки CLI. Docker CLI ищет плагины в стандартных каталогах и в каталоге из переменных окружения, поэтому после установки пакета команда docker compose появляется без ручной настройки.
docker info подтверждает, что демон отвечает и CLI с ним связывается, но наличие compose не показывает: для проверки самого плагина используйте docker compose version. Эта команда не обращается к демону и подходит как первая проверка после установки, до разбора прав доступа.
Установка на Astra Linux: особенности репозиториев
Astra Linux основана на Debian, поэтому apt и общая последовательность действий применимы. Сведения о том, на каких выпусках Debian основан конкретный релиз Astra, приведены в базе знаний Astra Linux о выпусках Debian — в таблицах вариантов исполнения Astra Linux Special Edition и Astra Linux Common Edition. Отличия в другом: состав и приоритеты репозиториев и требования по информационной безопасности, которые ограничивают подключение внешних источников.
Первый шаг здесь не установка, а инвентаризация. Выполните apt-cache policy docker.io docker-compose-plugin и apt search compose. Вывод покажет, что реально доступно в подключенных репозиториях. Второй шаг: сверьте версию базовой ветки Debian через /etc/os-release и /etc/debian_version, чтобы понять, какая инструкция Docker применима к вашей системе.
Проверка доступных пакетов в Astra Linux
Читайте вывод apt-cache policy построчно: Installed показывает, что стоит сейчас, Candidate - что будет поставлено, строка с адресом репозитория говорит, откуда придет пакет. Пустой ответ или отсутствие кандидата означают, что пакета в подключенных репозиториях нет. Старая версия кандидата означает, что пакет есть, но ветка v2 в нем может быть неактуальной.
Дополнительно проверьте, не подмешан ли сторонний источник: apt-cache policy покажет все репозитории, где встречается имя пакета, и приоритеты между ними. Это объясняет, почему установка берет версию не из того места, которое вы ожидали.
Когда нужен официальный репозиторий Docker
Подключать внешний репозиторий имеет смысл при совпадении трех условий: нужна актуальная ветка v2, в репозиториях Astra подходящего пакета нет или он устарел, политика безопасности допускает внешний источник. Совместимость конкретного релиза Astra с веткой Debian и требования ИБ согласуйте с ответственными за инфраструктуру: это зона, где самостоятельная проверка ограничена, а решение принимается по внутренним регламентам.
Учтите структуру репозиториев Astra Linux Special Edition: основной (main) проходит сертификационные испытания и соответствует сертифицированному изделию, а ПО базового (base, только в версиях 1.7/4.7) и расширенного (extended) репозиториев является дополнительным, не проходит сертификационные испытания и не входит в состав сертифицированного изделия. Это описано в описании структуры репозиториев Astra Linux Special Edition. Отсюда практический вывод: источник пакета влияет на сертификационный статус окружения, и выбирать его нужно осознанно.
Для Astra фиксируйте версию и источник пакета: запишите, из какого репозитория пришел docker-compose-plugin, и придерживайтесь этого источника при обновлениях, иначе после очередного apt upgrade окружение изменится непредсказуемо. Базовые операции с контейнерами на таких системах разобраны в руководстве по Docker для системных администраторов.
Конфликты со старым docker-compose и очистка окружения
Старый пакет и новый плагин спокойно сосуществуют, пока никто не сверяет версии. Проблемы начинаются, когда скрипт деплоя вызывает docker-compose, а документация проекта описывает docker compose.
Как отличить старый пакет от плагина
dpkg -l | grep docker-compose покажет пакеты, установленные через apt: имя, версию, статус. which -a docker-compose перечислит все бинарники с этим именем в PATH, включая положенные вручную в /usr/local/bin. docker compose version покажет версию плагина. Наличие docker-compose в PATH ничего не говорит о плагине, и наоборот: это независимые вещи.
Удаление и повторная проверка
- Проверьте зависимости: apt-cache rdepends docker-compose. Если пакет нужен другому инструменту, удаление сломает и его.
- Удалите пакет: sudo apt remove docker-compose.
- Проверьте остатки: ls -l /usr/bin/docker-compose /usr/local/bin/docker-compose. Файл, принадлежащий пакету, уберет apt; положенный вручную удалите сами, предварительно убедившись через dpkg -S, что он не принадлежит другому пакету.
- При необходимости переустановите плагин: sudo apt-get install --reinstall docker-compose-plugin.
- Проверьте результат: docker compose version и docker compose config в каталоге проекта.
Compose-файлы при удалении бинарника не затрагиваются: это обычные YAML-файлы в репозитории. Пройдитесь по скриптам деплоя и CI-конфигам, найдите вызовы docker-compose и замените их на docker compose, если они запускают старую команду.
Проверка: compose как подкоманда, версия и работа без sudo
Проверки идут в порядке от простого к сложному. docker compose version: плагин виден. docker compose config в каталоге с файлом: конфигурация разбирается, интерполяция переменных работает. docker info: демон отвечает. docker ps без sudo: прав достаточно.
Разбор самого файла и типовых конструкций есть в практическом руководстве по Docker Compose.
Добавление пользователя в группу docker
sudo usermod -aG docker $USER добавляет текущего пользователя в группу docker. Изменение применяется в новой сессии: перелогиньтесь или выполните newgrp docker для текущего терминала. Проверка: id -nG показывает группы пользователя, docker ps работает без sudo.
Оговорка по безопасности: официальная документация Docker указывает, что членство в группе docker предоставляет пользователю привилегии уровня root. Демон по умолчанию создает Unix-сокет /var/run/docker.sock, доступ к которому требует либо прав root, либо членства в группе docker, а привязка демона к сокету с пользовательской группой создает риски, поскольку может позволить непривилегированным пользователям получить root-доступ на хосте. Добавляйте только доверенных пользователей и не используйте этот способ на общих машинах без понимания последствий.
Что делать, если версия не v2
Сначала определите, что именно выполняется. which -a docker-compose и which docker показывают пути. Если docker-compose ведет в /usr/local/bin, там лежит вручную скачанный бинарник, и он перекрывает ожидаемое поведение. Если docker compose выдает старую версию, проверьте источник пакета: apt-cache policy docker-compose-plugin покажет репозиторий, и это может оказаться дистрибутив с отставшей веткой.
Порядок диагностики: which -a docker-compose, docker-compose version, docker compose version, apt-cache policy docker-compose-plugin. Эти четыре команды закрывают почти все случаи расхождения версий.
Типичные ошибки и их устранение
Формулировки сообщений зависят от версии CLI и дистрибутива, поэтому ниже смысловые группы: что видит пользователь, откуда это берется и что сделать.
| Симптом | Вероятная причина | Действие |
|---|---|---|
| CLI сообщает, что compose не команда docker | Плагин не установлен или Docker CLI его не видит | Проверить пакет docker-compose-plugin и каталог cli-plugins, затем docker compose version |
| command not found для docker | Docker CLI отсутствует или не в PATH | which docker, установить Engine, проверить PATH |
| permission denied при обращении к сокету | Пользователь не в группе docker или группа не применилась | usermod -aG docker, перелогин, проверка через id -nG |
| CLI не может подключиться к демону | Служба остановлена или выбран другой контекст | systemctl status docker, docker context ls |
| Версия не v2 | Старый бинарник в PATH или пакет из устаревшего репозитория | which -a, apt-cache policy, удаление остатков |
| Предупреждение об устаревшем ключе version в файле | Ключ version объявлен устаревшим и носит информативный характер | Удалить ключ, проверить docker compose config |
Ошибки прав доступа
Проверьте три вещи по порядку: id -nG показывает, есть ли docker в списке групп; ls -l /var/run/docker.sock показывает права на сокет; docker context ls показывает, к какому демону обращается CLI. Отсутствие группы лечится usermod с последующим перелогином, а не постоянным sudo: sudo скрывает проблему и создает файлы в проекте с владельцем root.
Ошибки версии и путей
Диагностика идет от общего к частному: which -a docker-compose, echo $PATH, ls по каталогу cli-plugins. Если в PATH два бинарника, порядок каталогов решает, что запустится. Если плагин лежит не в стандартном каталоге, CLI его не найдет, и это видно по отсутствию подкоманды при работающем docker ps.
Чек-лист рабочего окружения
- docker compose version возвращает ветку v2. Признак успеха: номер версии начинается с 2.
- docker ps выполняется без sudo. Признак успеха: список контейнеров без ошибок доступа.
- docker compose config в каталоге проекта разбирает файл. Признак успеха: нормализованный YAML без ошибок.
- which -a docker-compose пуст либо указывает на путь, который вы контролируете. Признак успеха: нет забытого бинарника в /usr/local/bin.
- apt-cache policy docker-compose-plugin показывает ожидаемый источник пакета. Признак успеха: репозиторий совпадает с выбранным маршрутом.
- Для Astra Linux записан источник и версия пакета. Признак успеха: при следующем обновлении понятно, откуда придет новая версия.
Перед раскаткой на прод сверьте адреса репозиториев, формат ключей и поддерживаемые ветки дистрибутивов с официальной инструкцией по установке Compose plugin и требованиями вашей системы: эти детали меняются между релизами, а остальная последовательность шагов остается рабочей.