Технології та Інфраструктура → Docker Compose і Dev-оточення

Docker Compose і Dev-оточення

1) Навіщо Compose

• Паритет з продом (образи, змінні, мережі) → менше «працює у мене».
• Швидкий старт для новачків →'make up'і в бій.
• Ізольовані стенди на розробника/гілку → паралельна робота без конфліктів.
• Інтеграційні тести на реальних залежностях.

2) Базова структура репозиторію

project/
docker/
app/      # Dockerfile, скрипты web/      # Nginx/Traefik конфиги seed/      # сидеры/фикстуры compose.yaml       # общий базовый стек compose.override.yaml   # локальные оверрайды (в.gitignore)
compose.ci.yaml      # для CI
.env.example       # шаблон окружения
Makefile         # удобные цели devcontainer.json     # VS Code Dev Containers (опционально)

• compose. yaml - описує «скелет» (сервіси, мережі, томи) однаковий для dev/CI.
• override - тільки локальні правки: маппінги каталогів, порти, debug-прапори.
• .env. example → розробник копіює в'.env'і підставляє значення.

3) Каркас compose. yaml (приклад)

yaml name: project services:
gateway:
image: traefik:v3 command:
- "--providers.docker=true"
- "--entrypoints.web.address=:80"
- "--entrypoints.websecure.address=:443"
- "--certificatesresolvers.dev.acme.tlschallenge=true"
ports: ["80:80", "443:443"]
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro networks: [edge, core]

api:
build:
context:.
dockerfile: docker/app/Dockerfile target: dev env_file: [.env]
command:./scripts/dev-start.sh volumes:
-./:/app:cached depends_on: [db, redis, kafka]
labels:
- "traefik.http.routers.api.rule=Host(`${API_HOST}`)"
- "traefik.http.services.api.loadbalancer.server.port=8080"
networks: [core]

db:
image: postgres:16 environment:
POSTGRES_USER: ${DB_USER}
POSTGRES_PASSWORD: ${DB_PASS}
POSTGRES_DB: ${DB_NAME}
volumes:
- pgdata:/var/lib/postgresql/data healthcheck: {test: ["CMD-SHELL","pg_isready -U $$POSTGRES_USER"], interval: 5s, timeout: 3s, retries: 20}
networks: [core]

redis:
image: redis:7 command: ["redis-server","--appendonly","yes"]
volumes: [ "redisdata:/data" ]
networks: [core]

kafka:
image: bitnami/kafka:3 environment:
KAFKA_ENABLE_KRAFT: "yes"
KAFKA_CFG_PROCESS_ROLES: "controller,broker"
KAFKA_CFG_NODE_ID: 1
KAFKA_CFG_LISTENERS: PLAINTEXT://:9092
KAFKA_CFG_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092 networks: [core]

mailhog:
image: mailhog/mailhog ports: ["8025:8025"]
networks: [core]

mock-psp:
image: wiremock/wiremock:3 command: ["--verbose","--global-response-templating"]
volumes: ["./docker/mocks/psp:/home/wiremock"]
labels:
- "traefik.http.routers.mockpsp.rule=Host(`${PSP_HOST}`)"
networks: [core]

volumes:
pgdata: {}
redisdata: {}

networks:
edge: {}
core: {}

• Traefik/NGINX как gateway: наближає схему роутингу до продовой.
• Healthcheck и depends_on с `condition: service_healthy' (у v3 через waiting-скрипти) - впорядкований старт.
• Volumes для персистентності (БД/кеш) і bind-mount для коду (hot-reload).

4) Профілі та декілька файлів

Profiles (`profiles: [dev, ci, extras]') включають/виключають сервіси ('docker compose --profile extras up -d').

• `docker compose -f compose. yaml -f compose. dev. yaml up'- зливання конфігурацій.

• `compose. yaml'- базовий.
• `compose. dev. yaml'- bind-mountи, дебаг, фічефлаги.
• `compose. extras. yaml'- інструментальні (Grafana, pgAdmin, Kafdrop).
• `compose. ci. yaml'- «голова без графіки», без bind-mountів.

5) Змінні, секрети та налаштування

.env - загальне джерело змінних: хости, креди тестових БД, прапори.

• локальні dummy-секрети (ключі заглушки),
• інтеграцію зі skinny-Vault/SOPS для особливо чутливого.
• Принцип: мінімально необхідні дані. PAN/PII - токени/фікстури.

6) Збірки і швидкість

6. 1 Multi-stage + BuildKit

Dockerfile з цілями'base','dev','prod'; загальний cache-layer для залежностей.
Увімкнути BuildKit: 'DOCKER _ BUILDKIT = 1'( або в конфігу).
Кешування: `--mount=type=cache,target=/root/.cache/...` для pip/npm/maven.

6. 2 Швидкий цикл

Bind-mount кода + hot-reload (nodemon, uvicorn --reload, Spring Devtools).
Окремий таргет dev зі складанням тільки потрібного.
Makefile цілі: `make up`, `make down`, `make logs`, `make rebuild`, `make seed`.

make
ENV?= dev up:
docker compose --profile $(ENV) up -d down:
docker compose down -v logs:
docker compose logs -f --tail=200 rebuild:
DOCKER_BUILDKIT=1 docker compose build --pull --no-cache api seed:
docker compose run --rm api./scripts/seed.sh migrate:
docker compose run --rm api./scripts/migrate.sh test:
docker compose -f compose.yaml -f compose.ci.yaml run --rm api./scripts/test.sh

7) БД, міграції, сідінг

Міграції (Flyway/Liquibase/Alembic/Prisma) запускаються хук-скриптом після старту'db'( очікування healthcheck).
Сідінг: окремий контейнер «seed» з фікстурами; повторюваний і ідемпотентний.
Снапшоти даних: том'pgdata'можна скидати/відновлювати скриптом'reset-db. sh`.

8) Брокери, кеші, CDC

Kafka/Rabbit/Redpanda - як в проді (мінімальні конфіги).
Redis з AOF включеним для реалістики.
CDC-конектори (опціонально): Debezium в окремому сервісі для інтеграційних тестів аналітики.

9) Моки зовнішніх постачальників

WireMock/Prism для REST, MockServer для складних сценаріїв.
Mailhog/SMTP4Dev для листів.
Localstack/MinIO для хмарних сторів і S3-сумісності.
Політика: всі зовнішні PSP/KYC/KMS - через мок-хаб за контрактами (OpenAPI), а не «в інтернет».

10) Зворотний проксі і TLS

• `api. local. test`, `mockpsp. local. test`.
• TLS: mkcert для видачі довіреного локального сертифіката, щоб тестувати HSTS/secure-cookies.
• Sticky-сесії включайте тільки для кейсів, де це правда важливо.

11) Профілі розробника: Node/Python/Java

Node: mount'node _ modules'як кеш (volume), щоб прискорити install;'CHOKIDAR _ USEPOLLING = 1'на Windows/WSL.
Python: `pip cache` как volume, `watchfiles`/`uvicorn --reload`.
Java: JRebel/Devtools,'mvn -T 1C -o'+ шар з залежностями.

12) Тести та якість

Інтеграційні тести ганяємо всередині мережі Compose: `docker compose run test`.
Testcontainers (для JVM/Node/Python/.NET) - хороший варіант для unit-інтеграції без повного стека.
Контракт-тести з мок-хабом → gate в CI.
Лінтери/Pre-commit: запускати в контейнері для повторюваності.

13) Devcontainers і «IDE-як-код»

`devcontainer. json'фіксує образ розраба (CLI, SDK, linters), монтує проект, проганяє'postCreateCommand'.
Профіт: однакові інструменти, не «засмічуємо» хост, нова машина - готова за хвилини.

14) Безпека в dev

Без root в образах додатків;'readOnlyRootFilesystem'коли можливо.
Ніяких бойових ключів/секретів, навіть тимчасово.
Логи - без PII/PAN; маскування на рівні форматтера.
Сегрегація портів і мереж: зовнішній доступ тільки через gateway.

15) FinOps/продуктивність в локалі

Обмежте ресурси: `deploy. resources. limits'( Compose читає частково, але допомагає дисципліні).
Зменшуйте фан-аут (менше сервісів за замовчуванням; extras - профілі).
Кеш BuildKit і volume-кеші для менеджерів пакетів.

16) CI с Compose

Використовуйте «compose». yaml` + `compose. ci. yaml'без bind-mountів.
Кеші залежностей - як attachable volumes між джобами/шарами.
Паралельні джоби: `name:'в Compose різний (або префікс по гілці), щоб стенди не конфліктували.

17) Траблшутінг

'docker compose ps '/' logs -f '/' exec'- базова діагностика.
Перевіряйте DNS в мережі Compose (сервіс по імені).
Якщо bind-mount «гальмує» на macOS/Windows -':cached`/`:delegated` или Mutagen/virtiofs.
Healthcheck «зелений», але сервіс «мертвий»: перевірте'readiness'вашої апки і порядок міграцій.

18) Чек-лист впровадження

1. Базовий стек (gateway, api, db, cache, queue) в compose. yaml.
2. Локальні правки - в override (в.gitignore).
3..env. example повний і актуальний;'make bootstrap'копіює його в'.env'.
4. Healthchecks і скрипт очікування БД/міграцій.
5. WireMock/Localstack/MinIO для зовнішніх провайдерів.
6. Сідінг і міграції як командлети'make seed/migrate'.
7. BuildKit + multi-stage, кеші залежностей.
8. Devcontainers/Makefile для швидкого старту.
9. Профілі'extras'для інструментів (Grafana/pgAdmin/Kafdrop).
10. CI використовує той же compose (+ ci-оверрайд).

19) Анти-патерни

«Монстр-compose» на 40 сервісів, завжди запущений: вмикайте профілі.
Жорстко прибиті порти, що конфліктують між розробниками.
Секрети/ключі в Git або'.env. example`.
Залежність від «інтернету» для тестів (реальні PSP/KYC).
Відсутність healthcheck/очікування - гонки міграцій і стартів.
Відсутність сидінгу → flaky інтеграційні тести.

20) Підсумок

Compose - це двигун розробної швидкості: один файл описує ваш світ сервісів, а профілі/оверрайди дають гнучкість. Підтримуйте паритет з продом, автоматизуйте сидинг і міграції, тримайте моки і TLS «як в бою», прискорюйте збірки BuildKit'ом - і у вас вийде локальне середовище, в якому зручно працювати, легко тестувати і безпечно відтворювати продові сценарії iGaming/фінтех