Docker Compose로 RCA 플랫폼 실행 구조 묶기

Kubernetes Cluster Infra RCA Platform 개발 기록 5편

---

지난 글에서는 RCA report를 확인할 Web Console을 붙인 과정을 적었다.

Backend의 report 생성, Console의 결과 조회, Kubernetes Node Agent의 evidence 수집 흐름이 잡힌 상태였다.

다음에는 이 컴포넌트들을 한 번에 실행할 방법을 정리했다.

개발 중에는 각각 실행해도 됐지만, 다시 실행할 때마다 연결 설정을 맞추는 일이 번거로웠다.

다른 사람이 프로젝트를 확인하거나 나중에 내가 다시 실행할 때도 같은 절차를 사용할 수 있어야 했다.

Docker Compose로 전체 실행 구조를 묶기로 했다.

---

왜 Docker Compose가 필요했나

전체 흐름을 실행하려면 여러 구성요소가 필요했다.

• Backend API
• Web Console
• Database
• DB migration
• Node Agent 또는 Agent manifest
• 환경 변수 설정

초기에는 Backend만 실행해 API를 확인했다.

Console과 DB가 붙은 뒤에는 서로 연결되는지도 확인해야 했다.

Console의 Backend API URL, Backend의 DB 연결, migration으로 준비할 schema를 함께 맞춰야 했다.

수동으로 맞추던 설정과 실행 순서를 Compose에 정리했다.

---

목표는 완벽한 운영 배포가 아니었다

이 단계에서 운영 배포까지 마친 것은 아니었다.

목표는 로컬에서 전체 플랫폼을 실행하고 검증하는 것이었다.

다음 흐름을 빠르게 확인하려고 했다.

docker compose up
  -> DB 실행
  -> Backend 실행
  -> migration 적용
  -> Web Console 실행
  -> Console에서 Backend API 호출

기능을 추가한 뒤 전체 연결이 깨졌는지 확인할 수 있는 실행 환경이 필요했다.

---

Backend 컨테이너화

먼저 Backend 실행 환경을 Dockerfile로 만들었다.

당시 Backend는 FastAPI였으므로 Python 환경, dependency 설치, 실행 명령을 포함했다.

환경마다 달라지는 값은 이미지 밖으로 분리했다.

DB URL, 인증 설정, LLM provider 설정, session TTL은 환경 변수로 받도록 했다.

로컬, 테스트, 배포 환경에서 같은 이미지를 쓰고 설정만 바꾸려는 구성이다.

같은 이미지
  -> 다른 환경 변수
  -> 다른 실행 환경

이후 Kubernetes로 옮길 때도 이미지와 설정을 나눠 사용할 수 있도록 했다.

---

DB와 migration 흐름

RCA report를 재시작 후에도 남기기 위해 DB를 함께 실행했다.

DB 컨테이너의 실행 여부와 schema 준비 여부는 따로 봐야 했다.

Backend가 API를 받기 전에 필요한 schema가 있어야 했기 때문이다.

migration도 실행 순서 안에 포함했다.

DB start
  -> migration run
  -> Backend ready
  -> Web Console connect

migration이 빠지면 Backend 프로세스가 떠 있어도 없는 DB table을 조회하다 API가 실패할 수 있었다.

그래서 Backend readiness 이전에 schema 준비가 끝나도록 흐름을 정리했다.

---

Web Console 연결

Console에서 실제 API를 호출할 경로도 맞췄다.

Compose에서는 Console이 바라볼 Backend URL을 설정할 수 있게 했다.

Compose 내부의 서버 간 통신에서는 Backend service name을 사용할 수 있었다.

web-console
  -> backend:8000

브라우저에서 직접 호출하는 API는 외부에서 접근 가능한 URL이 필요할 수 있었다.

두 경로를 환경에 맞게 설정할 수 있도록 Console 설정도 분리했다.

화면 응답과 Backend API 연결을 각각 확인하려고 했다.

---

smoke test를 같이 둔 이유

Compose 실행 후에는 smoke test로 연결 상태를 확인했다.

컨테이너가 모두 up이어도 Backend의 DB 연결이나 Console의 API 호출은 실패할 수 있었다.

그래서 최소 동작을 확인할 항목을 정했다.

• Backend readiness 응답
• DB migration 적용 여부
• Web Console 응답
• Console에서 Backend로 API 호출 가능 여부
• cluster 등록 API 동작 여부
• report 관련 API가 깨지지 않았는지

기능별 상세 테스트와 별개로, 전체 컴포넌트가 연결되는지 확인하는 시험이었다.

---

Codex를 어떻게 활용했는가

Compose에 넣을 구성요소와 실행 순서는 직접 정했다.

환경 변수의 구분, migration 시점, smoke test 범위도 직접 검토했다.

Dockerfile과 Compose 설정, 반복되는 smoke test 코드, README 초안에는 Codex를 활용했다.

작업을 다음처럼 나눴다.

사람:
실행 구조 설계
컴포넌트 연결 방식 결정
환경 변수 기준 정리
검증해야 할 흐름 결정

Codex:
Dockerfile 초안 작성
docker-compose.yml 정리
smoke test 스크립트 보강
README 실행 방법 정리
반복 설정 보완

반복 설정을 작성하는 시간을 줄일 수 있었다.

Compose 구성이 맞는지와 운영 배포에서 추가로 분리할 부분은 직접 검토했다.

---

이 단계에서 중요했던 점

한 번 실행하는 데 그치지 않고 같은 절차로 다시 실행할 수 있도록 했다.

이를 위해 다음 기준을 뒀다.

1. Backend, DB, Web Console을 한 번에 실행할 수 있어야 한다
2. DB migration 흐름이 누락되면 안 된다
3. 환경 변수로 설정을 분리해야 한다
4. Console이 실제 Backend와 연결되는지 확인해야 한다
5. smoke test로 최소 동작을 검증해야 한다
6. Codex는 반복 설정 작성에 활용하되, 실행 구조 판단은 사람이 한다

특히 1번과 5번을 같이 봤다.

실행 절차를 줄이는 것과 실행 후 연결 상태를 확인하는 것이 모두 필요했다.

---

마무리

Docker Compose로 로컬 전체 실행 환경을 묶었다.

Backend, DB, Web Console을 함께 실행하고 migration과 API 연결을 확인할 수 있게 됐다.

다음 글에서는 cluster 삭제와 RCA report export를 추가하고 관리 흐름을 정리한 과정을 다룬다.