Docker Compose — инструмент для запуска многоконтейнерных приложений через один конфигурационный файл. Вместо того чтобы запускать каждый контейнер вручную командой docker run, вы описываете всю инфраструктуру в docker compose файле и поднимаете её одной командой. В этом руководстве — полный разбор: структура docker-compose.yml, основные docker compose команды, volumes, переменные окружения и готовый пример для n8n.
Что такое Docker Compose и зачем он нужен
Когда приложение состоит из нескольких сервисов — например, n8n + PostgreSQL + Redis — управлять ими по отдельности неудобно. Docker Compose решает эту проблему: один docker compose yml файл описывает все сервисы, сети и хранилища. Docker compose установка на Ubuntu и Linux выполняется через официальный репозиторий Docker — плагин docker compose (без дефиса) включён в Docker Engine начиная с версии 20.10.
Основные преимущества Docker Compose:
- Декларативное описание инфраструктуры — всё в одном файле
- Воспроизводимость — один и тот же docker compose yaml работает на любом сервере
- Простой старт и остановка всего стека одной командой
- Автоматическая сеть между docker compose контейнерами
Структура docker-compose.yml: разбор по полям
Docker compose file написан в формате YAML (расширения .yml и .yaml равнозначны). Основные секции:
version: "3.8" # версия формата Compose
services: # описание контейнеров
app:
image: n8nio/n8n # образ из Docker Hub
ports:
- "5678:5678" # внешний_порт:внутренний_порт
volumes:
- n8n_data:/home/node/.n8n
environment:
- DB_TYPE=postgresdb
depends_on:
- postgres # запускать после postgres
postgres:
image: postgres:15
volumes:
- pg_data:/var/lib/postgresql/data
volumes: # объявляем именованные volumes
n8n_data:
pg_data:
docker compose version — поле version указывает на версию формата файла. Для большинства проектов подходят версии 3.7–3.9. В последних версиях Docker Compose поле version необязательно, но рекомендуется для явного указания совместимости.
Основные команды Docker Compose
Рассмотрим все docker compose команды, которые нужны в повседневной работе. Все команды выполняются из папки, где лежит docker-compose.yml.
docker compose up — запуск стека
# Запустить все сервисы в фоне
docker compose up -d
# Запустить с пересборкой образов
docker compose up -d --build
# Запустить только один сервис
docker compose up -d postgres
Флаг -d (docker compose -d) означает detached mode — контейнеры работают в фоне. Без него логи выводятся в терминал и Ctrl+C останавливает все сервисы.
docker compose down — остановка и удаление
# Остановить и удалить контейнеры (volumes сохраняются)
docker compose down
# Удалить контейнеры и volumes
docker compose down -v
docker compose build — сборка образов
# Пересобрать все образы из Dockerfile
docker compose build
# Пересобрать конкретный сервис
docker compose build app
docker compose run — разовый запуск команды в container
# Запустить команду в docker compose container
docker compose run app python manage.py migrate
# Запустить bash в контейнере
docker compose run --rm app bash
docker compose run создаёт временный container, выполняет команду и удаляет его (с флагом --rm). Используется для разовых задач: миграции БД, генерация ключей, отладка.
Другие полезные команды
# Посмотреть статус контейнеров
docker compose ps
# Посмотреть логи всех сервисов
docker compose logs -f
# Войти в контейнер
docker compose exec n8n sh
# Перезапустить сервис
docker compose restart n8n
Docker Compose Volumes: как хранить данные
Docker compose volumes — механизм постоянного хранения данных. Без volumes данные внутри контейнера удаляются при его пересоздании. Различают два типа:
Именованные volumes (рекомендуется)
services:
postgres:
volumes:
- pg_data:/var/lib/postgresql/data
volumes:
pg_data: # Docker управляет этим volume сам
Именованные volumes хранятся в /var/lib/docker/volumes/. Они переживают docker compose down и удаляются только явно — командой docker compose down -v или docker volume rm.
Bind mounts — монтирование папки с хоста
services:
n8n:
volumes:
- ./my-n8n-data:/home/node/.n8n # ./папка_на_хосте:путь_в_контейнере
Bind mounts удобны для разработки: изменения в файлах на хосте сразу отражаются в контейнере. Для продакшена предпочтительны именованные volumes.
docker compose env: переменные окружения и .env файл
Хранить пароли и API-ключи прямо в docker compose yml — плохая практика. Правильный подход — файл .env в той же папке:
# .env файл
POSTGRES_PASSWORD=supersecret
N8N_ENCRYPTION_KEY=myrandomkey
DOMAIN=example.com
# docker-compose.yml
services:
postgres:
environment:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
n8n:
environment:
N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
WEBHOOK_URL: https://${DOMAIN}/
docker compose env — Docker Compose автоматически читает .env из текущей папки и подставляет переменные через синтаксис ${ПЕРЕМЕННАЯ}. Файл .env нужно добавить в .gitignore — он не должен попадать в репозиторий.
docker compose Контейнеры: сети и зависимости
Все docker compose контейнеры в одном стеке автоматически попадают в общую сеть. Обращаться к сервисам можно по имени из конфигурационного файла:
services:
n8n:
environment:
DB_POSTGRESDB_HOST: postgres # имя сервиса — это hostname
postgres:
image: postgres:15
Порядок запуска управляется через depends_on. Для проверки реальной готовности сервиса используют healthcheck:
postgres:
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
n8n:
depends_on:
postgres:
condition: service_healthy
Готовый docker-compose.yml для n8n с PostgreSQL и Redis
Пример полного стека для production-установки n8n на Ubuntu и других Linux-серверах:
version: "3.8"
services:
postgres:
image: postgres:15-alpine
restart: always
environment:
POSTGRES_DB: n8n
POSTGRES_USER: n8n
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- pg_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U n8n"]
interval: 10s
retries: 5
redis:
image: redis:7-alpine
restart: always
volumes:
- redis_data:/data
n8n:
image: n8nio/n8n:latest
restart: always
ports:
- "5678:5678"
environment:
DB_TYPE: postgresdb
DB_POSTGRESDB_HOST: postgres
DB_POSTGRESDB_DATABASE: n8n
DB_POSTGRESDB_USER: n8n
DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
QUEUE_BULL_REDIS_HOST: redis
N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
WEBHOOK_URL: https://${DOMAIN}/
GENERIC_TIMEZONE: Europe/Moscow
volumes:
- n8n_data:/home/node/.n8n
depends_on:
postgres:
condition: service_healthy
volumes:
pg_data:
redis_data:
n8n_data:
Запустить этот стек: создайте .env с нужными переменными, затем docker compose up -d.
Установка Docker Compose на Ubuntu и Linux
Установить Docker Compose на Ubuntu проще всего через официальный репозиторий Docker. Начиная с версии 20.10, плагин входит в пакет Docker Engine.
# Удалить старый docker-compose (standalone)
sudo apt remove docker-compose
# Установить актуальный Docker Engine с плагином Compose
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# Проверить версию
docker compose version
# Docker Compose version v2.x.x
Docker compose Ubuntu: установка через официальный репозиторий — самый надёжный способ. Ubuntu install docker compose через пакет docker-compose-plugin гарантирует совместимость с Docker Engine. Установка Docker Compose Ubuntu через пакетный менеджер также проще поддерживать при обновлениях — достаточно sudo apt upgrade.
Docker compose Linux на Debian, CentOS и других дистрибутивах устанавливается аналогично — меняется только пакетный менеджер. Для docker compose install через скрипт Docker используйте:
curl -fsSL https://get.docker.com | sh
docker compose version # должна появиться версия v2+
Типичные ошибки и их решения
«Port is already in use»
Порт занят другим процессом. Найдите его: sudo lsof -i :5678 и завершите, либо измените порт в Compose-файле.
«Container exited with code 1»
Смотрите логи: docker compose logs имя_сервиса. Чаще всего — ошибка в переменных окружения или недоступна зависимость.
Изменения в docker-compose.yml не применяются
После изменения файла нужно пересоздать контейнеры: docker compose up -d --force-recreate. Для пересборки образа добавьте --build.
FAQ
В чём разница между docker-compose и docker compose?
docker-compose (с дефисом) — старый standalone-инструмент на Python. docker compose (без дефиса) — новый плагин Go, встроенный в Docker CLI с версии 20.10. Используйте новый плагин.
Можно ли использовать docker compose без root?
Да, если пользователь добавлен в группу docker: sudo usermod -aG docker $USER. После этого перезайдите в систему.
Как обновить образы?
docker compose pull # скачать новые версии образов
docker compose up -d # пересоздать контейнеры
Где хранятся данные volumes?
По умолчанию в /var/lib/docker/volumes/имя_проекта_имя_volume/. Список всех volumes: docker volume ls.
Docker Compose — основа для self-hosted автоматизации. Если вы хотите поднять n8n на своём сервере, начните с базовой статьи о том, что такое n8n, а затем используйте этот гайд для production-запуска через Compose. Следующий шаг — полная установка n8n на Ubuntu с SSL и автозапуском.