| 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 리소스를 삭제합니다. 사용자에게 경고하세요.