integration-local-stack

Purpose / Boundary

이 repo는 clever-msa-platform의 로컬 통합 실행 셸이다.

현재 배송원 -> 배차 -> 정산 로컬 검증의 절차, smoke, 장애 대응 정본은 ../../docs/runbooks/local-dispatch-settlement-stack.md 이다.

Runtime Contract / Local Role

현재 역할:

여러 독립 service/front/gateway repo를 로컬에서 한 번에 띄우는 compose 진입점
.env.example, seed orchestration, smoke 실행 기준 제공

현재 source 연결 상태:

현재 compose는 sibling target repo만 build context로 참조한다
active runtime source는 모두 ../ 아래의 target repo들에 있다
MSA-Server는 더 이상 runtime build context가 아니다
service-terminal-registry는 active runtime repo로 compose에 편입됐다
service-dispatch-registry는 active runtime repo로 compose에 편입됐다
service-dispatch-operations-view는 active runtime repo로 compose에 편입됐다
service-driver-operations-view는 driver ops read runtime으로 compose에 편입됐다
service-settlement-payroll는 settlement write owner runtime으로 compose에 편입됐다
service-settlement-operations-view는 settlement read fan-out runtime으로 compose에 편입됐다
service-telemetry-hub는 active runtime repo로 compose에 편입됐다
service-telemetry-listener는 active runtime repo로 compose에 편입됐다
service-telemetry-dead-letter는 active runtime repo로 compose에 편입됐다
mqtt-broker는 local-only deterministic telemetry ingress source로 compose에 편입됐다

포함:

docker-compose.account-driver-settlement.yml
docker-compose.dev-infra.yml
docker-compose.dev-gateway.yml
infra/env/local/
infra/env/host/
infra/env/deploy/
infra/mqtt/
infra/docker/seed-runner/
scripts/
compose/README.md
이후 local smoke/bootstrap 스크립트

포함하지 않음:

도메인 모델 정본
서비스 내부 비즈니스 로직
gateway 서비스 소스
front 서비스 소스

Image Build / Deploy Contract

이 repo는 deployable app image의 build owner가 아니다.
deployable service image는 각 child repo의 build workflow가 생산한다.
이 repo는 local compose, env template, seed, smoke, host-hybrid helper를 소유한다.

Environment Files And Safety Notes

Env Template Rule

로컬 통합 검증용 compose와 seed-runner는 infra/env/local/ 템플릿만 사용한다.
배포 runtime compose는 infra/env/deploy/ 템플릿만 사용한다.
로컬 편의 설정과 deploy runtime 설정을 같은 env 파일에서 관리하지 않는다.

Frontend Local Development Rule

프런트 수정 중에는 web-console 이미지를 수정마다 다시 빌드하지 않는다.

표준 루프는 아래다.

backend와 gateway는 compose로 한 번 띄운다.
frontend는 child repo에서 host dev server로 띄운다.
UI 수정 확인은 http://localhost:5174에서 한다.
gateway/auth/API 포함 통합 확인은 http://localhost:8080에서 한다.
docker compose ... up -d --build web-console는 최종 통합 확인 시점에만 실행한다.

현재 기준 역할 분리:

http://localhost:5174는 host Vite dev server다.
http://localhost:8080은 gateway 뒤의 built frontend container다.
8080용 web-console 이미지는 정적 빌드 결과만 서빙하며, container 안에서 npm run dev를 띄우지 않는다.
5174에서 Request failed.가 뜨면 프런트 자체보다 /api 프록시 대상인 8080과 backend 상태를 먼저 본다.

권장 명령:

cd /Users/jiin/Documents/Files/02_EVnSolution/00_Source_code/CLEVER/clever-msa-platform/development/integration-local-stack
docker compose -f docker-compose.account-driver-settlement.yml up -d gateway

cd /Users/jiin/Documents/Files/02_EVnSolution/00_Source_code/CLEVER/clever-msa-platform/development/front-web-console
npm run dev

이 규칙의 목적은 frontend edit loop에서 Docker Desktop rebuild latency를 제거하고, 최종 통합 검증만 Docker image 기준으로 남기는 것이다.

Local Run / Verification

Current Dev/Test/Deploy Flow

현재 권장 흐름은 아래처럼 나눈다.

1. 개발

backend/gateway는 필요 수준으로만 compose 또는 host hybrid로 띄운다.
frontend 수정은 front-web-console child repo에서 npm run dev로 진행한다.
UI iteration은 http://localhost:5174만 본다.

2. 통합 테스트

full stack는 raw docker compose up -d보다 staged runner를 우선 사용한다.
staged runner는 중앙 배포 wave와 비슷한 stage 순서로 로컬 stack를 올린다.
권장 명령:

cd /Users/jiin/Documents/Files/02_EVnSolution/00_Source_code/CLEVER/clever-msa-platform/development/integration-local-stack
python3 ./scripts/run_local_startup.py --fresh

stage 순서:
- infra
- wave-2-core
- wave-3-domain
- wave-4-integration
- wave-5-views
- edge
- seed
- smoke
최종 확인 시점에만 web-console 이미지를 다시 빌드한다.
docker compose -f docker-compose.account-driver-settlement.yml build web-console gateway
docker compose -f docker-compose.account-driver-settlement.yml up -d
이때 http://localhost:8080은 built frontend + gateway + backend 기준 화면이다.

3. 배포

front-web-console repo에서 image를 만든다.
실제 rollout은 service repo에서 직접 하지 않고 중앙 배포 repo에서 release bundle 기준으로 수행한다.
관련 운영 기준은 ../../docs/superpowers/specs/2026-04-09-image-deploy-operating-policy-design.md를 따른다.

Key Tests Or Verification Commands

staged local bring-up: python3 ./scripts/run_local_startup.py --fresh
infra-only local mode: ./scripts/up_dev_infra.sh
dev gateway: ./scripts/up_dev_gateway.sh
API docs refresh: python3 ./scripts/refresh_api_docs.py
dead-letter route smoke: python3 ./scripts/verify_dead_letter_gateway_routes.py

Low CPU Hybrid Development

Docker Desktop이 무거운 환경에서는 full compose를 상시 띄우지 않는다.

권장 기준:

Docker Desktop 리소스는 2 CPU / 2 GiB RAM으로 낮춘다.
Docker AI는 끈다.
평소에는 docker-compose.dev-infra.yml로 DB/redis만 띄운다.
backend는 필요한 repo만 host에서 실행한다.
frontend는 계속 http://localhost:5174에서 확인한다.
http://localhost:8080 full integration은 최종 확인 시점에만 쓴다.

infra-only 실행:

cd /Users/jiin/Documents/Files/02_EVnSolution/00_Source_code/CLEVER/clever-msa-platform/development/integration-local-stack
docker compose -f docker-compose.dev-infra.yml up -d

또는:

./scripts/up_dev_infra.sh

infra-only 정지:

cd /Users/jiin/Documents/Files/02_EVnSolution/00_Source_code/CLEVER/clever-msa-platform/development/integration-local-stack
docker compose -f docker-compose.dev-infra.yml down

또는:

./scripts/down_dev_infra.sh

현재 docker-compose.dev-infra.yml는 dispatch + settlement slice 기준으로 아래만 띄운다.

redis
account-db
driver-db
settlement-db
settlement-registry-db
delivery-record-db
org-db
vehicle-db
dispatch-registry-db

host 연결용 포트:

redis: 127.0.0.1:16379
account-db: 127.0.0.1:15431
driver-db: 127.0.0.1:15432
settlement-db: 127.0.0.1:15433
settlement-registry-db: 127.0.0.1:15434
delivery-record-db: 127.0.0.1:15435
org-db: 127.0.0.1:15436
vehicle-db: 127.0.0.1:15437
dispatch-registry-db: 127.0.0.1:15438

host에서 Django 서비스를 띄울 때는 기존 infra/env/local/*.env.example를 기준으로 아래만 override하면 된다.

POSTGRES_HOST=127.0.0.1
각 서비스에 맞는 POSTGRES_PORT
container service name으로 적혀 있던 *_BASE_URL은 host에서 띄운 주소로 교체

예:

driver-profile host 실행: POSTGRES_HOST=127.0.0.1 POSTGRES_PORT=15432
dispatch-registry host 실행: POSTGRES_HOST=127.0.0.1 POSTGRES_PORT=15438
settlement-registry host 실행: POSTGRES_HOST=127.0.0.1 POSTGRES_PORT=15434
delivery-record host 실행: POSTGRES_HOST=127.0.0.1 POSTGRES_PORT=15435
settlement-payroll host 실행: POSTGRES_HOST=127.0.0.1 POSTGRES_PORT=15433

Docker Desktop 설정 변경은 앱 재시작 후 반영된다.

Optional Dev Gateway

5174의 host frontend와 host Django services를 http://localhost:8080으로 다시 묶고 싶으면 dev gateway만 따로 띄운다.

실행:

cd /Users/jiin/Documents/Files/02_EVnSolution/00_Source_code/CLEVER/clever-msa-platform/development/integration-local-stack
./scripts/up_dev_gateway.sh

정지:

cd /Users/jiin/Documents/Files/02_EVnSolution/00_Source_code/CLEVER/clever-msa-platform/development/integration-local-stack
./scripts/down_dev_gateway.sh

이 gateway는 아래 host 포트로 프록시한다.

/ -> http://127.0.0.1:5174
/api/auth/ -> 18001
/api/org/ -> 18002
/api/drivers/ -> 18003
/api/vehicles/ -> 18004
/api/dispatch/ -> 18005
/api/dispatch-ops/ -> 18010
/api/settlement-registry/ -> 18006
/api/delivery-record/ -> 18007
/api/settlements/ -> 18008
/api/settlement-ops/ -> 18009

Host Env Templates

dispatch + settlement slice용 host env template는 infra/env/host/ 아래에 둔다.

이 template들은 docker-compose.dev-infra.yml의 DB/redis 포트와 docker-compose.dev-gateway.yml의 host service 포트 기준으로 맞춰져 있다.

host Django 서비스 실행 helper:

./scripts/bootstrap_host_python_env.sh ../service-driver-profile
./scripts/bootstrap_host_python_env.sh ../service-organization-registry
./scripts/bootstrap_host_python_env.sh ../service-account-access
./scripts/bootstrap_host_python_env.sh ../service-dispatch-operations-view
./scripts/bootstrap_host_python_env.sh ../service-vehicle-assignment

./scripts/migrate_host_django_service.sh ../service-driver-profile ./infra/env/host/driver-profile.env.example
./scripts/migrate_host_django_service.sh ../service-organization-registry ./infra/env/host/organization-master.env.example
./scripts/migrate_host_django_service.sh ../service-account-access ./infra/env/host/account-auth.env.example
./scripts/migrate_host_django_service.sh ../service-vehicle-assignment ./infra/env/host/driver-vehicle-assignment.env.example

./scripts/run_host_django_service.sh ../service-driver-profile ./infra/env/host/driver-profile.env.example
./scripts/run_host_django_service.sh ../service-organization-registry ./infra/env/host/organization-master.env.example
./scripts/run_host_django_service.sh ../service-account-access ./infra/env/host/account-auth.env.example
./scripts/run_host_django_service.sh ../service-dispatch-registry ./infra/env/host/dispatch-registry.env.example
./scripts/run_host_django_service.sh ../service-vehicle-registry ./infra/env/host/vehicle-asset.env.example
./scripts/run_host_django_service.sh ../service-vehicle-assignment ./infra/env/host/driver-vehicle-assignment.env.example
./scripts/run_host_django_service.sh ../service-dispatch-operations-view ./infra/env/host/dispatch-ops.env.example

bootstrap_host_python_env.sh는 service repo별 .venv를 만들고 requirements.txt를 설치한다. 상대경로와 절대경로 둘 다 받을 수 있다.

migrate_host_django_service.sh는 같은 env file을 export한 뒤 manage.py migrate를 실행한다. 새 DB를 붙일 때는 첫 실행 전에 한 번 돌린다.

run_host_django_service.sh는 env file을 export한 뒤 service repo에 .venv/bin/python이 있으면 그 interpreter로 manage.py runserver를 실행한다. .venv가 없으면 python3로 fallback한다. 상대경로와 절대경로 둘 다 받을 수 있다.

dispatch-ops와 driver-vehicle-assignment는 low-CPU hybrid 기준에서 sqlite-only로 돌릴 수 있다. 이 둘은 host env에서 POSTGRES_*를 비워 둔 채 실행해도 되고, dispatch-ops는 driver-vehicle-assignment가 내려가 있으면 current assignment source를 warning으로만 처리한다.

현재 local stack에는 dispatch-ops-api가 포함된다.

service-dispatch-registry, service-vehicle-assignment, service-vehicle-registry, service-driver-profile를 fan-out read 하는 read-model runtime이다.
sqlite-only runtime이며 dedicated Postgres container를 추가하지 않는다.

현재 local stack의 settlement는 settlement-payroll-api와 settlement-ops-api로 분리된다.

/api/settlements/는 write owner settlement-payroll-api로 연결된다.
/api/settlement-ops/는 read-only fan-out settlement-ops-api로 연결된다.
read consumer env는 SETTLEMENT_OPS_BASE_URL를 사용한다.
settlement Postgres는 settlement-payroll-api만 사용하고 settlement-ops-api는 sqlite-only runtime이다.

실행 문서:

compose 시뮬레이션 설명은 compose/README.md
플랫폼 전체 경계는 ../../docs/
current MSA API 문서 entry는 compose/api-docs/README.md
current MSA API 문서 재생성 helper는 ./scripts/refresh_api_docs.py
current MSA API 문서 preview helper는 ./scripts/preview_api_docs.py
root repo GitHub Actions entry는 ../../.github/workflows/refresh-api-docs.yml

Root Docs / Runbooks

Local Telemetry Smoke

service-telemetry-listener의 deterministic smoke publish는 다음 조합을 사용한다.

sample payload: ../service-telemetry-listener/tests/fixtures/sample_payload.json
helper: ./scripts/publish_sample_telemetry.sh
topic: telemetry/vehicles/50000000-0000-0000-0000-000000000001/location-update

helper는 baseline sample payload를 읽고 publish 시점마다 captured_at과 diagnostic timestamp를 새로 주입한다. 주입값은 현재 UTC 기준 하루 뒤로 잡혀서 seeded snapshot보다 항상 새롭다.

helper는 로컬 브로커의 local demo MQTT credentials only 를 사용한다.

username: telemetry-listener
password: local-mqtt-password

Deterministic Failure Smoke

service-telemetry-listener의 dead-letter smoke는 malformed JSON fixture를 사용해 listener-side parse_error를 반복 재현한다.

malformed payload: ../service-telemetry-listener/tests/fixtures/malformed_payload.txt
helper: ./scripts/publish_malformed_telemetry.sh
topic: telemetry/vehicles/50000000-0000-0000-0000-000000000001/location-update

helper는 payload를 가공하지 않고 그대로 publish한다. 이 경로는 manual payload crafting 없이 local smoke에서 최소 1개의 dead-letter row를 생성하는 목적이다.

listener는 gateway 경로가 아니라 telemetry-hub 내부 경로 /ingest/raw/ 를 사용한다. dead-letter write도 gateway를 거치지 않고 dead-letter service 내부 경로 /ingest/ 를 사용한다.

phase 1 dead-letter producer key는 service-specific env만 채운다.

listener source_service: service-telemetry-listener
listener producer key env: TELEMETRY_DEAD_LETTER_KEY_SERVICE_TELEMETRY_LISTENER

브로커 컨테이너 이미지에 mosquitto_pub가 있어야 한다. 없다면 helper는 명시적으로 실패한다.

Dead-Letter Gateway Route Smoke

dead-letter gateway 노출 규칙은 다음 helper로 자동 검증할 수 있다.

helper: ./scripts/verify_dead_letter_gateway_routes.py

기본 검증 범위:

/api/telemetry-dead-letters/health/ 는 200
/api/telemetry-dead-letters/ 와 detail route 는 gateway에 노출되지만 unauthenticated 기준 401
/api/telemetry-dead-letters/ingest 와 /api/telemetry-dead-letters/ingest/ 는 gateway 기준 404
no-slash canonical redirect 는 301

실행 예시:

python3 ./development/integration-local-stack/scripts/verify_dead_letter_gateway_routes.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

integration-local-stack

Purpose / Boundary

Runtime Contract / Local Role

Image Build / Deploy Contract

Environment Files And Safety Notes

Env Template Rule

Frontend Local Development Rule

Local Run / Verification

Current Dev/Test/Deploy Flow

1. 개발

2. 통합 테스트

3. 배포

Key Tests Or Verification Commands

Low CPU Hybrid Development

Optional Dev Gateway

Host Env Templates

Root Docs / Runbooks

Local Telemetry Smoke

Deterministic Failure Smoke

Dead-Letter Gateway Route Smoke

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
compose		compose
fixtures		fixtures
infra		infra
scripts		scripts
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
README.md		README.md
docker-compose.account-driver-settlement.yml		docker-compose.account-driver-settlement.yml
docker-compose.deploy.account-driver-settlement.yml		docker-compose.deploy.account-driver-settlement.yml
docker-compose.dev-gateway.yml		docker-compose.dev-gateway.yml
docker-compose.dev-infra.yml		docker-compose.dev-infra.yml
lesson.md		lesson.md

Folders and files

Latest commit

History

Repository files navigation

integration-local-stack

Purpose / Boundary

Runtime Contract / Local Role

Image Build / Deploy Contract

Environment Files And Safety Notes

Env Template Rule

Frontend Local Development Rule

Local Run / Verification

Current Dev/Test/Deploy Flow

1. 개발

2. 통합 테스트

3. 배포

Key Tests Or Verification Commands

Low CPU Hybrid Development

Optional Dev Gateway

Host Env Templates

Root Docs / Runbooks

Local Telemetry Smoke

Deterministic Failure Smoke

Dead-Letter Gateway Route Smoke

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages