개발 환경
Lumie 개발 환경은 FE-로컬, BE-클러스터 모델입니다. 상태형 서비스(백엔드, 워커, Postgres, RabbitMQ, Redis, MinIO)는 dev 클러스터에 Tilt로 배포되고, Next.js 프론트엔드는 로컬 머신에서 npm run dev로 실행됩니다. 프론트엔드 라이프사이클도 Tilt의 local_resource로 관리됩니다.
아키텍처 개요
시작 방법
# 워크스페이스 루트에서
.github/tilt-up.sh
tilt up을 직접 실행하지 마십시오. .github/tilt-up.sh는 SSH 터널을 통해 k3s API에 연결(localhost:6443)한 뒤 Tilt를 실행합니다. 직접 tilt up은 클러스터 API에 접근할 수 없습니다.
스크립트 동작
- 기존 SSH 터널 정리 (
/tmp/lumie-k3s-tunnel.sock, 포트 6443 해제) - SSH 터널 개설:
ssh -L 6443:127.0.0.1:6443 k3s export KUBECONFIG=~/.kube/lumie-k3s.yamltilt up실행 (.github/디렉터리 기준)
프론트엔드 로컬 실행
Next.js는 클러스터에 배포되지 않습니다. Tilt의 local_resource로 관리되며 npm run dev를 로컬에서 실행합니다.
http://localhost:3000
.env.local파일 불필요 —NEXT_PUBLIC_API_BASE=https://dev.lumie-infra.com은 Tiltfile의serve_env로 주입됩니다.- 브라우저 요청(
/api/v1/...)은app/api/[...path]/route.ts프록시를 통해https://dev.lumie-infra.com/api/v1/...로 전달됩니다. - ❌
next dev를 클러스터에 배포하지 마십시오. Turbopack 16.2+ HMR over Traefik HTTP/2 ALPN deadlocks client hydration.
Tilt 종료 시 (tilt down 또는 Ctrl+C) FE 프로세스도 함께 종료됩니다. 비정상 종료 후 포트 3000이 점유 상태일 경우:
lsof -ti tcp:3000 | xargs kill
dev 클러스터 네임스페이스
| 네임스페이스 | 용도 |
|---|---|
lumie-dev | 백엔드, 워커, CNPG(lumie-dev-db), RabbitMQ(rabbitmq-dev), Redis |
lumie-infra | ArgoCD, Tekton, Vault, Keycloak, Zot 등 인프라 |
monitoring | Prometheus, Grafana, Loki, Tempo |
kube-system | Traefik, cert-manager, Kyverno |
환경 변수 주입
2026-06-01부로 .env 파일이 제거되었습니다. 설정은 두 가지 방법으로 주입됩니다.
| 방법 | 대상 |
|---|---|
Tiltfile serve_env | FE NEXT_PUBLIC_API_BASE 등 비시크릿 공개 env |
| Vault → VSO (K8s Secret) | 백엔드 DB 비밀번호, JWT 시크릿, RabbitMQ/Redis 비밀번호 등 |
백엔드 파드에 주입되는 주요 환경 변수:
SPRING_PROFILES_ACTIVE: dev
DB_HOST: pgbouncer.lumie-dev.svc.cluster.local
DB_PORT: "5432"
DB_NAME: lumie
RABBITMQ_HOST: rabbitmq-dev.lumie-dev.svc.cluster.local
RABBITMQ_PORT: "5672"
REDIS_SENTINEL_MASTER: mymaster
REDIS_SENTINEL_NODES: redis.lumie-cache.svc.cluster.local:26379
민감한 값(비밀번호, JWT 시크릿 등)은 Vault-synced K8s Secret에서 secretKeyRef로 주입됩니다.
개발 서비스 URL
| 서비스 | URL |
|---|---|
| 프론트엔드 (로컬) | http://localhost:3000 |
| 백엔드 API | https://dev.lumie-infra.com/api/v1/... |
| ArgoCD | https://argocd.lumie-infra.com (Teleport 경유) |
| Grafana | https://grafana.lumie-infra.com (Teleport 경유) |
| Gitea | https://github.lumie-infra.com (Teleport mTLS) |
자주 쓰는 명령
kubectl
# dev 네임스페이스 파드 상태 확인
kubectl get pods -n lumie-dev
# 백엔드 로그 (K8s 배포 환경)
kubectl logs -n lumie-dev -l app=lumie-backend --tail=100 -f
# 시크릿 목록 확인
kubectl get secrets -n lumie-dev
# RabbitMQ 관리 콘솔 port-forward
kubectl port-forward -n lumie-dev svc/rabbitmq-dev 15672:15672
백엔드 Gradle (클러스터 내 배포 기준)
# 테스트 제외 JAR 빌드
./gradlew :app:bootJar -x test
# 전체 테스트
./gradlew test
# 통합 테스트 (TestContainers, 별도 태스크)
./gradlew :app:integrationTest