배포 위자드 (`cafe setup`)

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

빠른 시작 (One-liner)

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

# 2. 배포 파일 추출 (최초 1회)
cafe setup extract

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

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

전제 조건

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

워크플로우 (7단계)

단계별 설명

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

배포 프로파일

Caffeine은 용도에 따라 6가지 프로파일을 제공합니다. 개발 환경(인프라만 기동, 소스 코드 직접 실행)과 배포 환경(Docker 이미지 기반)으로 구분됩니다.

프로파일 비교표

🔧 개발 환경 — 인프라 서비스만 기동, 소스 코드를 직접 빌드·실행

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

🚀 배포 환경 — Docker 이미지 기반, 소스 코드 불필요

프로파일	용도	포함 서비스
`server`	중앙 서버 통합 배포	인프라 + Caffeine Engine, Admin, Bridge, Simulator
`edge`	엣지 — Docker 컨테이너	Redis, MQTT + Bridge.Host Docker (ENGINE_URL 수동 연결)
`edge-native`	엣지 — Runtime 실행 파일	Redis, MQTT Docker + Bridge.Host 네이티브 (mDNS 자동 검색)

서비스별 포트 매핑

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

Edge 배포: Docker vs Runtime 비교

	Edge — Docker	Edge — Runtime
Bridge 실행	Docker 컨테이너	네이티브 프로세스
mDNS 자동 검색	❌ 불가 (Docker 멀티캐스트 격리)	✅ 지원
Engine 연결	`ENGINE_URL` 수동 설정 필수	mDNS 자동 또는 수동
관리 편의성	`docker compose`로 관리	systemd / 수동 관리
OS 의존성	Docker만 필요	.NET 10 Runtime 필요

Edge Docker 환경변수

edge 프로파일(Docker)은 Engine에 수동 연결하기 위해 .env를 설정합니다:

환경변수	기본값	설명
`ENGINE_URL`	`http://host.docker.internal:5000`	중앙 Engine gRPC 주소
`EDGE_DEVICE_ID`	`Edge-01`	엣지 디바이스 식별자
`EDGE_DRIVER_TYPE`	`Simulation`	드라이버 타입

Edge Runtime 양방향 mDNS 자동 검색

edge-native 프로파일(Runtime)은 Bridge.Host를 네이티브로 실행하므로 양방향 mDNS 자동 검색이 동작합니다:

Engine → Bridge 검색 (Admin Bridge Discovery):

Engine이 _caffeine-engine._tcp 서비스를 mDNS로 광고
Bridge.Host가 _caffeine-bridge._tcp 서비스를 mDNS로 광고
Admin → Bridge Discovery → "스캔" 버튼으로 Bridge 발견 + 바인딩

Bridge → Engine 자동 검색 (ENGINE_URL 불필요):

Bridge.Host 시작 시 _caffeine-engine._tcp를 mDNS로 검색 (최대 3회, 5초 간격)
Engine 발견 → gRPC URL 자동 설정 (.env ENGINE_URL 설정 불필요!)
Engine 미발견 → ENGINE_URL 환경변수로 fallback

⚠️ mDNS는 같은 L2 서브넷에서만 동작합니다. 고객 시연 시 휴대용 공유기/핫스팟으로 같은 네트워크를 보장하세요. mDNS 실패 시 Admin에서 IP를 수동 입력하거나, ENGINE_URL 환경변수를 설정하세요.

오프라인 팩 Runtime 바이너리

publish_pack.sh --runtime <RID>로 팩에 Bridge.Host self-contained 바이너리를 포함할 수 있습니다:

# Linux x64 바이너리 포함
./scripts/publish_pack.sh --runtime linux-x64

# Linux ARM64 (Raspberry Pi 등)
./scripts/publish_pack.sh --runtime linux-arm64

# Windows x64
./scripts/publish_pack.sh --runtime win-x64

팩 내부에 bridge-host/<RID>/ 디렉토리로 self-contained 단일 실행 파일이 포함됩니다. .NET Runtime 설치 없이 Edge PC에서 직접 실행 가능합니다.

프로파일 선택 가이드

드라이버 개발만         → minimal
일반 개발              → standard (권장)
AI/그래프 기능         → full
운영 모니터링          → full+monitoring
중앙 서버 Docker 배포  → server
엣지 Docker 배포       → edge         (ENGINE_URL 수동 설정)
엣지 Runtime 배포      → edge-native  (mDNS 자동 검색 ✅)

서브커맨드

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

실행 위치

cafe setup status는 docker-compose.yml이 있는 디렉터리에서 실행해야 합니다. 일반적으로 deploy/ 디렉터리이며, 파일이 없는 경우 cafe setup extract로 먼저 추출하세요.

cd deploy/
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

`cafe setup clean` — 배포 환경 정리/초기화

Docker 컨테이너, 볼륨, 런타임 데이터를 단계적으로 정리합니다. 파괴적 작업이므로 현재 상태를 표시한 뒤 사용자 확인(기본값 No)을 받습니다.

# 기본: 컨테이너 + 볼륨 + caffeine-data/ 삭제
cafe setup clean

# 전체: + .env 파일 + NuGet CaffeineOffline 소스 해제
cafe setup clean --all

# 원격 서버 대상
cafe setup clean --remote ssh://user@192.168.1.100

⚠️ --all 옵션은 .env 파일(시크릿 포함)을 삭제합니다. 재설치 시 cafe setup으로 시크릿을 재생성해야 합니다.

원격 배포 (`--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 배포 — 실전 배포 예시
오프라인 배포 가이드 — cafe setup --source로 오프라인 설치

빠른 시작 (One-liner)​

전제 조건​

워크플로우 (7단계)​

단계별 설명​

배포 프로파일​

프로파일 비교표​

서비스별 포트 매핑​

Edge 배포: Docker vs Runtime 비교​

Edge Docker 환경변수​

Edge Runtime 양방향 mDNS 자동 검색​

오프라인 팩 Runtime 바이너리​

프로파일 선택 가이드​

서브커맨드​

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

cafe setup down — 서비스 중지​

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

cafe setup clean — 배포 환경 정리/초기화​

원격 배포 (--remote)​

사전 조건​

원격 배포 실행​

동작 방식​

Production 배포 (--mode production)​

보안 체크리스트​

Production 오버레이​

.env 파일 자동 생성​

전체 옵션 참조​

cafe setup (위자드)​

cafe setup status​

cafe setup down​

cafe setup extract​

문제 해결​

Docker를 찾을 수 없음​

Docker 데몬이 실행되지 않음​

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

SSH 연결 실패​

다음 단계​