Formatted SKILL.md (raw) Package Files
Copy .md
name: docker-commands
description: "ICJC Docker 서비스 관리 및 Make 명령어. Use when: (1) docker, make, 컨테이너, 서비스, 재시작, 로그 관련 요청, (2) 백엔드/프론트엔드/에이전트 재시작, (3) 빌드, 컨테이너 접속, 로그 확인, 서비스 상태 확인 필요시."
Docker Commands Skill
ICJC 프로젝트의 Docker 서비스 관리를 위한 스킬입니다.
## 사용 시점
다음 키워드나 상황에서 이 스킬을 사용하세요:
"docker", "make", "컨테이너", "서비스", "재시작", "로그"
"백엔드 재시작", "프론트엔드 재시작", "빌드"
"컨테이너 접속", "로그 확인", "서비스 상태"
## 서비스 아키텍처
의존성 순서: 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 프론트엔드
## 명령어 레퍼런스
빠른 시작
명령어
설명
사용 시점
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
메모리 모니터링
## 환경 변수
변수
기본값
설명
FRONTEND_MODE
development
프론트엔드 모드
USER_ID
$(id -u)
컨테이너 사용자 ID
GROUP_ID
$(id -g)
컨테이너 그룹 ID
# 프로덕션 모드로 빌드
make build FRONTEND_MODE=production
## 일반적인 워크플로우
코드 변경 후 테스트
백엔드 변경 : make backend (빠른 재시작)
프론트엔드 변경 : Hot reload 자동 적용 (재시작 불필요)
Agent 변경 : make agents-light (빌드 없이 재시작)
의존성 변경 : make build (전체 재빌드)
문제 발생 시
로그 확인: make logs-backend 또는 make logs-frontend
컨테이너 상태: docker ps
앱만 재시작: make re-app
그래도 안되면: make down && make build
깨끗한 환경으로 시작
make fclean && make build
## 이 스킬 사용 시 지침
명령어 실행 전 상황 파악 : 사용자가 원하는 작업을 정확히 이해하고, 최소한의 영향을 주는 명령어를 선택하세요.
DB 보존 우선 : 가능하면 DB를 유지하는 명령어 (make backend, make re-app)를 먼저 시도하세요.
로그 확인 습관화 : 서비스 재시작 후 반드시 로그를 확인하여 정상 동작을 검증하세요.
purge 사용 주의 : make purge는 모든 Docker 리소스를 삭제합니다. 사용자에게 경고하세요.