fix(deploy): configure a warehouse and a fitting memory limit in the production compose

[Eomdahyeon]

Closes #993

문제

운영 compose(docker-compose.prod.app.yml)가 warehouse 경로를 주지 않아 /warehouse/* 가 전부 warehouse_not_configured 이고, 컨테이너 메모리 한도 512M 은 DuckDB 연결 하나의 기본 한도(1GB)보다 작다.

변경 내용

• KPUBDATA_BUILDER_WAREHOUSE=/data/warehouse (builder-data 볼륨 안).
• 리소스 설정을 명시하고 .env 로 덮어쓸 수 있게 했다: MAX_WORKERS=2, DUCKDB_THREADS=1, DUCKDB_MEMORY_LIMIT=128MB, DUCKDB_MAX_TEMP_SIZE=1GB, QUERY_MAX_CONCURRENCY=1, QUERY_MAX_MEMORY_MB=768, QUERY_MEMORY_BUDGET_MB=768.
• 컨테이너 한도 512M → ${BUILDER_MEMORY_LIMIT:-3G}.
• .env.app.example 에 같은 변수와 계산식, docs/deploy.md §9 에 운영 기본값 표.
• 검사: tests/unit/test_prod_compose_budget.py 가 compose 파일의 기본값에서 DuckDB 연결 수 × DUCKDB_MEMORY_LIMIT + QUERY_MEMORY_BUDGET_MB + 400 MB 를 계산해 한도와 비교한다. 예전 512M 은 이 검사를 통과하지 못한다(그 자체를 테스트로 둠).

이슈의 제안(2 GiB)과 다르게 한 것 — 3 GiB

이슈는 "2GiB 기준 제안"이었다. 실측해 보니 맞추기 어렵다:

• KPUBDATA_DUCKDB_MEMORY_LIMIT=64MB 에서는 parity 시나리오의 20행짜리 빌드도 the table needs more memory or temporary disk than this deployment allows 로 실패한다 (tests/parity 23개 중 4개 실패). 96MB 부터 통과한다.
• 96 MB 는 여유가 없는 하한이라 128 MB 로 잡았고, 연결 10개(build 2 × source 4 + preview + composition) × 128 MB = 1280 MB, query 768 MB, 기본 400 MB → 2448 MB. 2 GiB(2048 MB)에 들어가지 않는다.

app-01 VM 의 실제 메모리를 모른다. 3 GiB 가 호스트보다 크면 한도는 의미가 없고 호스트 OOM 이 먼저 온다 — 그 경우 .env 에서 KPUBDATA_BUILDER_MAX_WORKERS=1(HTTP worker 도 1 이 된다) 이나 query 예산을 줄이고 BUILDER_MEMORY_LIMIT 을 맞춰야 한다. 이 선택은 확인이 필요하다.

검증

• BuilderService(output_root=/data, warehouse_root=/data/warehouse) 로 list_warehouse_tables → 200 {"tables": []}, 디렉터리는 첫 사용 때 만들어진다 (로컬 실행).
• 위 query 설정(QUERY_MAX_MEMORY_MB=768 등)으로 warehouse profile/aggregate/export 테스트와 parity: 118 passed. DuckDB 128MB·thread 1 로 parity: 23 passed.
• tests/unit/test_prod_compose_budget.py: 6개 통과.
• compose 를 실제로 띄워 보지는 못했다 (로컬에 docker 없음). 완료 조건 "운영 프로필에서 GET /warehouse/tables 가 200" 은 위 in-process 확인까지만 했다.

🤖 Generated with Claude Code

[Eomdahyeon]

이 PR 은 직접 머지하지 않고 owner 리뷰로 남긴다. 운영 compose 의 메모리 한도(512M → 3G)와 worker·DuckDB 한도를 정하는데, app-01 VM 의 실제 메모리를 확인하지 못한 채 잡은 값이다. VM 메모리에 맞는지 확인하고 필요하면 .env 기본값을 조정해 달라 — 계산식은 본문과 docs/deploy.md §9 에 있다.

[yeongseon]

리뷰 (코멘트, 승인 아님).

warehouse 루트(/data/warehouse)와 예산 식, 그 식을 compose 파일에서 계산하는 테스트까지 타당합니다. 64MB 에서 20행 빌드가 실패한다는 실측을 문서에 남긴 것도 좋습니다.

본문이 확인을 요청한 app-01 VM 메모리는 고려하지 않기로 했습니다 — 거기에 배포하지 않습니다. 따라서 3G 기본값은 그대로 두면 되고, 실제 배포 대상이 정해지면 .env 의 BUILDER_MEMORY_LIMIT·KPUBDATA_BUILDER_MAX_WORKERS 로 맞춥니다.

#1020 과 .env.app.example·docker-compose.prod.app.yml 의 같은 자리를 고칩니다. 하나가 먼저 들어가면 다른 쪽은 리베이스가 필요합니다.

[yeongseon]

승인합니다. 앞선 리뷰 코멘트 그대로입니다.