
РазборЕвгений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.
Читайте также
- n8n: что это, как запустить и где он хранит ключи
- Hermes Agent: установка и настройка, как я завёл его на Mac и в Telegram
- Локальная нейросеть на ПК: как запустить локальный ИИ и какую модель выбрать
- Как создать ИИ-агента: рабочий агент на Python за 57 строк и что нужно ему дальше
- Нейросеть для написания текста: черновик по источникам и проверка
Источники
- Docker Docs: How Compose works
- Docker Docs: History and development of Compose
- Docker Docs: Compose FAQ
- Docker Docs: Compose file reference
- Docker Docs: Version and name top-level elements
- Docker Docs: Services top-level element
- Docker Docs: Compose Build Specification
- Docker Docs: Networks top-level element
- Docker Docs: Volumes top-level element
- Docker Docs: Secrets top-level element
- Docker Docs: Secrets in Compose
- Docker Docs: Variable interpolation
- Docker Docs: Interpolation
- Docker Docs: Using profiles with Compose
- Docker Docs: Compose Develop Specification
- Docker Docs: Use Compose Watch
- Docker Docs: docker compose CLI
- Docker Docs: docker compose up
- Docker Docs: docker compose down
- Docker Docs: docker compose logs
- Docker Docs: docker compose ps
- Docker Docs: docker compose exec
- Docker Docs: docker compose pull
- Docker Docs: docker compose config
- Docker Docs: docker compose watch
- Docker Docs: Packet filtering and firewalls
- Docker Docs: Port publishing and mapping
- Docker Docs: Volumes
- Docker Docs: Build secrets
- Docker Official Image postgres: README
- PostgreSQL Docs: SQL Dump
- Docker Blog: New Docker Compose v2 and v1 deprecation
- Docker Blog: Announcing Compose V2 General Availability
- Хабр (RUVDS): Руководство по Docker Compose для начинающих
- Хабр (СИБУР): Основы Docker: контейнеризация, Dockerfile и Docker Compose. Часть 2
- PostgreSQL 17: pg_isready
- PostgreSQL 17: pg_dump
- PostgreSQL 17: psql
- Docker Docs: docker compose run
- Docker Docs: docker image pull
- OpenSSL 3.0: openssl-rand