설치 가이드

NuFi 플랫폼은 Zarf를 사용하여 폐쇄망(Air-gapped) 환경에 배포됩니다. 설치 번들을 대상 서버에 전송한 뒤 스크립트를 실행하면 K3s 클러스터 생성부터 플랫폼 배포까지 자동으로 진행됩니다.

사전 준비

항목	요구사항
OS	Ubuntu 22.04+ (x86_64)
CPU	4코어 이상
RAM	16GB 이상
디스크	200GB 이상
GPU (선택)	NVIDIA 드라이버 575.51.03 이상 / CUDA 12.9 이상

정보

NVIDIA GPU를 사용하는 경우 NVIDIA 드라이버만 사전 설치하면 됩니다. NVIDIA Container Toolkit은 설치 번들에 포함되어 자동 설치됩니다.

설치 절차

1. 번들 전송

설치 번들 디렉토리를 대상 서버에 전송합니다 (USB, SCP 등).

nufi/
├── .env                          # 환경 설정
├── install.sh                    # 설치 스크립트
├── zarf                          # Zarf 바이너리
├── zarf-init-*.tar.zst           # Zarf Init 패키지 (K3s 포함)
├── nufi-amd64-*.tar.zst          # NuFi 플랫폼 패키지
├── realm-export.json             # Keycloak 설정
├── nvidia-container-toolkit/     # NVIDIA CTK 패키지 (deb)
├── models/                       # AI 모델 캐시
└── docs/
    └── install-guide.md
    └── dns-setup-guide.md

2. 환경 설정

.env 파일을 편집합니다:

BASE_DOMAIN=nufi.com          # 서비스 도메인
PASSWORD=nufi1234             # Keycloak, Grafana 공통 비밀번호
PROTOCOL=http                 # http 또는 https
NUFI_VERSION=0.1.0            # 배포할 NuFi 버전

변수	설명	예시
BASE_DOMAIN	서비스 접속에 사용할 도메인. 설치 후 dashboard.{도메인}, grafana.{도메인} 등의 서브도메인으로 접속합니다. 도메인을 변경한 경우 docs/dns-setup-guide.md의 DNS 설정도 변경된 도메인에 맞게 진행해야 합니다.	nufi.com
PASSWORD	Keycloak 관리자 및 Grafana 관리자 공통 비밀번호	nufi1234
PROTOCOL	서비스 프로토콜. TLS 인증서가 준비된 경우 https, 아닌 경우 http	http
NUFI_VERSION	배포할 NuFi 플랫폼 버전. 번들 디렉토리 내 nufi-amd64-*.tar.zst 파일의 버전과 일치해야 합니다.	0.1.0

3. 설치 실행

sudo ./install.sh

레지스트리 설정

NuFi는 Zarf 내장 레지스트리만 사용합니다. 설치 시 자동으로 클러스터 내부에 경량 레지스트리가 구성됩니다.

커스텀 외부 이미지

외부에서 가져온 컨테이너 이미지를 사용하려면 설치 후 Admin > External Images 메뉴에서 docker save로 만든 tar 파일을 업로드하세요. 업로드된 이미지는 내부 레지스트리로 자동 import되며, Serving/Lab 생성 시 선택할 수 있습니다. 자세한 내용은 External Images 관리를 참고하세요.

설치 진행 단계

sudo ./install.sh 실행 후 자동으로 진행됩니다:

[1/8] Zarf 설치
[2/8] 시스템 설정 (+ NVIDIA Container Toolkit 설치)
[3/8] AI 모델 캐시 배포
[4/8] K3s 클러스터 생성 (zarf init)
[5/8] NuFi Platform 배포
[6/8] CoreDNS rewrite 규칙 추가
[7/8] Keycloak Realm Import
[8/8] 최종 상태

단계	설명
Zarf 설치	Zarf CLI 바이너리를 시스템에 설치
시스템 설정	swap 비활성화, 포트 설정, NVIDIA CTK 설치 (GPU 서버)
AI 모델 캐시 배포	번들 포함 모델을 /mnt/data/cache/huggingface/hub/에 배포
K3s 클러스터 생성	zarf init으로 K3s + Flannel CNI + 내장 레지스트리를 한 번에 구성
NuFi Platform 배포	Prometheus, JuiceFS 등 NUFI 관련 전체 스택 배포
CoreDNS rewrite	*.{도메인} 요청을 Istio Ingress Gateway로 라우팅
Keycloak Realm Import	인증 Realm 및 기본 사용자(admin) 생성

팁

NVIDIA GPU가 감지되면 containerd nvidia runtime 설정 및 RuntimeClass가 자동 구성됩니다.

설치 완료

설치가 완료되면 접속 정보가 출력됩니다:

접속 URL:
  Dashboard: http://dashboard.nufi.com
  Grafana:   http://grafana.nufi.com
  Keycloak:  http://keycloak.nufi.com

기본 계정: admin / <설정한 비밀번호>

노트

.env에서 설정한 BASE_DOMAIN과 PROTOCOL에 따라 실제 URL이 결정됩니다.

경고

설치 완료 후 접속하려면 클라이언트 PC에서 DNS 설정이 필요합니다. DNS 설정 가이드를 참고하여 진행하세요.