Docker Compose: кілька сервісів разом

Docker Compose: кілька сервісів разом

У першій статті серії ми навчились запускати один контейнер командою docker run. Реальний застосунок рідко живе сам: до нього додається база даних, кеш, а часто ще й черга повідомлень. Три сервіси — це вже три окремі команди docker run, у кожній до десятка прапорів, плюс мережа, яку треба створити вручну заздалегідь: docker network create app-net. Порядок запуску при цьому важливий, але нічим не гарантований.

Проблема стає особливо відчутною після перезавантаження сервера. Контейнери з restart: unless-stopped піднімаються самі, але Docker не знає, який сервіс має стартувати першим. Якщо застосунок піднявся раніше за базу даних, перший же запит впаде з ECONNREFUSED — і доведеться вручну перезапускати застосунок, коли база вже готова.

Docker Compose вирішує це, змінюючи сам спосіб мислення. Замість послідовності команд ви описуєте бажаний стан у файлі docker-compose.yml: які сервіси мають існувати, як вони пов'язані, що від чого залежить. Порядок запуску, мережі та volumes Compose бере на себе.

Один технічний момент варто зняти одразу. Сучасна команда — docker compose (два слова, плагін на Go, вбудований у Docker Engine з версії 20.10+). Стара docker-compose (через дефіс, окрема утиліта на Python, гілка v1) офіційно зняли з підтримки у травні 2023. Перевірити, яка версія стоїть:

docker compose version

Очікуваний вивід — щось на кшталт Docker Compose version v2.x.x. Якщо команда не знайдена, плагін ставиться окремо: apt install docker-compose-plugin.

2. Структура docker-compose.yml

2.1 Про рядок version:

У більшості старих туторіалів файл починається з version: "3.8". У Compose v2 цей рядок ігнорується з попередженням про застарілість — його можна сміливо прибирати, файл стає коротшим і без зайвого шуму в логах.

2.2 services: — ключ, ім'я і DNS одночасно

Назва кожного сервісу під ключем services: виконує подвійну роль: за замовчуванням з неї складається ім'я контейнера (<проєкт>-<сервіс>-1), і водночас це DNS-ім'я, за яким сервіс видно іншим контейнерам у тій самій мережі. Якщо задати container_name: my-app явно, ім'я стане передбачуваним, але тоді сервіс не можна масштабувати командою docker compose up --scale app=3 — Compose не зможе створити кілька контейнерів з однаковим фіксованим ім'ям.

2.3 image: чи build:

image: postgres:16-alpine завантажує готовий образ з реєстру. build: . збирає образ з Dockerfile у поточній директорії. Якщо Dockerfile лежить не в корені проєкту, вказується явно:

build:
  context: ./app
  dockerfile: Dockerfile.prod

2.4 environment: — два формати запису

Змінні середовища можна писати як map (DATABASE_URL: postgres://...) або як список (- DATABASE_URL=postgres://...). Формат map читається легше при великій кількості змінних. Вираз ${VAR} у будь-якому з форматів підставляється зі значення в .env-файлі чи з shell-оточення в момент запуску Compose.

2.5 ports: — тільки те, що дійсно потрібно ззовні

Формат "3000:3000" означає порт хоста : порт контейнера. Без секції ports: сервіс лишається недоступним ззовні, але доступним іншим сервісам у тій самій мережі Compose. Для бази даних у production ports:, як правило, не потрібен і небажаний — відкривати порт СУБД в інтернет без крайньої необхідності не варто.

2.6 volumes: у сервісі

Коротка форма — pgdata:/var/lib/postgresql/data. Довга форма дозволяє явно вказати тип — type: volume для named volume або type: bind для bind mount. Named volume, використаний у сервісі, має відповідний блок на верхньому рівні файлу: volumes: pgdata: — саме тут Compose бере на себе керування його життєвим циклом.

2.7 networks: — своя мережа за замовчуванням

Без явного оголошення Compose створює мережу з ім'ям <проєкт>_default і підключає до неї всі сервіси. Кастомна мережа задається так: у сервісі — networks: [app-net], і внизу файлу — networks: app-net: (порожній блок означає bridge-мережу з налаштуваннями за замовчуванням).

2.8 restart: — чотири варіанти

Для production за замовчуванням варто обирати unless-stopped: сервіс переживе перезавантаження хоста, але не буде намагатись піднятись знову, якщо ви зупинили його свідомо.

2.9 command: і entrypoint:

Обидві директиви перевизначають те, що задано в Dockerfile через CMD чи ENTRYPOINT. Типове застосування — окремий dev-режим: command: npm run dev замість production-команди запуску, без потреби тримати два різні Dockerfile.

3. Реальний стек: Node.js + PostgreSQL + Redis

Зведемо все в один робочий приклад — застосунок на Node.js, база даних PostgreSQL і кеш Redis:

services:
  app:
    build: .
    ports: ["3000:3000"]
    env_file: .env
    environment:
      DATABASE_URL: postgres://user:${DB_PASSWORD}@db:5432/mydb
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    networks: [app-net]
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: mydb
    volumes: [pgdata:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
      interval: 5s
      timeout: 5s
      retries: 10
    networks: [app-net]
    restart: unless-stopped

  cache:
    image: redis:7-alpine
    command: redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru
    networks: [app-net]
    restart: unless-stopped

volumes:
  pgdata:

networks:
  app-net:

3.1 Змінні POSTGRES_*

Офіційний образ postgres зчитує POSTGRES_USER, POSTGRES_PASSWORD і POSTGRES_DB лише один раз — при першій ініціалізації кластера на порожньому volume. При наступних запусках, коли volume вже існує, ці змінні ігноруються. Змінити пароль пізніше зміною змінної не вийде — доведеться виконати ALTER USER всередині вже працюючої бази.

3.2 depends_on з умовою service_healthy

Секція depends_on: db: condition: service_healthy означає, що app не почне стартувати, доки healthcheck бази не поверне успіх. Простий запис depends_on: [db], без умови, чекає лише на старт самого процесу контейнера — а PostgreSQL у цей момент ще може ініціалізувати кластер і не приймати з'єднання. Саме це і призводить до ECONNREFUSED при першому запиті після старту стека.

3.3 Чому retries: 10, а не 5

При interval: 5s і retries: 10 Compose готовий чекати на healthy-стан бази до 50 секунд сумарно. Це не з запасом: перша ініціалізація кластера PostgreSQL сама по собі може займати 10-20 секунд, і при retries: 5 (25 секунд) Compose може позначити базу як unhealthy ще до того, як вона реально піднялась.

3.4 redis:7-alpine і ліміт пам'яті

Тег redis:latest означає, що вміст образу може змінитись у будь-який момент; redis:7-alpine фіксує мажорну версію і важить приблизно 40 MB. Прапор --maxmemory 128mb у command: критично важливий у продакшні: без явного ліміту Redis за замовчуванням намагається використати всю доступну пам'ять хоста, і при активному кешуванні це може призвести до OOM-вбивства сусідніх контейнерів.

3.5 Як сервіси знаходять один одного за іменем

Рядок @db:5432 у DATABASE_URL працює завдяки вбудованому DNS Compose: ім'я сервісу db резолвиться у внутрішню IP-адресу відповідного контейнера. Це працює тільки для сервісів, які перебувають в одній секції networks:, і не працює з хоста — з термінала сервера ім'я db нічого не означає.

4. .env — змінні та секрети

4.1 Автоматичне підхоплення

Файл .env у тій самій директорії, що й docker-compose.yml, підхоплюється Compose автоматично, без додаткових налаштувань:

DB_PASSWORD=supersecret123
NODE_ENV=production

4.2 Два різних механізми — не плутати

Тут легко наплутати два схожі, але різні шляхи потрапляння значень у контейнер:

• ${DB_PASSWORD} у самому compose-файлі — підстановка відбувається під час парсингу YAML самим Compose; значення потрапляє в конфігурацію, але не автоматично в змінні середовища контейнера.
• env_file: .env у секції сервісу — файл цілком передається всередину контейнера як змінні середовища, доступні застосунку через, наприклад, process.env.DB_PASSWORD.

4.3 Перевірка підстановки

docker compose config

Ця команда виводить фінальний compose-файл уже після підстановки всіх ${VAR} — зручний спосіб переконатись, що значення з .env дійсно підхопились, ще до запуску стека.

4.4 Пріоритет джерел значень

Від вищого пріоритету до нижчого: змінна shell-оточення → значення з файлу .env → дефолт у самому виразі, якщо він заданий як ${VAR:-default}.

4.5 .gitignore

Файл .env обов'язково додається в .gitignore. Розумний шаблон — *.env і .env*, щоб заодно виключити .env.local і .env.production, які часто заводять пізніше.

4.6 .dockerignore теж

.env так само має бути в .dockerignore — інакше COPY . . у Dockerfile скопіює секрети прямо всередину образу. Перевірити це легко:

docker run --rm my-app cat /app/.env

Якщо команда виводить вміст файлу — секрет уже "запечений" в образ, і проблему не вирішити видаленням файлу з наступного коміту: попередній шар образу все одно його містить.

4.7 Права доступу до файлу

chmod 600 .env обмежує читання файлу тільки власником — для одного VPS цього достатньо. Для сценаріїв складніших за один сервер (Swarm, кілька команд з різним рівнем довіри) варто дивитись у бік Docker Secrets або HashiCorp Vault.

5. Мережі: як сервіси знаходять один одного

5.1 Ізоляція за проєктами

Кожен Compose-проєкт — це, як правило, окрема директорія — отримує власну ізольовану мережу. Сервіс app з одного проєкту не бачить db іншого проєкту, навіть якщо обидва запущені на тому самому хості.

5.2 Ім'я проєкту

За замовчуванням ім'я проєкту береться з назви директорії. Його можна задати явно прапором docker compose -p myproject up або рядком name: myproject на верхньому рівні compose-файлу — це впливає на імена контейнерів і мереж, а отже і на те, чи "побачать" один одного два стеки.

5.3 Мінімум відкритих портів

Правило просте: ports: прописується тільки тим сервісам, яким дійсно потрібен доступ ззовні. У прикладі вище це app (3000:3000); db і cache такого блоку не мають. Зайвий рядок "5432:5432" у секції бази даних відкриває PostgreSQL для всього інтернету — це одна з найчастіших причин компрометації бази на VPS.

5.4 Спілкування між різними стеками

Якщо два незалежні Compose-проєкти мають взаємодіяти — наприклад, окремий стек моніторингу, який повинен бачити метрики застосунку, — використовується підключення до вже існуючої мережі:

networks:
  monitoring-net:
    external: true

6. Ключові команди

7. Висновок

Тепер весь стек — застосунок, база даних, кеш — описаний в одному файлі. git clone плюс docker compose up -d відтворюють ідентичне середовище на будь-якому сервері з Docker за одну-дві хвилини, без жодного ручного кроку і без питання "у якому порядку це запускати".

Лишається кілька речей, які docker-compose.yml сам по собі не вирішує. HTTPS і SSL-сертифікати — стеку потрібен reverse proxy на кшталт Nginx чи Traefik перед ним. Кілька доменів на одній IP-адресі теж вирішується на рівні proxy, а не Compose. Ліміти ресурсів (mem_limit: 512m, cpus: "0.5") поки що відсутні — а без них один сервіс, що вийшов з-під контролю, здатен забрати всю пам'ять сервера в інших. І логи поки що доступні лише через docker compose logs, без ротації і без збереження після видалення контейнера.

Саме ці прогалини — тема наступної статті: перед стеком стає Nginx або Traefik, з'являється сертифікат Let's Encrypt, а автозапуск переходить з ручного docker compose up -d на systemd-юніт, який піднімає стек після перезавантаження сервера сам, без участі людини.

Часті запитання