docker-commands

ICJC Docker 서비스 관리 및 Make 명령어. Use when: (1) docker, make, 컨테이너, 서비스, 재시작, 로그 관련 요청, (2) 백엔드/프론트엔드/에이전트 재시작, (3) 빌드, 컨테이너 접속, 로그 확인, 서비스 상태 확인 필요시.

⭐3stars🔀1forks📁View on GitHub🕐Updated Jan 6, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive interface for managing the ICJC project's Docker-based microservices architecture. It streamlines local development and DevOps workflows by automating complex Docker and Make commands for service orchestration, real-time log monitoring, and database administration. By abstracting container management, it allows developers to focus on coding while ensuring environment consistency across the backend, frontend, and AI agent gateways.

Use Cases

  • Service Orchestration: Quickly restart specific components like the FastAPI backend or Next.js frontend without disrupting the entire stack, ideal for testing incremental code changes.
  • Environment Troubleshooting: Monitor real-time logs across multiple containers and access container shells (bash/sh) to debug integration issues or service failures.
  • Database Lifecycle Management: Automate MongoDB operations including replica set initialization, data backups, restorations, and full database resets for clean testing environments.
  • Resource & Permission Management: Resolve common environment bottlenecks using specialized commands for memory monitoring and fixing volume-related file permissions.
  • Rapid Environment Setup: Execute full project builds and cleanups (fclean/purge) to ensure a consistent and reproducible development environment from scratch.
namedocker-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
## 일반적인 워크플로우

코드 변경 후 테스트

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