Как использовать profiles, override и несколько Compose-файлов
На этой странице
Profiles включают необязательные сервисы только по запросу: сервис с profiles: [tools] стартует лишь при --profile tools. Несколько файлов (-f compose.yaml -f compose.prod.yaml) сливаются по порядку: последующие дополняют и переопределяют предыдущие. Файл compose.override.yaml рядом с основным подключается автоматически — его используют для локальных dev-настроек. Для явного подключения файлов есть ещё поле include.
Вопрос
Как разделить dev-, production- и вспомогательные настройки Compose?
Profiles
services:
api:
build: .
db:
image: postgres:18
adminer:
image: adminer
ports: ["8080:8080"]
profiles: [tools]
mailpit:
image: axllent/mailpit
ports: ["8025:8025"]
profiles: [tools, mail]docker compose up -d # api и db
docker compose --profile tools up -d # + adminer и mailpit
COMPOSE_PROFILES=mail docker compose up -d
docker compose run --rm adminer # явный запуск включает сервис и без профиляСервисы без profiles запускаются всегда. Типичные кандидаты в профили: GUI для БД, Mailpit, отладочные контейнеры, стек мониторинга, редкие воркеры.
Слияние нескольких файлов
# compose.yaml — общая база
services:
api:
image: ghcr.io/team/api:${TAG:-latest}
environment:
NODE_ENV: production# compose.dev.yaml — разработка
services:
api:
build: .
command: ["npm", "run", "dev"]
environment:
NODE_ENV: development
ports: ["3000:3000", "9229:9229"]docker compose -f compose.yaml -f compose.dev.yaml up -d
docker compose -f compose.yaml -f compose.dev.yaml config # посмотреть результат слиянияПравила слияния: одиночные значения (image, command) заменяются, словари (environment, labels) объединяются по ключам, списки ports и expose дополняются.
compose.override.yaml
compose.yaml ← база
compose.override.yaml ← подключается автоматически при обычном `docker compose up`
compose.prod.yaml ← явно: -f compose.yaml -f compose.prod.yamlПопулярная схема: в compose.override.yaml — bind mounts, dev-команда и открытые порты; для production файл override не используют, а передают -f compose.yaml -f compose.prod.yaml. Если указан хотя бы один -f, автоматический override не подключается.
include
# compose.yaml
include:
- ./infra/compose.db.yaml
- ./infra/compose.observability.yaml
services:
api:
build: .include подключает отдельный Compose-файл как самостоятельный модуль со своими относительными путями — удобно для монорепозиториев и общих инфраструктурных частей.
Частые ошибки
- Держать dev, prod и отладку в одном огромном файле с комментариями «раскомментируй».
- Случайно запустить Adminer в production без профиля.
- Не понимать порядок
-f: более поздний файл важнее. - Хранить production-секреты в override-файле в git.
- Забыть, что при явных
-fcompose.override.yamlне подключается.
Что важно помнить
- Профили — для необязательных сервисов, файлы — для разных окружений.
- Итог слияния всегда проверяют через
docker compose config. COMPOSE_FILEиCOMPOSE_PROFILESможно задать в.env, чтобы не писать флаги каждый раз.
Мини-шпаргалка
profiles: [tools]+--profile tools.-f base -f env— слияние, последний важнее.compose.override.yaml— автоматически для dev.include— модульные файлы.docker compose config— проверить результат.
Документация
Docker: Using profiles with Compose, Docker: Merge Compose files, Docker: Include.