Tilt
Tilt는 Lumie의 기본 개발 진입점입니다. 이 페이지는 프론트엔드는 로컬에서
실행되고, 백엔드, 워커, 상태 저장 서비스는 dev 클러스터에서 실행되는 공용 개발
스택을 시작하는 how-to 가이드입니다.
준비 사항
.github/tilt-up.sh가 포함된 워크스페이스 체크아웃- 스크립트가
ssh ... k3s로 터널을 열기 때문에k3s라는 이름의 동작하는 SSH host alias - 스크립트가
KUBECONFIG로 내보내는$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를 내보냅니다.- 추가 인자를 전달하면서
.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 앱에 도달하고, 프론트엔드 편집이 클러스터 재배포 없이 핫 리로드됩니다.
브라우저 요청이 백엔드에 도달하는 방식
일반적인 로컬 흐름에서는 브라우저가 클러스터 API origin을 직접 호출하지 않습니다. 대신 다음 경로를 따릅니다.
- 브라우저가
http://localhost:3000의 로컬 프론트엔드와 통신합니다. - 프론트엔드 API 호출은 동일 출처
/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 라우트만 제공하고, 루트 경로는404를 반환합니다. next dev를 클러스터로 옮기지 마세요. 프론트엔드Tiltfile과 워크스페이 스 규칙은 HMR을 의도적으로 로컬에 유지합니다.