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> |
빠른 시작
| 명령어 | 설명 | 사용 시점 |
|---|---|---|
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 | 메모리 모니터링 |
<environment_variables>
환경 변수
| 변수 | 기본값 | 설명 |
|---|---|---|
| FRONTEND_MODE | development | 프론트엔드 모드 |
| USER_ID | $(id -u) | 컨테이너 사용자 ID |
| GROUP_ID | $(id -g) | 컨테이너 그룹 ID |
bash
# 프로덕션 모드로 빌드 make build FRONTEND_MODE=production
</environment_variables>
<workflows> ## 일반적인 워크플로우코드 변경 후 테스트
- •백엔드 변경:
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
깨끗한 환경으로 시작
bash
make fclean && make build
- •명령어 실행 전 상황 파악: 사용자가 원하는 작업을 정확히 이해하고, 최소한의 영향을 주는 명령어를 선택하세요.
- •DB 보존 우선: 가능하면 DB를 유지하는 명령어 (
make backend,make re-app)를 먼저 시도하세요. - •로그 확인 습관화: 서비스 재시작 후 반드시 로그를 확인하여 정상 동작을 검증하세요.
- •purge 사용 주의:
make purge는 모든 Docker 리소스를 삭제합니다. 사용자에게 경고하세요.