Расширенный справочник по docker-compose.yml

Этот документ описывает ключевые элементы и опции, доступные в YAML-файле docker-compose.yml, начиная с версии 3.8 и выше. Используется в многоконтейнерных приложениях для управления инфраструктурой.

---

🧩 Основная структура docker-compose.yml

version: "3.9"  # или 3.8, 3.7 и т.д.

services:
  сервис:
    image: имя_образа:тег
    build: путь_к_папке_или_объект_с_настройками
    ports: ["хост:контейнер"]
    volumes: ["источник:назначение"]
    environment:
      - ПЕРЕМЕННАЯ=значение
    command: "команда_заменяющая_CMD"
    depends_on:
      - другой_сервис
    networks:
      - имя_сети

volumes:
  имя_тома:
    external: true  # опционально

networks:
  имя_сети:
    external: true  # опционально

---

🧱 services (Сервисы)

Описывает контейнеры, которые нужно запустить.

image

Указывает, какой Docker-образ использовать:

image: postgres:15-alpine

build

Если образ нужно собрать из Dockerfile:

build:
  context: ./app
  dockerfile: CustomDockerfile  # не обязательно

ports

Проброс портов между хостом и контейнером:

ports:
  - "8080:80"

volumes

Подключение директорий или томов:

volumes:
  - ./html:/usr/share/nginx/html
  - db-data:/var/lib/postgresql/data

environment

Передача переменных окружения:

environment:
  POSTGRES_DB: mydb
  POSTGRES_USER: user
  POSTGRES_PASSWORD: pass

command

Переопределяет CMD из Dockerfile:

command: python main.py

depends_on

Определяет порядок запуска:

depends_on:
  - db

⚠️ Не ждёт готовности сервиса, только запуска.

networks

Подключение сервиса к сети:

networks:
  - webnet

---

📦 volumes (Тома)

Определение именованных томов:

volumes:
  db-data:

Или использование внешнего уже созданного тома:

volumes:
  db-data:
    external: true

---

🌐 networks (Сети)

Определение пользовательской сети:

networks:
  webnet:

Использование внешней сети:

networks:
  webnet:
    external: true

Если ничего не указать — будет создана сеть project_default автоматически.

---

🔁 restart (Политика перезапуска)

restart: always         # всегда перезапускать
restart: on-failure     # только при ошибке
restart: unless-stopped # пока не остановлен вручную

---

🌍 Работа с переменными окружения (environment)

Docker Compose поддерживает несколько способов задания переменных окружения:

1. Встроенный блок environment внутри сервиса

services:
  app:
    environment:
      - ENV=production
      - DEBUG=false

Или в виде объекта:

services:
  db:
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: secret

2. Использование .env файла (автоматически подгружается)

Создай рядом с docker-compose.yml файл .env:

POSTGRES_DB=mydb
POSTGRES_USER=user
POSTGRES_PASSWORD=secret

В docker-compose.yml можно писать переменные вот так:

environment:
  - POSTGRES_DB=${POSTGRES_DB}
  - POSTGRES_USER=${POSTGRES_USER}

Также можно указать .env файл явно:

docker compose --env-file custom.env up

3. Передача переменных из текущего shell

export DEBUG=true
export ENV=production
docker compose up

💡 Распространённые переменные окружения

• NODE_ENV=production — для Node.js
• DJANGO_SETTINGS_MODULE=config.production — для Django
• SPRING_PROFILES_ACTIVE=prod — для Spring Boot
• RAILS_ENV=production — для Rails
• POSTGRES_USER, MYSQL_ROOT_PASSWORD — для БД

🧪 Типичные сценарии

🔐 Передача секретов:

environment:
  - JWT_SECRET=${JWT_SECRET}
  - API_KEY=${API_KEY}

🌐 Подключение к БД:

environment:
  - DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/mydb

🧪 Установка режима окружения:

environment:
  - ENV=development
  - DEBUG=true

📦 Смена конфигурации без пересборки образа: - Меняешь .env, перезапускаешь docker compose up -d.

---

🧪 Пример полноценного docker-compose.yml

version: "3.9"

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html
    networks:
      - webnet

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: mydatabase
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - webnet

  app:
    build:
      context: ./app
    ports:
      - "5000:5000"
    environment:
      - ENV=production
      - API_KEY=${API_KEY}
    depends_on:
      - db
    networks:
      - webnet
    restart: unless-stopped

volumes:
  db-data:

networks:
  webnet:

---

📌 Рекомендуется использовать version: "3.9" (или выше) для актуального синтаксиса.

🧠 Помни, что Docker Compose создаёт тома и сети автоматически, если они не external.