Tilt
Tilt는 Lumie의 기본 개발 진입점입니다. 이 페이지는 프론트엔드는 로컬에서
실행되고, 백엔드, 워커, 상태 저장 서비스는 dev 클러스터에서 실행되는 공용 개발
스택을 시작하는 how-to 가이드입니다.
준비 사항
.github/tilt-up.sh가 포함된 워크스페이스 체크아웃- 스크립트가
ssh ... k3s로 터널을 열기 때문에k3s라는 이름의 동작하는 SSH host alias - 스크립트가
KUBECONFIG로 export하는$HOME/.kube/lumie-k3s.yaml의 kubeconfig - 스크립트가 직접 호출하는
ssh,nc,lsof,tilt의 로컬 설치 - 프론트엔드
Tiltfile이npm run dev를 시작하므로 로컬에 설치된lumie-frontend의존성
1단계: 워크스페이스 루트에서 Tilt 시작
cd /path/to/Lumie
.github/tilt-up.sh
예상 성공 신호:
- 스크립트가
Starting SSH tunnel to k3s API (localhost:6443)...를 출력합니다. - 스크립트가
Tunnel ready를 출력합니다. - Tilt가 시작되고
http://localhost:3000에 연결된lumie-frontend리소스를 표시합니다.
워크스페이스 스크립트가 하는 일
이 스크립트는 tilt up으로 넘기기 전에 세 가지를 수행합니다.
- K3s API가
localhost:6443에서 접근 가능하도록 SSH 터널을 엽니다. KUBECONFIG=$HOME/.kube/lumie-k3s.yaml를 export합니다.- 추가 인자를 전달하면서
.github/에서tilt up을 실행합니다.
세션이 끝나면 스크립트는 SSH control socket을 닫고, 필요하면 다음 실행에서 오래된 터널 상태를 정리합니다.
런타임 분리
프론트엔드
lumie-frontend/Tiltfile은 다음을 실행하는 local_resource를 정의합니다.
npm run dev
프론트엔드는 개발자 머신에 머물며 http://localhost:3000을 제공합니다.
NEXT_PUBLIC_API_BASE 같은 현재 로컬 env 값은 Tiltfile이 직접 주입하므로,
표준 Tilt 경로는 체크인된 .env.example이나 수동으로 만든 .env.local에
의존하지 않습니다.
백엔드와 워커
백엔드와 워커 Tiltfile은 워크로드를 lumie-dev 네임스페이스에 빌드하고
배포합니다. 이 서비스들은 로컬 복사본 대신 클러스터 측의 공용 PostgreSQL,
RabbitMQ, Redis, MinIO 인스턴스를 사용합니다.
워커는 더 촘촘한 내부 루프를 위해 live-update 스타일 컨테이너 sync를 사용하고, 백엔드는 Java 애플리케이션이 기대하는 클러스터 배포 경로를 따릅니다.
2단계: 로컬 프론트엔드 열기
Tilt가 lumie-frontend 리소스를 실행 중으로 표시한 뒤
http://localhost:3000을 여세요.
예상 성공 신호: 브라우저가 클러스터 호스트명이 아니라 로컬 Next.js 앱에 도달하고, 프론트엔드 편집이 클러스터 재배포 없이 hot reload됩니다.
브라우저 요청이 백엔드에 도달하는 방식
일반적인 로컬 흐름에서는 브라우저가 클러스터 API origin을 직접 호출하지 않습니다. 대신 다음 경로를 따릅니다.
- 브라우저가
http://localhost:3000의 로컬 프론트엔드와 통신합니다. - 프론트엔드 API 호출은 same-origin
/api/...라우트를 통과합니다. app/api/[...path]/route.ts가 이 요청들을NEXT_PUBLIC_API_BASE로 프록시합니다.- 프록시는
Set-Cookie헤더에서Domain과Secure를 제거해 인증 쿠키가 localhost에 올바르게 저장되도록 합니다.
이 덕분에 백엔드 자체는 클러스터에서 실행되더라도 로컬 개발에서 로그인과 브라우저 세션 동작을 예측 가능하게 유지할 수 있습니다.
검증
nc -z 127.0.0.1 6443
예상 성공 신호: Tilt가 실행 중일 때 이 명령이 성공 종료되어 SSH 터널이 열려 있음을 확인합니다.
curl -I http://localhost:3000
예상 성공 신호: connection refused 대신 로컬 프론트엔드의 HTTP 응답을
받습니다.
흔한 실패
ERROR: Tunnel not ready after 15s는 보통k3sSSH alias가 없거나, 클러스터에 접근할 수 없거나,6443포트가 막혀 있음을 의미합니다.tilt: command not found는 노트북에 Tilt가 설치되지 않았다는 뜻입니다.lumie-frontend리소리는npm run dev가 시작되지 못하면 즉시 실패하며, 보통lumie-frontend에 의존성이 없을 때 발생합니다.- 프론트엔드 프록시를 우회하고
https://dev.lumie-infra.com/를 직접 열면 로그인 쿠키가 깨집니다. 이 호스트는 API 라우트만 제공하고, bare root는404를 반환합니다. next dev를 클러스터로 옮기지 마세요. 프론트엔드Tiltfile과 워크스페이스 규칙은 HMR을 의도적으로 로컬에 유지합니다.