배포 위자드 (`cafe setup`)

cafe setup은 Caffeine 플랫폼을 한 줄로 배포할 수 있는 대화형 위자드입니다. Docker Compose 프로파일 선택, .env 자동 생성, Production 보안 검증, 원격 SSH 배포까지 단계적으로 안내합니다.

빠른 시작 (One-liner)

# 1. CLI 설치
dotnet tool install -g NEXCODE.Caffeine.Cli

# 2. 대화형 위자드 실행
cafe setup

30초 안에 Caffeine 개발 환경이 준비됩니다.

전제 조건

항목	요구사항
.NET SDK	10.0 이상
Docker	20.10 이상
Docker Compose	v2 (Docker Desktop에 포함)
SSH 키	원격 배포 시만 필요

워크플로우 (7단계)

단계별 설명

단계	설명
1. 사전 검증	Docker 설치 여부, 데몬 실행 여부, Compose v2 확인
2. 프로파일 선택	대화형 메뉴에서 5개 프로파일 중 선택
3. 포트 충돌 확인	선택한 프로파일의 포트 사용 현황 확인 (로컬만)
4. .env 생성	랜덤 시크릿으로 `.env` 파일 자동 생성
5. 보안 검증	`--mode production` 시 6개 항목 자동 검사
6. Compose 실행	`docker compose up -d --profile {name}` 실행
7. 완료	서비스 시작 확인 및 다음 명령어 안내

배포 프로파일

Caffeine은 용도에 따라 5가지 프로파일을 제공합니다.

프로파일 비교표

프로파일	용도	포함 서비스
`minimal`	드라이버 개발 최소 환경	Redis, MQTT Broker
`standard`	표준 개발환경 (권장)	+ InfluxDB, Kafka, Zookeeper
`full`	전체 기능 개발	+ TypeDB, Grafana
`full+monitoring`	운영 모니터링 포함	+ Prometheus
`app`	소스 없이 앱 실행	+ Caffeine Engine, Caffeine Admin

서비스별 포트 매핑

서비스	포트	프로파일
Redis	6379	모든 프로파일
MQTT Broker	1883, 9001	모든 프로파일
InfluxDB	8086	standard 이상
Kafka	9092	standard 이상
TypeDB	1729	full 이상
Grafana	3000	full 이상
Prometheus	9090	full+monitoring
Caffeine Engine API	5000, 5001	app
Caffeine Admin	8080	app

프로파일 선택 가이드

드라이버 개발만  → minimal
일반 개발       → standard (권장)
AI/그래프 기능  → full
운영 모니터링   → full+monitoring
앱 전체 실행    → app

서브커맨드

`cafe setup status` — 서비스 상태 확인

# 실행 중인 서비스 목록
cafe setup status

# HTTP /health 엔드포인트 폴링 포함
cafe setup status --health

# 원격 서비스 상태 확인
cafe setup status --remote ssh://user@192.168.1.100

출력 예시:

NAME                    STATUS          PORTS
caffeine-redis          running         6379->6379/tcp
caffeine-influxdb       running         8086->8086/tcp
caffeine-kafka          running         9092->9092/tcp

`cafe setup down` — 서비스 중지

# 로컬 서비스 중지
cafe setup down

# 원격 서비스 중지
cafe setup down --remote ssh://user@192.168.1.100

`cafe setup extract` — 배포 리소스 추출

CLI에 내장된 docker-compose.yml, .env.example 등의 배포 파일을 현재 디렉토리에 추출합니다.

# 현재 디렉토리에 추출
cafe setup extract

# 특정 경로에 추출
cafe setup extract --output ./deploy

# 특정 프로파일 파일만 추출
cafe setup extract --profile minimal

# 기존 파일 덮어쓰기
cafe setup extract --force

# 내장 리소스 목록만 확인
cafe setup extract --list

원격 배포 (`--remote`)

SSH를 통해 원격 서버에 Caffeine을 배포합니다. Docker Context를 자동으로 생성하여 원격 Docker 데몬을 직접 제어합니다.

사전 조건

원격 서버에 Docker가 설치되어 있어야 합니다
SSH 키 기반 인증이 설정되어 있어야 합니다

# SSH 키 생성 (없는 경우)
ssh-keygen -t ed25519 -C "caffeine-deploy"

# 원격 서버에 공개 키 복사
ssh-copy-id user@192.168.1.100

원격 배포 실행

# 원격 서버에 배포 (위자드 + SSH context 자동 생성)
cafe setup --remote ssh://user@192.168.1.100

# 포트 지정
cafe setup --remote ssh://user@192.168.1.100:22

# Production 모드로 원격 배포
cafe setup --remote ssh://user@192.168.1.100 --mode production

# 원격 서비스 상태 확인
cafe setup status --remote ssh://user@192.168.1.100

# 원격 서비스 중지
cafe setup down --remote ssh://user@192.168.1.100

동작 방식

원격 context 이름은 --remote URL에서 자동 유도됩니다 (예: ssh://user@192.168.1.100 → caffeine-192-168-1-100). 배포 성공 후 .caffeine-context 파일에 저장되어 이후 status/down 명령에서 자동으로 재사용됩니다.

Production 배포 (`--mode production`)

cafe setup --mode production

Production 모드에서는 Docker Compose 실행 전에 6개 보안 항목을 자동 검증합니다.

보안 체크리스트

항목	검증 내용	통과 기준
`.env 파일 존재`	`.env` 파일 있는지 확인	파일 존재
`JWT Secret 강도`	JWT_SECRET 길이 확인	44자 이상 (Base64 32바이트+)
`기본 비밀번호 미사용`	`admin123`, `changeme` 등 취약 패턴 탐지	취약 패턴 없음
`CAFFEINE_ENV=production`	환경 변수 값 확인	`production` 설정됨
`TLS 인증서 존재`	`.pfx` 인증서 파일 확인	`caffeine.pfx` 존재
`Docker 데몬 실행`	Docker 데몬 상태 확인	실행 중

보안 항목 실패 시 경고와 함께 계속 진행 여부를 묻습니다.

Production 오버레이

docker-compose.prod.yml이 존재하면 자동으로 적용됩니다:

컨테이너 리소스 제한 (CPU, 메모리)
로그 로테이션 (10MB, 최대 5개)
재시작 정책 (on-failure:5)
Production 환경 변수 오버라이드

`.env` 파일 자동 생성

위자드 실행 중 .env 파일이 없으면 자동 생성 여부를 묻습니다. 자동 생성 시 모든 시크릿이 RandomNumberGenerator를 사용하여 암호학적으로 안전하게 생성됩니다.

생성되는 주요 변수:

# 자동 생성 예시 (.env)
CAFFEINE_ENV=development
JWT_SECRET=<44자 Base64 랜덤>
INFLUXDB_ADMIN_TOKEN=<44자 Base64 랜덤>
INFLUXDB_ADMIN_PASSWORD=<22자 랜덤>
REDIS_PASSWORD=<22자 랜덤>
KAFKA_CLUSTER_ID=<22자 랜덤>

주의

.env 파일에는 민감한 시크릿이 포함됩니다. .gitignore에 추가하여 소스 컨트롤에 포함되지 않도록 하세요.

echo ".env" >> .gitignore

전체 옵션 참조

`cafe setup` (위자드)

옵션	단축키	기본값	설명
`--mode`	`-m`	`development`	배포 모드 (`development` \| `production`)
`--remote`	—	—	원격 Docker SSH URL (예: `ssh://user@host`)

`cafe setup status`

옵션	단축키	기본값	설명
`--health`	`-H`	`false`	HTTP `/health` 엔드포인트 폴링
`--remote`	—	—	원격 Docker SSH URL

`cafe setup down`

옵션	단축키	기본값	설명
`--remote`	—	—	원격 Docker SSH URL

`cafe setup extract`

옵션	단축키	기본값	설명
`--output`	`-o`	현재 디렉토리	추출 대상 경로
`--force`	`-f`	`false`	기존 파일 덮어쓰기
`--list`	`-l`	`false`	리소스 목록만 표시
`--profile`	`-p`	—	특정 프로파일 파일만 추출

문제 해결

Docker를 찾을 수 없음

❌ Docker: 설치되지 않았습니다

해결: Docker 공식 사이트에서 Docker Desktop을 설치합니다.

Docker 데몬이 실행되지 않음

❌ Docker 데몬: 실행되지 않습니다

해결: Docker Desktop을 시작하거나 Linux에서 sudo systemctl start docker를 실행합니다.

`docker-compose.yml`을 찾을 수 없음

❌ docker-compose.yml을 찾을 수 없습니다.

해결: 먼저 배포 파일을 추출한 후 실행합니다:

cafe setup extract
cafe setup

SSH 연결 실패

❌ 원격 Docker 연결 실패: ssh://user@host

해결 순서:

SSH 연결 직접 테스트: ssh user@host
원격 Docker 데몬 확인: ssh user@host docker ps
SSH 키 확인: ssh-add -l

다음 단계

Docker 배포 가이드 — 고급 Docker 설정
CLI 명령어 참조 — 전체 명령어 매뉴얼
튜토리얼: Production 배포 — 실전 배포 예시

빠른 시작 (One-liner)​

전제 조건​

워크플로우 (7단계)​

단계별 설명​

배포 프로파일​

프로파일 비교표​

서비스별 포트 매핑​

프로파일 선택 가이드​

서브커맨드​

cafe setup status — 서비스 상태 확인​

cafe setup down — 서비스 중지​

cafe setup extract — 배포 리소스 추출​

원격 배포 (--remote)​

사전 조건​

원격 배포 실행​

동작 방식​

Production 배포 (--mode production)​

보안 체크리스트​

Production 오버레이​

.env 파일 자동 생성​

전체 옵션 참조​

cafe setup (위자드)​

cafe setup status​

cafe setup down​

cafe setup extract​

문제 해결​

Docker를 찾을 수 없음​

Docker 데몬이 실행되지 않음​

docker-compose.yml을 찾을 수 없음​

SSH 연결 실패​

다음 단계​