Docker Compose plugin в Linux: современная работа с compose.yaml

Docker Compose plugin запускается командой docker compose через пробел и ставится пакетом docker-compose-plugin из репозитория Docker, а в Arch пакетом docker-compose. Конфигурация хранится в compose.yaml без устаревшего поля version. Ниже установка, пример файла с healthcheck, повседневные команды, watch и переход со старого docker-compose.

docker-compose и docker compose: в чём разница

Если в инструкции написано docker-compose up через дефис, перед вами текст из прошлой эпохи. Старый Compose на Python перестал получать обновления в 2023 году. Сейчас Compose устроен как плагин Docker CLI на Go и вызывается через пробел: docker compose up. Плагин сам находит файл в каталоге, понимает спецификацию Compose без устаревшего поля version и умеет вещи, которых в v1 не было: watch, include, ожидание готовности сервисов.

С нумерацией версий тоже не всё очевидно. После ветки 2.x вышла сразу 5.0. По документации Docker, Compose v5 функционально равен v2, а номер выбрали, чтобы не путать программу со старыми форматами файлов "v2" и "v3". Главные отличия v5: официальный Go SDK и сборка образов, которая теперь передаётся Docker Bake, как у docker build. На октябрь 2026 года актуальна ветка 5.x.

docker compose version

Если команда ответила docker: 'compose' is not a docker command, плагин не установлен. Это лечится в следующем разделе.

Установка плагина Compose

Debian и Ubuntu

Документация Docker рекомендует ставить движок и плагины из репозитория Docker. Если он уже подключён по официальной инструкции, достаточно одного пакета:

sudo apt update
sudo apt install docker-compose-plugin

В штатных репозиториях Debian и Ubuntu тоже есть Docker и Compose, но версии там заметно отстают и названия пакетов отличаются. Смешивать пакеты из двух источников не стоит.

Fedora

sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker

Команда работает после подключения репозитория Docker для Fedora. Если вы предпочитаете Podman, у него свой путь, и для постоянных сервисов удобнее Podman Quadlet.

Arch Linux

sudo pacman -S docker docker-compose docker-buildx

Пакет docker-compose в Arch уже является плагином и работает как docker compose.

Ручная установка для одного пользователя

Если прав root нет, бинарник с GitHub кладут в каталог плагинов пользователя. Подставьте актуальный номер версии со страницы релизов:

mkdir -p ~/.docker/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/vX.Y.Z/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

Чтобы запускать контейнеры без sudo и без группы docker, которая фактически даёт права root, посмотрите режим Docker Rootless.

Как устроен compose.yaml

Плагин ищет файл в текущем каталоге в таком порядке: compose.yaml, compose.yml, затем старые имена docker-compose.yaml и docker-compose.yml. Для новых проектов используйте compose.yaml. Строку version: "3.8" в начале больше не пишут: Compose её игнорирует и выводит предупреждение, что атрибут устарел.

Пример: веб-приложение и PostgreSQL, где приложение стартует только после того, как база реально готова принимать подключения.

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 10
  app:
    build: .
    ports:
      - "8080:8080"
    env_file: .env
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

volumes:
  pgdata:

Обратите внимание на condition: service_healthy. Обычный depends_on ждёт только запуска контейнера, а не готовности программы внутри. Без healthcheck приложение часто падает на первом подключении к базе, которая ещё инициализируется.

Команды на каждый день

Все команды выполняются в каталоге с compose.yaml или с ключом -f путь/к/файлу.

Обновление сервисов на домашнем сервере обычно выглядит так:

docker compose pull
docker compose up -d
docker image prune -f

Последняя команда удаляет образы, оставшиеся без тегов после обновления. Старые образы и кэш сборки со временем занимают десятки гигабайт, об этом подробнее в статье как освободить место на диске.

Переменные, файл .env и профили

Compose подставляет переменные окружения в файл при запуске. Значения берутся из оболочки и из файла .env рядом с compose.yaml. Можно задавать значения по умолчанию:

# .env
DB_PASSWORD=секрет
APP_PORT=8080

# в compose.yaml
ports:
  - "${APP_PORT:-8080}:8080"

Файл .env добавьте в .gitignore, а в репозиторий кладите пример вроде .env.example. Посмотреть, что получилось после подстановки всех переменных и слияния файлов, помогает команда, которая заодно проверяет синтаксис:

docker compose config

Профили позволяют держать в одном файле вспомогательные сервисы, которые нужны не всегда, например pgAdmin или инструменты отладки:

services:
  pgadmin:
    image: dpage/pgadmin4
    profiles: ["debug"]

Такой сервис не стартует при обычном docker compose up, а запускается только с docker compose --profile debug up -d.

Режим разработки: override-файлы и watch

Если рядом с compose.yaml лежит compose.override.yaml, Compose автоматически накладывает его поверх основного файла. Удобная схема: в основном файле настройки для сервера, в override пробросы портов, тома с исходниками и отладочные переменные. На сервере override просто не копируют. Явно указать набор файлов можно так:

docker compose -f compose.yaml -f compose.prod.yaml up -d

Для разработки есть режим watch. Он следит за файлами проекта и синхронизирует изменения в контейнер или пересобирает образ:

services:
  app:
    build: .
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: package.json

docker compose watch

Для больших проектов пригодится ключ верхнего уровня include: он подключает compose-файлы других команд или каталогов, при этом относительные пути в каждом файле считаются от его собственного расположения. Если вы работаете в Windows через WSL2, держите исходники внутри файловой системы Linux, иначе watch и сборка будут медленными. Подробности в статье про Docker в WSL2.

Переход со старого docker-compose

Большинство старых файлов работают без правок, но несколько мест стоит проверить.

1. Удалите строку version: из начала файла.
2. Имена контейнеров теперь собираются через дефис: проект-web-1 вместо проект_web_1. Если скрипты мониторинга или бэкапа обращались к контейнерам по имени, их нужно поправить или задать в файле явный container_name.
3. Секция links не нужна: сервисы одного проекта и так видят друг друга по имени через общую сеть.
4. Если старые скрипты вызывают docker-compose, создайте ссылку на плагин вместо установки v1.

# путь для пакетов docker-ce в Debian, Ubuntu и Fedora
sudo ln -s /usr/libexec/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose

Ошибки Compose и откат версии

• permission denied while trying to connect to the Docker daemon socket. Пользователь не в группе docker. Добавьте его командой sudo usermod -aG docker $USER и перезайдите в сессию, либо используйте rootless-режим.
• port is already allocated. Порт занят другим контейнером или службой. Найдите виновника через sudo ss -tlnp | grep 8080.
• Сервис постоянно перезапускается. Смотрите docker compose logs app: почти всегда причина в переменных окружения или недоступной базе.
• Пропали данные после down. Команда docker compose down -v удаляет и тома. Без -v они остаются.

Если новая версия плагина сломала ваш сценарий, откатитесь на предыдущую. В Debian и Ubuntu список доступных версий показывает apt:

apt-cache madison docker-compose-plugin
sudo apt install docker-compose-plugin=ВЕРСИЯ
sudo apt-mark hold docker-compose-plugin

В Fedora то же делает sudo dnf downgrade docker-compose-plugin. Не забудьте снять фиксацию (apt-mark unhold), когда проблему исправят. Справочник по всем ключам файла есть в разделе Docker Compose официальной документации, а идеи для постоянных сервисов дома собраны в статье про домашний сервер на Linux.

Частые вопросы

Документация и источники

• Docker Compose documentation, Docker, 2026
• Install the Docker Compose plugin, Docker, 2026
• History and development of Docker Compose, Docker, 2026
• Compose file reference, Docker, 2026

Команды проверены на актуальных версиях дистрибутивов на момент обновления. Перед изменением системных настроек сделайте резервную копию.