오프라인 배포 가이드

인터넷이 없는 엣지 PC, 폐쇄망, 외부 개발자 환경에서 Caffeine 플랫폼을 완전히 오프라인으로 설치하는 방법을 안내합니다.

📋 개요

Caffeine 오프라인 배포 팩은 NuGet 패키지 + Docker 이미지 + 배포 설정 파일을 하나의 압축 파일로 묶어, USB 메모리나 파일 전송만으로 전체 환경을 구성할 수 있게 합니다.

[개발 머신 — 인터넷 O]                    [타겟 머신 — 인터넷 X]
  publish_pack.sh 실행                     cafe setup --source 실행
    ↓                                        ↓
  caffeine-pack-3.x.x.tar.gz   →USB/SCP→   NuGet 소스 등록
  (NuGet + Docker + 설정 파일)               Docker 이미지 로드
                                             서비스 시작

📋 사전 요구사항

타겟 머신 (설치할 PC)

항목	Windows	Linux
.NET 10 SDK	dotnet.microsoft.com	`sudo apt install dotnet-sdk-10.0`
Docker	Docker Desktop (WSL2)	Docker Engine 20.10+
Caffeine CLI	팩에 포함 (오프라인 설치)	팩에 포함 (오프라인 설치)

개발 머신 (팩을 생성할 PC)

.NET 10 SDK + Docker + 인터넷 연결

🚀 빠른 시작 (3단계)

Step 1: 배포 팩 생성 (인터넷 있는 PC)

Caffeine CLI 설치

팩 생성은 스크립트로 수행하므로 CLI가 필수는 아닙니다.

dotnet tool install -g NEXCODE.Caffeine.Cli

Linux/macOS:

# Caffeine 소스 디렉토리에서 실행
./scripts/publish_pack.sh

# 프로파일 지정 (기본: standard)
./scripts/publish_pack.sh -p full -o ~/Packs

Windows (PowerShell):

.\scripts\publish_pack.ps1

# 프로파일 지정
.\scripts\publish_pack.ps1 -Profile full -Output ~\Packs

생성되는 파일:

Linux/macOS: caffeine-pack-{version}.tar.gz
Windows: caffeine-pack-{version}.zip

Step 2: 팩 전송

생성된 압축 파일을 타겟 머신으로 전송합니다:

# SCP로 전송
scp packs/caffeine-pack-3.2.0.tar.gz user@edge-pc:~/

# 또는 USB 메모리에 복사
cp packs/caffeine-pack-3.2.0.tar.gz /Volumes/USB/

Step 3: 오프라인 설치 (타겟 PC)

# 1. Caffeine CLI 오프라인 설치 (최초 1회)
tar xzf caffeine-pack-3.2.0.tar.gz    # 또는 ZIP 해제
dotnet tool install -g NEXCODE.Caffeine.Cli \
  --add-source ./caffeine-pack-3.2.0/tools

# 2. 원클릭 설치 + 서비스 시작
cafe setup --source caffeine-pack-3.2.0.tar.gz

cafe setup --source가 자동으로 수행하는 작업:

압축 해제 (tar.gz/zip 자동 감지)
NuGet 로컬 소스 등록 (CaffeineOffline)
Docker 이미지 로드 (Caffeine 앱 + 인프라, macOS ._ 리소스 포크 파일 자동 제외)
배포 파일 복사 (docker-compose.yml 등)
.env에 CAFFEINE_VERSION 자동 기록 (팩 버전과 Docker 이미지 태그 자동 일치)
대화형 위자드로 프로파일 선택 → 서비스 시작

팩 생성 시 각 이미지에 버전 태그 + :latest 태그가 모두 포함됩니다. CAFFEINE_VERSION 미설정 시 :latest로 폴백하므로, 기존 .env가 있어도 정상 동작합니다.

📦 배포 팩 구성

내부 구조

caffeine-pack-3.2.0/
├── manifest.json                    # 팩 메타데이터
├── nuget/                           # NuGet 패키지 (30개)
│   ├── NEXCODE.Caffeine.Core.3.2.0.nupkg
│   ├── NEXCODE.Caffeine.Client.3.2.0.nupkg
│   └── ...
├── images/                          # Docker 이미지
│   ├── caffeine-apps.tar            # Engine, Admin, Bridge, Simulator
│   └── infrastructure.tar           # Redis, MQTT, InfluxDB, Kafka 등
├── deploy/                          # 배포 설정 파일
│   ├── docker-compose.yml
│   ├── mosquitto.conf
│   └── ...
└── tools/                           # Caffeine CLI
    └── NEXCODE.Caffeine.Cli.3.2.0.nupkg

manifest.json 예시

{
  "version": "3.2.0",
  "createdAt": "2026-03-27T00:00:00Z",
  "profile": "standard",
  "nugetPackages": 30,
  "caffeineImages": [
    "nexcode/caffeine-engine:3.2.0",
    "nexcode/caffeine-admin:3.2.0",
    "nexcode/caffeine-bridge-host:3.2.0",
    "nexcode/caffeine-simulator:3.2.0"
  ],
  "infrastructureImages": [
    "redis:alpine",
    "eclipse-mosquitto:2.0",
    "influxdb:2.7",
    "confluentinc/cp-zookeeper:7.4.0",
    "confluentinc/cp-kafka:7.4.0"
  ]
}

🔧 cafe setup --source 옵션

기본 사용법

# tar.gz 파일 직접 지정
cafe setup --source caffeine-pack-3.2.0.tar.gz

# ZIP 파일 (Windows에서 생성된 팩)
cafe setup --source caffeine-pack-3.2.0.zip

# 이미 압축 해제된 디렉토리
cafe setup --source ./caffeine-pack-3.2.0/

다른 옵션과 결합

# 프로덕션 모드 + 오프라인 팩
cafe setup --source pack.tar.gz --mode production

# 원격 SSH + 오프라인 팩
cafe setup --source pack.tar.gz --remote ssh://user@edge-pc

💡 프로파일별 이미지 목록

팩 생성 시 프로파일에 따라 포함되는 이미지가 달라집니다:

프로파일	Caffeine 이미지 (4개 고정)	외부 이미지	대략적 크기
`minimal`	Engine, Admin, Bridge, Simulator	Redis, MQTT	~1.5 GB
`standard`	〃	+ InfluxDB, Zookeeper, Kafka	~3.0 GB
`full`	〃	+ TypeDB, Qdrant, Grafana, Prometheus, AlertManager	~5.0 GB

# minimal (드라이버 개발용)
./scripts/publish_pack.sh -p minimal

# standard (일반 개발 — 권장)
./scripts/publish_pack.sh -p standard

# full (전체 기능)
./scripts/publish_pack.sh -p full

Caffeine 이미지만 (외부 이미지 제외)

인터넷이 되지만 Caffeine 이미지만 로컬 배포하고 싶을 때:

./scripts/publish_pack.sh --caffeine-images-only

🔧 수동 설치 (cafe CLI 없이)

cafe setup --source를 사용할 수 없는 환경에서 수동으로 설치하는 방법:

# 1. 압축 해제
tar xzf caffeine-pack-3.2.0.tar.gz
cd caffeine-pack-3.2.0

# 2. NuGet 로컬 소스 등록
dotnet nuget add source "$(pwd)/nuget" -n CaffeineOffline

# 3. Caffeine CLI 설치
dotnet tool install -g NEXCODE.Caffeine.Cli --add-source "$(pwd)/tools"

# 4. Docker 이미지 로드
docker load -i images/caffeine-apps.tar
docker load -i images/infrastructure.tar

# 5. 배포 파일 복사
cp -r deploy/* ~/Works/

# 6. 서비스 시작
cd ~/Works
cafe setup

🔍 문제 해결

Docker 이미지 로드 실패

증상: docker load 시 에러

해결:

# Docker 데몬 실행 확인
docker info

# 디스크 공간 확인 (이미지가 큼)
df -h

# 수동으로 개별 이미지 로드
docker load -i images/caffeine-apps.tar
docker load -i images/infrastructure.tar

NuGet 소스 등록 실패

증상: dotnet nuget add source 시 "source already exists"

해결:

# 기존 소스 제거 후 재등록
dotnet nuget remove source CaffeineOffline
dotnet nuget add source "$(pwd)/nuget" -n CaffeineOffline

팩 포맷 불일치

증상: Windows에서 생성한 .zip을 Linux에서 사용 (또는 반대)

해결: cafe setup --source는 .tar.gz와 .zip 모두 자동 감지합니다. 포맷에 관계없이 사용 가능합니다.

버전 불일치

증상: 팩 버전과 기존 설치 버전이 다름

해결:

# 팩 버전 확인
cat caffeine-pack-3.2.0/manifest.json | grep version

# 기존 CLI 업데이트
dotnet tool update -g NEXCODE.Caffeine.Cli --add-source ./caffeine-pack-3.2.0/tools

📚 참고 자료

설치 가이드 — 온라인 환경 설치
배포 위자드 가이드 — cafe setup 전체 옵션
Docker 배포 가이드 — Docker Compose 프로파일 상세
CLI 명령어 참조 — cafe CLI 전체 명령어

📋 개요​

📋 사전 요구사항​

타겟 머신 (설치할 PC)​

개발 머신 (팩을 생성할 PC)​

🚀 빠른 시작 (3단계)​

Step 1: 배포 팩 생성 (인터넷 있는 PC)​

Step 2: 팩 전송​

Step 3: 오프라인 설치 (타겟 PC)​

📦 배포 팩 구성​

내부 구조​

manifest.json 예시​

🔧 cafe setup --source 옵션​

기본 사용법​

다른 옵션과 결합​

💡 프로파일별 이미지 목록​

Caffeine 이미지만 (외부 이미지 제외)​

🔧 수동 설치 (cafe CLI 없이)​

🔍 문제 해결​

Docker 이미지 로드 실패​

NuGet 소스 등록 실패​

팩 포맷 불일치​

버전 불일치​

📚 참고 자료​