--- name: callabo-tmux description: Callabo 서비스들을 tmux로 한번에 실행합니다. callabo-server, scheduler, callabo-webapp, magi를 4개의 pane으로 구성하여 개발 환경을 빠르게 시작합니다. trigger_keywords: - 콜라보 실행 - callabo 실행 - 콜라보 띄워 - callabo run - 개발 서버 시작 - tmux 콜라보 - 작업 환경 띄워 - 서버 띄워 --- # Callabo Tmux 실행 스킬 ## Overview Callabo 개발 서버들을 tmux 세션으로 한번에 실행하는 스킬입니다. **핵심 기능:** - **통합 실행**: 4개 서비스를 하나의 tmux 세션으로 관리 - **자동 의존성 체크**: .venv, node_modules 자동 설치 - **AWS Vault 연동**: 자동 인증 처리 - **세션 관리**: 기존 세션 재접속 또는 재시작 **Pane 구성:** ``` ┌─────────────────┬─────────────────┐ │ callabo-server │ scheduler │ │ (API\/8000) │ (scheduled_task)│ ├─────────────────┼─────────────────┤ │ callabo-webapp │ magi │ │ (Next.js) │ (pnpm dev) │ └─────────────────┴─────────────────┘ ``` ## When to Use 이 스킬은 다음 상황에서 **자동으로** 활성화됩니다: **명시적 요청:** - "콜라보 서버 실행해줘" - "callabo 띄워줘" - "개발 서버 시작해줘" - "tmux로 콜라보 실행해줘" - "작업 환경 띄워줘" **자동 활성화:** - callabo-init으로 생성한 워크스페이스 실행 시 - 개발 작업 시작 전 ## Prerequisites ### 필수 도구 ```bash # tmux tmux -V # uv (Python) uv --version # yarn 또는 pnpm yarn --version pnpm --version # AWS Vault (선택) aws-vault --version ``` ### 워크스페이스 구조 실행할 디렉토리에 다음 구조가 필요: ``` \/ ├── callabo-server\/ │ ├── .env │ ├── .venv\/ # 자동 생성 │ └── asgi.py ├── callabo-webapp\/ │ ├── .env │ └── node_modules\/ # 자동 설치 ├── magi\/ │ ├── .env │ └── node_modules\/ # 자동 설치 └── run.sh ``` ## Workflow ### Step 1: 워크스페이스 확인 ```bash # 워크스페이스 경로 확인 ls -la \/ # 필수 디렉토리 확인 ls callabo-server\/ callabo-webapp\/ magi\/ ``` ### Step 2: 실행 스크립트 호출 ```bash # 스킬 내장 스크립트 경로 SKILL_SCRIPT=".\/scripts\/run.sh" # 기본 실행 (AWS Vault 비밀번호 자동 입력) echo "" | $SKILL_SCRIPT # 현재 디렉토리에서 실행 echo "" | $SKILL_SCRIPT . # AWS Vault 건너뛰기 (로컬 전용) CALLABO_SKIP_AWS_VAULT=1 $SKILL_SCRIPT ``` > **Note**: `echo "" |`는 AWS Vault 비밀번호 프롬프트에 빈 문자열(엔터)을 자동 입력합니다. ### Step 3: 옵션 설정 | 옵션 | 설명 | 예시 | |------|------|------| | `--name NAME` | tmux 세션 이름 | `--name my-callabo` | | `-f, --force` | 기존 세션 종료 후 재시작 | `-f` | | `--force-sync` | 의존성 강제 재설치 | `--force-sync` | | `--skip-scheduler` | 스케줄러 pane 생성 안 함 | `--skip-scheduler` | | `--with-scheduler` | 스케줄러 강제 활성화 | `--with-scheduler` | ### Step 4: 세션 관리 ```bash # 세션 목록 확인 tmux ls # 세션 접속 tmux attach -t # 세션 분리 (tmux 내에서) Ctrl+b, d # 세션 종료 tmux kill-session -t ``` --- ## Examples ### 예시 1: 기본 실행 ``` 사용자: 콜라보 서버 띄워줘 Claude: Callabo 개발 서버를 시작하겠습니다. 📍 현재 워크스페이스: ~\/work\/feature-login [명령 실행] echo "" | .\/scripts\/run.sh ~\/work\/feature-login ✅ tmux 세션 'runtime-feature-login' 이(가) 준비되었습니다. 접속 명령: tmux attach -t runtime-feature-login 실행 중인 서비스: - callabo-server: http:\/\/localhost:8000 - callabo-webapp: http:\/\/localhost:3000 - magi: http:\/\/localhost:3200 - scheduler: 백그라운드 실행 중 ``` ### 예시 2: 커스텀 세션명으로 실행 ``` 사용자: my-dev라는 이름으로 콜라보 띄워줘 Claude: 커스텀 세션명으로 실행하겠습니다. [명령 실행] echo "" | .\/scripts\/run.sh . --name my-dev ✅ tmux 세션 'my-dev' 생성 완료 Pane 구성: ┌─────────────┬─────────────┐ │ server │ scheduler │ ├─────────────┼─────────────┤ │ webapp │ magi │ └─────────────┴─────────────┘ ``` ### 예시 3: 기존 세션 강제 재시작 ``` 사용자: 콜라보 세션 다시 시작해줘 Claude: 기존 세션을 종료하고 재시작하겠습니다. [명령 실행] echo "" | .\/scripts\/run.sh . --force 기존 tmux 세션 'runtime-feature-login' 종료를 시도합니다... 기존 tmux 세션 'runtime-feature-login' 이(가) 정상적으로 종료되었습니다. ✅ 새 세션 시작 완료 ``` ### 예시 4: 스케줄러 없이 실행 ``` 사용자: 스케줄러 빼고 띄워줘 Claude: 스케줄러 없이 실행하겠습니다. [명령 실행] echo "" | .\/scripts\/run.sh . --skip-scheduler ✅ 세션 준비 완료 (scheduler 제외) Pane 구성: ┌─────────────┬─────────────┐ │ server │ (skipped) │ ├─────────────┼─────────────┤ │ webapp │ magi │ └─────────────┴─────────────┘ ``` ### 예시 5: 의존성 강제 재설치 후 실행 ``` 사용자: 의존성 다시 설치하고 띄워줘 Claude: 의존성을 재설치 후 실행하겠습니다. [명령 실행] echo "" | .\/scripts\/run.sh . --force-sync [callabo-server] CALLABO_FORCE_SYNC=1: uv sync를 강제로 실행합니다... [callabo-webapp] yarn install을 실행합니다... [magi] pnpm install을 실행합니다... ✅ 의존성 설치 완료 ✅ 세션 시작 완료 ``` ### 예시 6: 다른 워크스페이스 실행 ``` 사용자: ~\/work\/other-feature 워크스페이스 띄워줘 Claude: 지정된 워크스페이스를 실행하겠습니다. [명령 실행] echo "" | .\/scripts\/run.sh ~\/work\/other-feature ✅ tmux 세션 'runtime-other-feature' 준비 완료 접속: tmux attach -t runtime-other-feature ``` --- ## Configuration ### 환경 변수 | 변수 | 설명 | 기본값 | |------|------|--------| | `AWS_VAULT_PROFILE` | AWS Vault 프로파일 | `dev-callabo` | | `AWS_VAULT_PASS` | AWS Vault 비밀번호 (빈 문자열이면 자동 엔터) | `""` | | `CALLABO_SKIP_AWS_VAULT` | AWS Vault 건너뛰기 | 미설정 | | `CALLABO_FORCE_SYNC` | 강제 의존성 설치 | `0` | | `CALLABO_SKIP_SCHEDULER` | 스케줄러 비활성화 | `0` | | `CALLABO_FORCE_SHUTDOWN_TIMEOUT` | 종료 대기 시간(초) | `15` | **AWS Vault 자동 인증 (기본값):** ```bash # AWS_VAULT_PASS가 설정되면 자동으로 비밀번호 입력 # 빈 비밀번호인 경우 (기본값) AWS_VAULT_PASS="" .\/run.sh # 비밀번호가 있는 경우 AWS_VAULT_PASS="" .\/run.sh ``` ### 포트 설정 각 서비스의 포트는 `.env` 파일에서 설정: ```bash # callabo-server\/.env PORT=8000 UVICORN_PORT=8000 # callabo-webapp\/.env PORT=3000 # magi\/.env PORT=3200 ``` ### 세션 이름 규칙 `--name` 미지정 시 자동 생성: ``` runtime-{현재디렉토리이름} ``` 예시: - `~\/work\/feature-login` → `runtime-feature-login` - `~\/callabo-base` → `runtime-callabo-base` --- ## Tmux 단축키 세션 내에서 유용한 단축키: | 단축키 | 설명 | |--------|------| | `Ctrl+b, d` | 세션 분리 (detach) | | `Ctrl+b, o` | 다음 pane으로 이동 | | `Ctrl+b, ;` | 이전 pane으로 이동 | | `Ctrl+b, 방향키` | 해당 방향 pane으로 이동 | | `Ctrl+b, z` | 현재 pane 확대\/축소 | | `Ctrl+b, [` | 스크롤 모드 진입 | | `q` | 스크롤 모드 종료 | | `Ctrl+c` | 현재 pane 프로세스 중단 | --- ## Best Practices **DO:** - 작업 전 기존 세션 확인 (`tmux ls`) - 세션명을 기억하기 쉽게 지정 - 문제 발생 시 `--force`로 깨끗하게 재시작 - 의존성 문제 시 `--force-sync` 사용 **DON'T:** - 같은 워크스페이스에 여러 세션 실행 - 프로세스 강제 종료 대신 graceful shutdown 사용 - AWS Vault 없이 실서버 연동 시도 --- ## Troubleshooting ### tmux 세션 접속 안 됨 ```bash # 세션 존재 확인 tmux has-session -t # 세션 목록 tmux ls # 모든 세션 종료 후 재시작 tmux kill-server .\/run.sh ``` ### AWS Vault 인증 오류 ```bash # AWS Vault 프로파일 확인 aws-vault list # 수동 인증 aws-vault exec dev-callabo -- .\/run.sh # AWS Vault 건너뛰기 (로컬 전용) CALLABO_SKIP_AWS_VAULT=1 .\/run.sh ``` ### 포트 이미 사용 중 ```bash # 포트 사용 프로세스 확인 lsof -i :8000 lsof -i :3000 lsof -i :3200 # 프로세스 종료 kill -9 # 또는 기존 세션 강제 종료 후 재시작 .\/run.sh --force ``` ### .venv 손상됨 ```bash # 강제 재설치 .\/run.sh --force-sync # 또는 수동 재설치 cd callabo-server rm -rf .venv uv sync ``` ### Pane이 바로 종료됨 ```bash # 로그 확인 # 각 서비스 디렉토리에서 직접 실행하여 에러 확인 # callabo-server cd callabo-server && .venv\/bin\/python -m uvicorn asgi:app # callabo-webapp cd callabo-webapp && yarn dev # magi cd magi && pnpm dev ``` --- ## Integration 이 스킬은 다음 스킬과 연동됩니다: | 스킬 | 연동 방식 | |------|-----------| | callabo-init | 생성된 워크스페이스 실행 | | context-worktree | 워크스페이스 전환 시 실행 | ### callabo-init과의 워크플로우 ``` ┌─────────────────────────────────────────────────────────────┐ │ 일반적인 개발 시작 흐름: │ │ │ │ [callabo-init] ──────────────────> [callabo-tmux] │ │ │ │ │ │ │ 워크스페이스 생성 │ 서비스 실행 │ │ │ - 레포 클론 │ - tmux 세션 │ │ │ - 브랜치 생성 │ - 4개 pane │ │ │ - .env 설정 │ - 의존성 체크 │ │ │ - 포트 연동 │ │ │ ▼ ▼ │ │ ~\/work\/feature-x\/ runtime-feature-x 세션 │ └─────────────────────────────────────────────────────────────┘ ``` **연속 사용 예시:** ``` 사용자: 새 기능 개발 시작할게. 워크스페이스 만들고 서버 띄워줘 Claude: 1. [callabo-init 활성화] 워크스페이스 생성 중... .\/scripts\/init-callabo-workspace.sh ~\/work\/new-feature feature\/new ✅ 완료 2. [callabo-tmux 활성화] 서비스 시작 중... echo "" | .\/scripts\/run.sh ~\/work\/new-feature ✅ tmux 세션 'runtime-new-feature' 준비됨 ``` ### context-worktree와의 연동 context-worktree가 활성화된 경우: - 워크스페이스 전환 시 해당 워크스페이스의 tmux 세션 상태 확인 - 세션이 없으면 자동으로 callabo-tmux 실행 제안 - 세션이 있으면 기존 세션에 접속 안내 ``` 사용자: ~\/work\/other-feature로 전환해줘 Claude: [context-worktree + callabo-tmux 연동] 워크스페이스 전환: ~\/work\/other-feature tmux 세션 'runtime-other-feature'가 존재하지 않습니다. 서비스를 시작할까요? [Y\/n] ``` --- ## Resources | 항목 | 경로 | |------|------| | 실행 스크립트 | `.\/scripts\/run.sh` | | 서버 코드 | `\/callabo-server\/` | | 웹앱 코드 | `\/callabo-webapp\/` | | Magi 코드 | `\/magi\/` |