설치 가이드

Caffeine Framework를 설치하고 개발 환경을 구성하는 방법을 안내합니다.

📋 사전 요구사항

필수 소프트웨어

소프트웨어	최소 버전	권장 버전	다운로드
.NET SDK	10.0	10.0	dotnet.microsoft.com
Docker	20.10	24.0	docker.com
Redis	6.0	7.2	redis.io
Git	2.30	2.43	git-scm.com

선택 소프트웨어

• InfluxDB 2.7+ (시계열 데이터 저장)
• Kafka 3.0+ (이벤트 스트리밍)
• Visual Studio 2022 또는 VS Code (IDE)

🚀 빠른 설치 (Windows)

1. .NET SDK 설치

# Winget 사용 (Windows 11)
winget install Microsoft.DotNet.SDK.10

# 또는 Chocolatey 사용
choco install dotnet-sdk -y

# 설치 확인
dotnet --version
# 출력: 10.0.x

2. Docker Desktop 설치

# Winget 사용
winget install Docker.DockerDesktop

# 설치 확인
docker --version
# 출력: Docker version 24.x.x

3. Caffeine CLI 설치

# NuGet에서 글로벌 도구 설치
dotnet tool install -g NEXCODE.Caffeine.Cli

# 설치 확인
cafe --version
# 출력: Caffeine CLI 2.1.0

4. 개발 환경 시작

cafe setup 위자드를 사용하면 한 번에 구성됩니다:

# 대화형 위자드 실행
cafe setup

위자드가 프로파일을 선택하게 안내합니다:

프로파일	서비스	권장 용도
minimal	Redis, MQTT	드라이버 개발만
standard	+ InfluxDB, Kafka	일반 개발 (권장)
full	+ TypeDB, Grafana	전체 기능 개발
app	+ Caffeine 앱	소스 없이 실행

# 서비스 상태 확인
cafe setup status

# 서비스 중지
cafe setup down

배포 파일 직접 접근: cafe setup extract로 docker-compose.yml을 현재 디렉토리에 추출할 수 있습니다.

🐧 Linux 설치

Ubuntu/Debian

# .NET SDK 설치
wget https://dot.net/v1/dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --channel 10.0

# Docker 설치
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

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

# 환경 변수 추가
echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.bashrc
source ~/.bashrc

CentOS/RHEL

# .NET SDK 설치
sudo dnf install dotnet-sdk-10.0

# Docker 설치
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io

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

🍎 macOS 설치

# Homebrew로 .NET SDK 설치
brew install --cask dotnet-sdk

# Docker Desktop 설치
brew install --cask docker

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

# 설치 확인
cafe --version

📦 소스에서 빌드

1. SDK 다운로드

라이선스 계약 후 Caffeine SDK를 제공받습니다. 받은 소스 패키지를 압축 해제하세요.

# 압축 해제 후 프로젝트 디렉토리로 이동
cd Caffeine

2. 의존성 복원

dotnet restore

3. 빌드

# 전체 솔루션 빌드
dotnet build

# Release 모드 빌드
dotnet build -c Release

4. 테스트

# 전체 테스트 실행
dotnet test

# 특정 프로젝트 테스트
dotnet test tests/Caffeine.Core.Tests

🔧 개발 환경 설정

Visual Studio 2022

1. 워크로드 설치:

   • ASP.NET 및 웹 개발
   • .NET 데스크톱 개발

2. 확장 프로그램 (권장):

   • ReSharper
   • CodeMaid
   • GitLens

3. 솔루션 열기:

   File → Open → Project/Solution
   → Caffeine.sln 선택

Visual Studio Code

1. 확장 프로그램 설치:

   code --install-extension ms-dotnettools.csharp
   code --install-extension ms-dotnettools.csdevkit
   code --install-extension ms-azuretools.vscode-docker

2. 작업 영역 열기:

   cd Caffeine
   code .

3. 디버그 구성 (.vscode/launch.json):

   {
     "version": "0.2.0",
     "configurations": [
       {
         "name": ".NET Core Launch (web)",
         "type": "coreclr",
         "request": "launch",
         "preLaunchTask": "build",
         "program": "${workspaceFolder}/src/Caffeine.Core/bin/Debug/net10.0/Caffeine.Core.dll",
         "cwd": "${workspaceFolder}/src/Caffeine.Core",
         "env": {
           "ASPNETCORE_ENVIRONMENT": "Development"
         }
       }
     ]
   }

🐳 Docker 환경 설정

cafe setup이 Docker 환경 구성을 자동으로 처리합니다. 배포 파일을 직접 다루어야 하는 경우:

# 배포 파일 현재 디렉토리에 추출
cafe setup extract

# 추출된 파일 확인
ls -la
# docker-compose.yml
# docker-compose.prod.yml
# .env.example

# .env 파일 생성 (위자드가 자동 처리하지만 수동 생성 시)
cp .env.example .env
# .env 편집하여 시크릿 설정

# 특정 프로파일 직접 실행
docker compose --profile standard up -d

자세한 Docker 설정은 Docker 배포 가이드를 참조하세요.

✅ 설치 확인

1. 환경 진단

# CLI 및 환경 진단
cafe doctor

# 배포 서비스 상태 확인 (cafe setup 실행 후)
cafe setup status

출력 예시:

✓ .NET SDK 10.0.0 설치됨
✓ Docker 24.0.6 실행 중
✓ Redis (localhost:6379) 연결 성공
✓ InfluxDB (localhost:8086) 연결 성공
✓ Kafka (localhost:9092) 연결 성공

모든 요구사항이 충족되었습니다! 🎉

2. 샘플 프로젝트 생성

# 드라이버 프로젝트 생성
cafe init --name TestDriver --template driver-full

# 빌드 및 테스트
cd TestDriver
dotnet build
dotnet test

성공 시 출력:

빌드 성공: 0 오류, 0 경고
테스트 통과: 10/10

🔍 문제 해결

.NET SDK 인식 안 됨

증상:

'dotnet' 용어가 cmdlet로 인식되지 않습니다.

해결:

# 환경 변수 새로고침
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

# PowerShell 재시작

Docker 연결 실패

증상:

Cannot connect to the Docker daemon

해결:

1. Docker Desktop 실행 확인
2. WSL 2 백엔드 활성화 (Windows)
3. Docker 서비스 재시작:

   sudo systemctl restart docker

Redis 연결 실패

증상:

No connection is available to service this operation

해결:

# Redis 컨테이너 확인
docker ps | grep redis

# Redis 재시작
docker restart caffeine-redis

# 연결 테스트
redis-cli ping
# 출력: PONG

📚 다음 단계

• 빠른 시작 가이드
• 배포 위자드 가이드 — cafe setup 전체 옵션
• 첫 번째 드라이버 만들기
• CLI 도구 사용법

🆘 추가 도움

• 문서: docs.nexcode.co.kr/caffeine
• 기술 지원: matrix@live.co.kr
• 공식 사이트: www.nexcode.co.kr

---

이전: ← 아키텍처 개요 | 다음: 빠른 시작 →