From 99473caa1c88425dab0dcb2e1d84dc8b2a8aec0c Mon Sep 17 00:00:00 2001 From: Justin Ko Date: Tue, 18 Aug 2026 17:38:18 +0900 Subject: [PATCH] docs: document k3s container topology --- README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/README.md b/README.md index edacb45..f19aba2 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,41 @@ streamlit run dashboard/app.py --server.address 0.0.0.0 --server.port 8501 - 계좌: 등록 계좌/잔액 확인 - Import: PDF/CSV/API import batch 조회 및 rollback +## 컨테이너 및 k3s 실행 구조 + +릴리즈 이미지는 MCP 서버와 Streamlit Dashboard의 코드 및 의존성을 모두 포함하지만, 이미지의 기본 명령(`CMD`)은 MCP 서버만 실행합니다. `EXPOSE 8000 8501`은 사용할 포트를 선언할 뿐 Streamlit 프로세스를 자동으로 시작하지 않습니다. + +현재 Dashboard는 MCP를 경유하지 않고 MCP 서버와 동일한 SQLite 파일을 직접 읽고 씁니다. 따라서 k3s에서는 두 프로세스를 별도 Deployment로 나누기보다 다음과 같이 함께 배치합니다. + +```text +Deployment: jarca-ledger (replicas: 1) +└─ Pod + ├─ mcp container + │ ├─ 동일 릴리즈 이미지 + │ ├─ 기본 CMD: jarca-ledger-mcp + │ └─ containerPort: 8000 + ├─ frontend container + │ ├─ 동일 릴리즈 이미지 + │ ├─ command: python -m streamlit run dashboard/app.py ... + │ └─ containerPort: 8501 + └─ shared PVC + └─ /data/ledger.sqlite3 +``` + +운영 원칙: + +- 하나의 Pod 안에서 MCP와 Streamlit을 **별도 컨테이너**로 실행합니다. 한 컨테이너에서 두 프로세스를 supervisor나 background command로 함께 실행하지 않습니다. +- 두 컨테이너는 동일한 PVC를 `/data`에 마운트하고 `JARCA_LEDGER_DB_PATH=/data/ledger.sqlite3`를 사용합니다. +- SQLite 파일을 공유하므로 Deployment의 replica는 `1`로 유지합니다. +- MCP와 frontend는 목적별 Kubernetes Service로 분리합니다. MCP는 `8000`, frontend는 `8501`을 대상으로 합니다. +- 외부 공개가 필요하면 일반적으로 frontend Service만 Ingress 또는 NodePort에 연결하고, MCP Service는 필요한 범위에서만 노출합니다. +- ARM64 worker에서만 실행하도록 Pod의 `nodeSelector` 또는 node affinity를 설정합니다. +- 배포 이미지는 가변 태그 대신 검증된 GHCR digest로 고정합니다. + +Streamlit이 SQLite에 직접 접근하지 않고 MCP/API만 호출하도록 변경하거나 네트워크 DB로 전환한 뒤에는 MCP와 frontend를 각각 독립 Deployment로 분리할 수 있습니다. + +로컬 `docker-compose.yml`도 동일한 애플리케이션 이미지를 두 컨테이너로 실행하는 구조입니다. 현재 Compose 설정은 로컬에서 빌드한 `jarca-ledger:latest`를 사용하며, MCP는 호스트 `8000` 포트로, Streamlit은 호스트 `40059`에서 컨테이너 `8501` 포트로 연결됩니다. GHCR 릴리즈를 배포할 때는 두 서비스의 `image`를 검증된 동일 digest로 지정해야 합니다. + ## 주요 도구 - `ledger_health_check`