Docker Commands Skill

ICJC 프로젝트의 Docker 서비스 관리를 위한 스킬입니다.

<trigger_conditions>

사용 시점

다음 키워드나 상황에서 이 스킬을 사용하세요:

• "docker", "make", "컨테이너", "서비스", "재시작", "로그"
• "백엔드 재시작", "프론트엔드 재시작", "빌드"
• "컨테이너 접속", "로그 확인", "서비스 상태" </trigger_conditions>

<service_architecture>

서비스 아키텍처

의존성 순서: MongoDB (27017) → Redis (6379) → Backend (8000) → Agent Gateway (8100→8080) → Frontend (3000)

| 서비스 | 컨테이너명 | 외부포트 | 내부포트 | 설명 | |--------|-----------|---------|---------|------| | mongodb-primary | mongodb-primary-dev | 27017 | 27017 | MongoDB Atlas Local | | redis | redis-dev | 6379 | 6379 | Redis 캐시 | | backend | backend-dev | 8000 | 8000 | FastAPI 백엔드 | | agent-multi-gateway | agent-multi-gateway-dev | 8100 | 8080 | AI Agent Gateway | | frontend | frontend-dev | 3000 | 3000 | Next.js 프론트엔드 | </service_architecture>

<commands> ## 명령어 레퍼런스

빠른 시작

| 명령어 | 설명 | 사용 시점 | |--------|------|----------| | make build | 전체 빌드 및 실행 | 첫 실행, 의존성 변경 | | make all | 빌드 없이 실행 | 이미 빌드된 상태 | | make dev | Docker Watch 개발 모드 | 개발 중 |

개별 서비스

| 명령어 | 설명 | 영향 범위 | |--------|------|----------| | make backend | 백엔드 + Agent 재시작 | DB/Frontend 유지 | | make frontend | 프론트엔드 재시작 (dev) | Frontend만 | | make frontend-prod | 프론트엔드 (prod) | Frontend만 | | make agent | Agent Gateway만 실행 | Agent만 | | make agents | 모든 Agent 재빌드 | Agent 전체 | | make agents-light | 모든 Agent 재시작 (빌드X) | Agent 전체 | | make re-app | 앱 컨테이너만 재시작 | DB 유지 |

로그

| 명령어 | 대상 | |--------|------| | make logs | 전체 | | make logs-backend | 백엔드 | | make logs-frontend | 프론트엔드 | | make logs-agent | Agent Gateway | | make logs-mongo | MongoDB 초기화 | | docker logs -f backend-dev | 백엔드 (직접) | | docker logs -f --tail 100 frontend-dev | 프론트엔드 최근 100줄 |

컨테이너 접근

| 명령어 | 대상 | |--------|------| | docker exec -it backend-dev bash | 백엔드 | | docker exec -it frontend-dev sh | 프론트엔드 | | docker exec -it mongodb-primary-dev mongosh | MongoDB | | docker exec -it agent-multi-gateway-dev bash | Agent |

클린업

| 명령어 | 설명 | 주의 | |--------|------|------| | make down | 컨테이너 중지 + 볼륨 삭제 | 데이터 유지됨 | | make fclean | down + 이미지/네트워크 정리 | | | make purge | 모든 Docker 리소스 제거 | 매우 주의 |

MongoDB 관리

| 명령어 | 설명 | |--------|------| | make mongo | MongoDB 레플리카셋 테스트 | | make mongo-reset | MongoDB 완전 초기화 (데이터 삭제!) | | make mongo-backup-dev | Dev DB 백업 | | make mongo-restore | 백업 복원 | | make mongo-sync-dev | 백업 → 복원 | | make mongo-rebuild | 초기화 + 재시작 + 복원 |

문제 해결

| 명령어 | 설명 | |--------|------| | make fix-permissions | 파일 권한 문제 해결 | | make frontend-fix-next-perms | .next 볼륨 권한 수정 | | make mem-watch | 메모리 모니터링 | </commands>

<environment_variables>

환경 변수

| 변수 | 기본값 | 설명 | |------|--------|------| | FRONTEND_MODE | development | 프론트엔드 모드 | | USER_ID | $(id -u) | 컨테이너 사용자 ID | | GROUP_ID | $(id -g) | 컨테이너 그룹 ID |

# 프로덕션 모드로 빌드
make build FRONTEND_MODE=production

</environment_variables>

<workflows> ## 일반적인 워크플로우

코드 변경 후 테스트

1. 백엔드 변경: make backend (빠른 재시작)
2. 프론트엔드 변경: Hot reload 자동 적용 (재시작 불필요)
3. Agent 변경: make agents-light (빌드 없이 재시작)
4. 의존성 변경: make build (전체 재빌드)

문제 발생 시

1. 로그 확인: make logs-backend 또는 make logs-frontend
2. 컨테이너 상태: docker ps
3. 앱만 재시작: make re-app
4. 그래도 안되면: make down && make build

깨끗한 환경으로 시작

make fclean && make build

</workflows> <instructions> ## 이 스킬 사용 시 지침

1. 명령어 실행 전 상황 파악: 사용자가 원하는 작업을 정확히 이해하고, 최소한의 영향을 주는 명령어를 선택하세요.
2. DB 보존 우선: 가능하면 DB를 유지하는 명령어 (make backend, make re-app)를 먼저 시도하세요.
3. 로그 확인 습관화: 서비스 재시작 후 반드시 로그를 확인하여 정상 동작을 검증하세요.
4. purge 사용 주의: make purge는 모든 Docker 리소스를 삭제합니다. 사용자에게 경고하세요.

</instructions>