undercode_
  1. Главная
  2. Блог
  3. Docker Compose: compose.yaml, несколько сервисов и основные команды
Схема: контейнеры веб-приложения, PostgreSQL и Redis на общей сети, рядом файл compose.yaml

Разбор16 мин чтения

Docker Compose: compose.yaml, несколько сервисов и основные команды

Как устроен compose.yaml: сервисы, сети, тома, healthcheck, профили и secrets. Чем docker compose отличается от docker-compose, основные команды и частые ошибки.

Содержание · 8 разделов

Docker Compose описывает приложение из нескольких контейнеров в одном YAML-файле и управляет ими как одним проектом: веб-сервис, база и кэш поднимаются одной командой и останавливаются другой. Ниже разбираю устройство compose.yaml на примере из трёх сервисов, разницу между .env, env_file, environment и secrets, основные команды и ошибки, которые чаще всего встречаются в чужих примерах. Всё сверено с документацией Docker на 1 ноября 2026 года. Пример из статьи вместе с файлами приложения из листингов ниже запущен 1 ноября на macOS через OrbStack (Docker Engine 29.4.0, Docker Compose v5.1.2): сборка, проверки здоровья, ответ приложения, дамп базы и восстановление из него. Порт 8080 на той машине был занят, поэтому в прогоне на хосте стоял 18080.

Что такое Docker Compose

В документации модель Compose держится на трёх сущностях:

  • services (сервисы): контейнеры, запущенные из одного образа с одной конфигурацией, один или несколько раз;
  • networks (сети): по ним сервисы общаются между собой;
  • volumes (тома): в них сервисы хранят данные, которые должны пережить пересоздание контейнера.

По умолчанию Compose создаёт для приложения одну сеть. Каждый контейнер подключается к ней, и другие контейнеры находят его по имени сервиса. Поэтому веб-приложение ходит в PostgreSQL по адресу db, а не по IP.

Если нужен один контейнер, хватит docker run. Compose нужен, когда сервисов несколько и у них общие сети, порядок запуска, переменные и данные. Так обычно поднимают self-hosted инструменты вроде n8n или связку агента с базой и кэшем на своём сервере.

docker-compose, docker compose и v5

В инструкциях встречаются три варианта, и путаница идёт отсюда.

  • docker-compose (через дефис): Compose v1, вышел в 2014 году, написан на Python. В файлах v1 обычно стоит version: со значениями от 2.0 до 3.8. Docker прекратил поддержку v1 после июня 2023 года.
  • docker compose (через пробел): Compose v2, анонсирован в 2020 году, написан на Go. Он игнорирует поле version и читает файл по Compose Specification.
  • Compose v5 вышел в 2025 году. Команда та же, docker compose, по функциям он совпадает с v2. Главное отличие в официальном Go SDK.

Свою версию проверяют командой docker compose version.

Поле version в начале файла теперь только информационное. Compose всегда проверяет файл по самой свежей схеме и выдаёт предупреждение, что поле устарело. Его можно удалить. В русскоязычных инструкциях до сих пор встречается совет начинать файл с version: "3", например в переводе на Хабре; для современного Compose это лишняя строка.

Файл по умолчанию называется compose.yaml, подходит и compose.yml. Старые имена docker-compose.yaml и docker-compose.yml поддерживаются для совместимости. Если в папке лежат оба варианта, Compose возьмёт compose.yaml.

compose.yaml на примере: веб-приложение, PostgreSQL и Redis

Типовой проект: Python-приложение, PostgreSQL как база, Redis как кэш, плюс клиент psql, который запускается только по требованию. Структура папки:

project/
├── compose.yaml
├── web.env
├── secrets/
│   └── db_password.txt
└── web/
    ├── Dockerfile
    ├── app.py
    └── requirements.txt

Приложение здесь учебный стенд: оно показывает, что веб дошёл до базы и Redis. Таблицу оно создаёт прямо в обработчике и пишет в базу на каждый GET, поэтому для рабочего сервиса не годится: там нужны нормальный HTTP-сервер, миграции, обработка ошибок и контроль доступа. Три файла минимальные, их хватает, чтобы пример поднялся как есть. web/requirements.txt:

psycopg[binary]==3.2.6
redis==5.2.1

web/Dockerfile:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
CMD ["python", "app.py"]

web/app.py на каждый запрос пишет визит в PostgreSQL, увеличивает счётчик в Redis и отвечает JSON:

import json, os
from pathlib import Path
from http.server import BaseHTTPRequestHandler, HTTPServer
import psycopg, redis

cache = redis.Redis.from_url(os.environ["REDIS_URL"])

def db_connect():
    secret = Path(os.environ["DB_PASSWORD_FILE"]).read_text().strip()
    return psycopg.connect(host=os.environ["DB_HOST"], port=os.environ["DB_PORT"],
                           dbname=os.environ["DB_NAME"], user=os.environ["DB_USER"],
                           password=secret)

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        try:
            with db_connect() as conn, conn.cursor() as cur:
                cur.execute("CREATE TABLE IF NOT EXISTS visits (id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, visited_at timestamptz DEFAULT now())")
                cur.execute("INSERT INTO visits DEFAULT VALUES")
                cur.execute("SELECT count(*) FROM visits")
                total = cur.fetchone()[0]
            body = json.dumps({"postgres_visits": total, "cache_visits": cache.incr("visits")}).encode()
            self.send_response(200)
        except Exception:
            body = b'{"error": "dependency unavailable"}'
            self.send_response(503)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(body)

HTTPServer(("0.0.0.0", 8000), Handler).serve_forever()

Сам compose.yaml:

services:
  web:
    build:
      context: ./web
      dockerfile: Dockerfile
    ports:
      - "127.0.0.1:8080:8000"
    env_file:
      - ./web.env
    environment:
      DB_HOST: db
      DB_PORT: "5432"
      DB_NAME: app
      DB_USER: app
      DB_PASSWORD_FILE: /run/secrets/db_password
      REDIS_URL: redis://redis:6379/0
    secrets:
      - db_password
    networks:
      - frontend
      - backend
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped
    develop:
      watch:
        - path: ./web
          action: rebuild

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password
    volumes:
      - pg_data:/var/lib/postgresql/data
    networks:
      - backend
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 20s
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    networks:
      - backend
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10
    restart: unless-stopped

  psql:
    image: postgres:17-alpine
    profiles:
      - tools
    command: ["psql", "-h", "db", "-U", "app", "-d", "app"]
    networks:
      - backend
    depends_on:
      db:
        condition: service_healthy

volumes:
  pg_data:

networks:
  frontend:
  backend:
    internal: true

secrets:
  db_password:
    file: ./secrets/db_password.txt

В web.env лежит одна строка APP_ENV=development. Приложение читает адрес базы и Redis из переменных, а пароль из файла, путь к которому указан в DB_PASSWORD_FILE.

Дальше по ключам.

image и build

image задаёт готовый образ в формате [реестр/][проект/]образ[:тег|@digest]. У db и redis тег указан явно: postgres:17-alpine, redis:7-alpine. В прогоне 1 ноября под ними оказались PostgreSQL 17.11 и Redis 7.4.12. Без тега Docker берёт :latest. Образ, закреплённый по digest, по документации Docker всегда один и тот же.

build говорит Compose собрать образ из исходников. context это папка с Dockerfile (относительный путь считается от папки проекта), dockerfile задаёт другое имя файла. Если у сервиса указаны и build, и image, Compose решает по правилам pull_policy.

ports

Запись "127.0.0.1:8080:8000" значит: порт 8000 контейнера доступен на порту 8080 хоста, и только с самого хоста (оговорку для старых версий Docker Engine смотрите в разделе о безопасности). Если IP не указать, Docker привяжет порт ко всем интерфейсам, 0.0.0.0. В документации Docker прямо сказано, что публикация портов по умолчанию небезопасна: опубликованный порт виден и хосту, и внешнему миру.

У db и redis секции ports нет совсем. Наружу им открываться незачем: веб-сервис достаёт их по внутренней сети по именам db и redis.

networks

Сетей две. frontend обычная, backend объявлена с internal: true, то есть изолирована от внешнего мира. База и Redis подключены только к backend. Веб подключён к обеим сетям и через backend ходит в базу и Redis.

volumes

Ключ volumes у сервиса монтирует именованные тома или папки хоста. Типы монтирования: volume, bind, tmpfs и npipe. В примере база пишет данные в именованный том pg_data, объявленный на верхнем уровне файла. docker compose up создаёт том, если его ещё нет, иначе берёт существующий.

Путь важен. Для PostgreSQL 17 и ниже том монтируют в /var/lib/postgresql/data. В описании официального образа предупреждают: если смонтировать на уровень выше, в /var/lib/postgresql, данные базы не сохранятся при пересоздании контейнера.

healthcheck и depends_on

depends_on задаёт порядок запуска и остановки. Короткая запись (просто список имён) не ждёт, пока зависимость станет «здоровой»: она ждёт старта контейнера, а сам сервис внутри может быть ещё не готов. На это жалуются и в русскоязычных статьях, например у СИБУРа на Хабре.

Длинная запись с condition: service_healthy ждёт, пока зависимость пройдёт свой healthcheck. Поэтому у db и redis проверки заданы: pg_isready для PostgreSQL и redis-cli ping для Redis. healthcheck в Compose работает так же и с теми же значениями по умолчанию, что инструкция HEALTHCHECK в Dockerfile.

Двойной доллар в $$POSTGRES_USER нужен, чтобы Compose не подставлял переменную сам при чтении файла. Её раскроет оболочка внутри контейнера.

restart

restart задаёт, что делать, когда контейнер завершился. По умолчанию no: не перезапускать никогда. always перезапускает всегда, пока контейнер не удалят. unless-stopped перезапускает при любом коде выхода, но перестаёт, если сервис остановили или удалили. Для долгоживущих сервисов в примере стоит unless-stopped.

profiles

Сервисы без profiles всегда включены и запускаются обычным docker compose up без списка сервисов. Сервис с профилем стартует, когда включён его профиль или когда его вызвали по имени. psql в примере помечен профилем tools, поэтому обычный docker compose up поднимет web, db и redis, а клиент базы не тронет.

Для разовых утилит удобен вызов по имени, профиль при этом включать не нужно:

docker compose run --rm psql

Секрет этому сервису не выдан, поэтому psql спросит пароль в терминале. После выхода --rm удалит контейнер.

develop.watch

Блок develop.watch описывает правила: что делать, когда меняются локальные файлы. action: rebuild пересобирает образ по секции build и пересоздаёт сервис. Есть и restart, он просто перезапускает контейнер; это действие доступно с Docker Compose 2.32.0. Режим включается командой docker compose watch. Bind mount он не заменяет, это дополнение для разработки в контейнерах.

Переменные и секреты: .env, env_file, environment, secrets

Четыре механизма похожи по названию и делают разные вещи.

  • .env в папке проекта, рядом с compose.yaml. Переменные из него Compose подставляет в сам compose.yaml при docker compose up, в записи вида ${ИМЯ}. Это подстановка в файл: чтобы значение попало в контейнер, его указывают в environment или env_file.
  • env_file у сервиса. Список файлов, переменные из которых передаются в контейнер. Файлы читаются сверху вниз.
  • environment у сервиса. Переменные контейнера прямо в YAML. Значения из environment перекрывают значения из env_file, даже пустые. Булевы true, false, yes, no берите в кавычки, иначе YAML-парсер превратит их в True или False.
  • secrets. Секрет объявляется на верхнем уровне файла (из файла через file: или из переменной хоста через environment:) и выдаётся только тем сервисам, у которых он указан. Внутри контейнера он появляется файлом /run/secrets/<имя>. Секреты работают только в Linux-контейнерах.

Для паролей подходят secrets. Часть официальных образов, включая postgres и mysql, понимает переменные с суффиксом _FILE: POSTGRES_PASSWORD_FILE=/run/secrets/db_password берёт пароль из файла. Так пароль не лежит открытым текстом в compose.yaml и не виден в списке переменных контейнера.

Файл с паролем создайте сами, например случайной строкой из openssl rand, и не коммитьте в git:

mkdir -p secrets
openssl rand -base64 24 > secrets/db_password.txt

Локальный Compose ничего не шифрует: он монтирует этот файл в контейнер как есть, и на диске сервера пароль лежит открытым текстом. Закройте файл от других пользователей сервера, но так, чтобы его мог прочитать пользователь, от которого работает процесс в контейнере.

Секреты для сборки образа отдельная история. Аргументы сборки и переменные окружения для них не годятся: они остаются в итоговом образе. Docker советует secret mounts или SSH mounts.

Основные команды docker compose

Все команды запускаются из папки с compose.yaml.

КомандаЧто делает
docker compose config -qПроверяет файл и ничего не печатает. Без -q показывает итоговую модель: подставленные переменные, слитые файлы -f
docker compose up -dПоднимает проект в фоне. С --build сначала собирает образы
docker compose psКонтейнеры проекта, их статус и порты
docker compose logs -f webЛоги сервиса в реальном времени
docker compose exec db psql -U app -d appКоманда внутри запущенного контейнера
docker compose pullСкачивает образы сервисов, контейнеры не запускает
docker compose watchСледит за файлами и пересобирает сервис по правилам develop.watch
docker compose downОстанавливает и удаляет контейнеры и сети проекта
docker compose down -vТо же плюс удаляет именованные тома из volumes и анонимные тома

Порядок для первого запуска на Docker-хосте: docker compose config -q, затем docker compose up -d --build и docker compose ps. Логи docker compose logs -f web удобнее смотреть во втором терминале. Ответ приложения проверяют на том же хосте командой curl http://127.0.0.1:8080/. Порт привязан к 127.0.0.1, поэтому на удалённом сервере браузер с вашего компьютера этот адрес не откроет: к вебу ходят через обратный прокси на том же сервере, об этом раздел о безопасности. Ответ вида {"postgres_visits": 1, "cache_visits": 1} значит, что веб дошёл и до базы, и до Redis. Если порт 8080 на хосте занят, поменяйте левую часть записи в ports.

Обновить образы: docker compose pull, затем docker compose up -d. Если сервис собирается из build, добавьте --build.

down без флагов удаляет контейнеры сервисов, сети из секции networks и сеть по умолчанию. Тома остаются, внешние сети и тома не удаляются никогда. Анонимные тома тоже не удаляются, но у них нет стабильного имени, и следующий up их не подключит. Поэтому данные, которые должны пережить обновление, держат в именованном томе или в bind mount. down -v удаляет и именованные тома, то есть на рабочем сервере стирает базу.

Безопасность и данные

Порты и ufw. Если на сервере включён ufw, опубликованный порт Docker это не закрывает. Docker направляет трафик контейнеров через таблицу nat, и пакеты уходят в сторону раньше, чем доходят до цепочек INPUT и OUTPUT, на которых работает ufw. Поэтому база и Redis в примере без ports, а веб опубликован на 127.0.0.1: снаружи к нему ходят через обратный прокси на том же сервере. С адресом 127.0.0.1 опубликованный порт доступен только самому хосту. Оговорка из документации: в Docker Engine до версии 28.0.0 порт, опубликованный на localhost, могли достать хосты из того же L2-сегмента, например подключённые к тому же коммутатору.

Пароли. В compose.yaml и в образе паролей нет: пароль приходит файлом через secrets. Сам файл secrets/db_password.txt лежит рядом с проектом открытым текстом, поэтому добавьте его в .gitignore и ограничьте к нему доступ.

Том не бэкап. Том живёт отдельно от контейнера: контейнер удалили, данные остались. От down -v, удалённого тома или сломанного диска это не спасает. Для PostgreSQL штатный способ резервной копии pg_dump. Дамп согласован, даже если с базой в этот момент работают. В текстовом формате это SQL-скрипт, который восстанавливает базу на момент сохранения.

docker compose exec -T db pg_dump -U app -d app > backup.sql

Такой дамп восстанавливают через psql, например в пустую базу на тестовой копии проекта:

docker compose exec -T db psql -U app -d app < backup.sql

В прогоне 1 ноября цикл прошёл целиком: дамп, docker compose down -v, новая пустая база, восстановление, и в таблице снова были обе записи. Резервная копия, из которой ни разу не восстанавливались, остаётся предположением. Docker в документации по томам описывает и копирование самого тома через временный контейнер, этими приёмами автоматизируют бэкап, миграцию и проверку восстановления.

Частые ошибки

  • version: в начале файла. Современный Compose его игнорирует и предупреждает, что поле устарело.
  • depends_on без condition: service_healthy. Веб может стартовать раньше, чем база готова принимать соединения. Если приложение не повторяет попытку подключения, первые запросы кончатся ошибкой.
  • 5432:5432 у базы. Порт открыт на всех интерфейсах, ufw его не закрывает. Базе публикация не нужна, если к ней ходят только соседние сервисы.
  • Пароль прямо в YAML вида POSTGRES_PASSWORD: secret. При коммите такого файла пароль попадёт в репозиторий, а в контейнере он виден в списке переменных. Используйте secrets и _FILE.
  • docker compose down -v на рабочем сервере. Удаляет именованные тома вместе с базой.
  • Том смонтирован не туда. Для postgres:17-alpine том монтируют в /var/lib/postgresql/data. Если смонтировать только родительскую /var/lib/postgresql, данные не сохранятся при пересоздании контейнера.
  • Образ без закреплённой версии. Без тега Docker берёт :latest. Указывайте конкретный тег, а для фиксации точного образа пишите его по digest, postgres@sha256:…. Команда docker compose config --resolve-image-digests выводит итоговую модель с digest вместо тегов: нужные строки переносят в image своего compose.yaml.

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

Чем docker compose отличается от docker-compose? docker-compose это Compose v1 на Python, его поддержка закончилась после июня 2023 года. docker compose через пробел это v2, написанный на Go, и v5 с той же командой. Файл они читают по Compose Specification, в которую влились старые форматы 2.x и 3.x, а поле version игнорируют.

Нужно ли писать version в compose.yaml? Нет. Поле осталось для обратной совместимости, Compose проверяет файл по последней схеме и выдаёт предупреждение.

Как дождаться, пока база запустится? healthcheck у базы и depends_on с condition: service_healthy у зависимого сервиса, как в примере выше.

Где хранить пароли для Docker Compose? В файлах, подключённых через secrets: внутри контейнера они лежат в /run/secrets/. Если образ понимает переменные _FILE, передавайте путь к файлу, а сам файл держите вне git.

Почему порт контейнера открыт, хотя ufw включён? Docker пускает трафик опубликованных портов через таблицу nat, в обход цепочек, которые использует ufw. Не публикуйте лишние порты, а нужные привязывайте к 127.0.0.1.

Что удаляет docker compose down? Контейнеры и сети проекта, тома остаются. С -v уходят и тома вместе с данными.

Как запустить сервис из профиля? docker compose --profile tools up -d поднимет сервисы профиля tools и вместе с ними все сервисы без профиля. Один сервис вызывают по имени, docker compose run --rm psql, без включения профиля.

Короткий список проверки учебного стенда: config -q без ошибок, у db и redis в ps статус healthy, web запущен и отвечает на curl, psql запускается по требованию, у базы нет ports, файл с паролем вне git, дамп снят и хотя бы раз восстановлен на тестовой копии. По той же схеме из веб-сервиса, базы и кэша на одном сервере собирают и инструменты под ИИ: локальную модель через Ollama или Hermes Agent.

Читайте также

Источники

  1. Docker Docs: How Compose works
  2. Docker Docs: History and development of Compose
  3. Docker Docs: Compose FAQ
  4. Docker Docs: Compose file reference
  5. Docker Docs: Version and name top-level elements
  6. Docker Docs: Services top-level element
  7. Docker Docs: Compose Build Specification
  8. Docker Docs: Networks top-level element
  9. Docker Docs: Volumes top-level element
  10. Docker Docs: Secrets top-level element
  11. Docker Docs: Secrets in Compose
  12. Docker Docs: Variable interpolation
  13. Docker Docs: Interpolation
  14. Docker Docs: Using profiles with Compose
  15. Docker Docs: Compose Develop Specification
  16. Docker Docs: Use Compose Watch
  17. Docker Docs: docker compose CLI
  18. Docker Docs: docker compose up
  19. Docker Docs: docker compose down
  20. Docker Docs: docker compose logs
  21. Docker Docs: docker compose ps
  22. Docker Docs: docker compose exec
  23. Docker Docs: docker compose pull
  24. Docker Docs: docker compose config
  25. Docker Docs: docker compose watch
  26. Docker Docs: Packet filtering and firewalls
  27. Docker Docs: Port publishing and mapping
  28. Docker Docs: Volumes
  29. Docker Docs: Build secrets
  30. Docker Official Image postgres: README
  31. PostgreSQL Docs: SQL Dump
  32. Docker Blog: New Docker Compose v2 and v1 deprecation
  33. Docker Blog: Announcing Compose V2 General Availability
  34. Хабр (RUVDS): Руководство по Docker Compose для начинающих
  35. Хабр (СИБУР): Основы Docker: контейнеризация, Dockerfile и Docker Compose. Часть 2
  36. PostgreSQL 17: pg_isready
  37. PostgreSQL 17: pg_dump
  38. PostgreSQL 17: psql
  39. Docker Docs: docker compose run
  40. Docker Docs: docker image pull
  41. OpenSSL 3.0: openssl-rand
Консультация · 60 минут · 6 000 ₽Обсудить свою задачуОпишите задачу в Telegram-боте, разберём её на созвоне.