Перейти к основному содержимому

Docker Compose And Local Development

Цели​

  • Run each service independently with api, migrator, and background.
  • Run shared infrastructure once.
  • Support Windows .bat scripts with explicit compose project names.
  • Validate required environment and container health.

Infrastructure Compose​

deploy/infrastructure/docker-compose.yml should include:

  • PostgreSQL
  • Kafka / Redpanda-compatible local broker
  • Redis
  • Elasticsearch
  • Elasticsearch Dashboards optional
  • ClickHouse
  • MinIO
  • OTEL Collector
  • Prometheus
  • Grafana
  • Sentry-compatible local stack optional
  • Mail/SMS mock providers

Service Compose​

Each service has:

src/services/<service-name>/
  docker-compose.yml
  run-<service-name>-stack.bat
  .env.example

Services in compose:

  • <service>-api
  • <service>-migrator
  • <service>-background

The migrator starts first and exits after migrations. API/background depend on successful migration and infrastructure health.

Windows BAT Launcher Requirements​

Every launcher should:

  1. Set explicit project name: Pin-<service>.
  2. Check Docker is available.
  3. Check .env exists or print copy instruction from .env.example.
  4. Validate required environment keys.
  5. Run docker compose -p Pin-<service> build --parallel.
  6. Run docker compose -p Pin-<service> up.
  7. After startup, assert health endpoints where possible.

Example intent:

docker compose -p Pin-accounting build --parallel
docker compose -p Pin-accounting up

Environment​

Secrets must not be committed. .env.example contains names only:

  • POSTGRES_CONNECTION_STRING
  • KAFKA_BOOTSTRAP_SERVERS
  • REDIS_CONNECTION_STRING
  • ELASTICSEARCH_URL
  • CLICKHOUSE_CONNECTION_STRING
  • S3_ENDPOINT
  • JWT_ISSUER
  • JWT_AUDIENCE
  • provider-specific secret references.

Migrations​

  • PostgreSQL migrations through EF Core migrator projects.
  • ClickHouse migrations through SQL scripts executed by analytics migrator.
  • Elasticsearch index migrations through versioned index creation and aliases.
  • Migrators must be idempotent and safe to rerun.

Local URLs​

Reserve port ranges:

  • Gateway: 7000-7099
  • Backend services: 7100-7399
  • Frontends: 3000-3099
  • Infrastructure UIs: 9000-9099

Exact ports should be documented in each service README when scaffolded.