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

Kubernetes Cluster Infra RCA Platform 개발 기록 5편

지난 글에서는 RCA report를 운영자가 확인할 수 있도록 Web Console을 붙이는 과정을 정리했습니다.

이제 Backend는 RCA report를 만들 수 있고, Web Console은 그 결과를 보여줄 수 있고, Node Agent는 Kubernetes 노드에서 evidence를 수집하는 방향으로 정리되고 있었습니다.

그 다음 고민은 이것이었습니다.

이걸 어떻게 한 번에 실행 가능한 형태로 만들 것인가?

개발 중에는 각 컴포넌트를 따로 실행해도 괜찮습니다.

하지만 프로젝트를 다른 사람이 보거나, 나중에 내가 다시 실행하려고 할 때 매번 Backend, DB, Web Console을 각각 띄우는 방식은 불편합니다.

그래서 이번 단계에서는 Docker Compose를 이용해 전체 플랫폼을 실행 가능한 구조로 묶었습니다.

왜 Docker Compose가 필요했나

이 프로젝트는 단일 애플리케이션이 아닙니다.

최소한 다음 구성요소가 필요합니다.

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

개발 초기에는 Backend만 실행해도 충분했습니다.

하지만 기능이 늘어나면서 컴포넌트 사이의 연결이 더 중요해졌습니다.

예를 들어 Web Console은 Backend API URL을 알아야 하고, Backend는 DB에 연결되어야 하며, DB schema는 migration을 통해 준비되어야 합니다.

이런 흐름을 매번 수동으로 맞추면 실수가 생기기 쉽습니다.

그래서 Docker Compose로 실행 구조를 정리했습니다.

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

Docker Compose를 붙였다고 해서 바로 운영 환경 배포를 끝냈다는 뜻은 아닙니다.

이번 단계의 목표는 운영 배포보다는 로컬에서 전체 플랫폼을 쉽게 실행하고 검증하는 것에 가까웠습니다.

즉, 이런 흐름을 빠르게 확인하고 싶었습니다.

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

이 정도만 안정적으로 되어도 개발 효율이 많이 좋아집니다.

새로운 기능을 추가한 뒤 전체 흐름이 깨졌는지 빠르게 확인할 수 있기 때문입니다.

Backend 컨테이너화

먼저 Backend를 컨테이너로 실행할 수 있게 정리했습니다.

Backend는 FastAPI 기반이기 때문에 Python 환경, dependency 설치, 실행 명령을 Dockerfile에 담아야 했습니다.

중요하게 본 것은 환경 변수였습니다.

Backend는 DB URL, 인증 관련 설정, LLM provider 설정, session TTL 같은 값을 환경 변수로 받아야 합니다.

그래야 로컬, 테스트, 배포 환경에서 같은 이미지를 쓰면서 설정만 바꿀 수 있습니다.

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

이 구조가 되어야 나중에 Docker Compose뿐 아니라 Kubernetes 배포로 넘어가기도 쉬워집니다.

DB와 migration 흐름

RCA report는 운영 기록이기 때문에 DB에 남아야 합니다.

그래서 Compose 구조에서도 DB는 중요한 구성요소였습니다.

단순히 DB 컨테이너를 띄우는 것만으로는 부족했습니다.

Backend가 실행되기 전에 schema가 준비되어야 하기 때문입니다.

그래서 migration 실행 흐름도 같이 고려했습니다.

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

이 구조가 없으면 Backend는 켜졌지만 API 호출 시 DB table이 없어서 실패하는 상황이 생길 수 있습니다.

개발 중에는 이런 문제가 생각보다 자주 발생합니다.

그래서 migration을 실행 흐름 안에 넣는 것은 꼭 필요하다고 판단했습니다.

Web Console 연결

Web Console은 Backend와 연결되어야 의미가 있습니다.

그래서 Compose에서는 Web Console이 어떤 Backend URL을 바라볼지도 설정할 수 있게 했습니다.

로컬에서는 보통 내부 네트워크의 Backend service name을 사용할 수 있습니다.

web-console
  -> backend:8000

하지만 브라우저에서 접근할 때는 또 다른 public API URL이 필요할 수 있습니다.

이 부분은 환경에 따라 달라질 수 있기 때문에, Console 쪽도 설정을 분리하는 방향으로 정리했습니다.

중요한 것은 Console이 단순히 뜨는 것이 아니라, 실제 Backend API와 연결되는지 확인하는 것이었습니다.

smoke test를 같이 둔 이유

Compose로 묶은 뒤에는 smoke test가 더 중요해졌습니다.

컨테이너가 실행되는 것과 플랫폼이 정상 동작하는 것은 다릅니다.

예를 들어 컨테이너는 모두 up 상태인데, 실제로는 Backend가 DB에 연결하지 못하거나, Web Console이 API 호출에 실패할 수 있습니다.

그래서 최소한의 확인 흐름을 smoke test에 넣었습니다.

확인하고 싶었던 것은 이런 것들이었습니다.

• 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 실행 방법 정리
반복 설정 보완

Codex는 이런 작업에서 확실히 도움이 됐습니다.

다만 Compose 구조 자체가 안전한지, 운영 환경으로 넘어갈 때 어떤 부분을 분리해야 하는지는 직접 검토해야 한다고 생각했습니다.

이 단계에서 중요했던 점

이번 단계에서 가장 중요하게 본 것은 “재현 가능성”이었습니다.

내 컴퓨터에서만 우연히 실행되는 프로젝트가 아니라, 명령어 몇 개로 다시 실행할 수 있는 구조가 필요했습니다.

정리하면 기준은 이랬습니다.

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

개인적으로는 1번과 5번이 가장 중요했습니다.

실행은 쉬워야 하고, 실행된 뒤에는 최소한 제대로 연결됐는지 확인할 수 있어야 합니다.

마무리

이번 단계에서는 RCA 플랫폼을 Docker Compose로 묶으면서, 로컬에서도 전체 구조를 실행하고 검증할 수 있게 만들었습니다.

Backend, DB, Web Console을 따로 보는 것이 아니라 하나의 플랫폼으로 실행할 수 있게 된 것이 가장 큰 변화였습니다.

이제 프로젝트는 단순한 코드 모음이 아니라, 실행 가능한 형태에 가까워졌습니다.

좋은 프로젝트는 기능만 있는 것이 아니라, 다시 실행하고 검증할 수 있어야 한다.

다음 글에서는 cluster 삭제, RCA report export 같은 운영 편의 기능을 추가하면서, 플랫폼을 실제로 관리 가능한 형태로 다듬은 과정을 정리해보려고 합니다.