# 오프라인 번들 설치

> 오프라인 릴리스 번들로 에어갭 사이트에 Xisom Edge AI Box를 설치합니다 — 이미지 로드, 설치 프로그램 실행, 시크릿 설정, 스택 기동, 헬스 검증까지.

이것은 **인터넷, 레지스트리 접근, 박스에서의 이미지 빌드가 모두 불필요한** 상태로 고객
엣지 사이트에 설치하는 권장 방법입니다. USB 미디어로 제공되는 단일 자가 완결형
**릴리스 번들**에서 모든 것을 설치합니다.

**이 페이지를 사용해야 하는 경우**

공장이나 OT 사이트의 프로덕션 엣지 박스에는 오프라인 번들을 사용하세요. 인터넷이 있는
노트북에서 빠르게 평가하려면 [빠른 시작](/ko/install-deploy/quickstart/)이 더 빠릅니다.

## 받게 되는 것

릴리스 번들은 하드웨어 프로필과 버전으로 이름 지어진 하나의 디렉터리입니다
(예: `amd64-cpu-v1.5.0`). 하드웨어에 맞는 번들을 선택하세요:

| 번들 프로필 | 박스가 다음에 해당할 때 사용 |
|----------------|---------------------------|
| `amd64-cpu`    | x86_64 CPU, GPU 없음 — CPU 전용 추론 |
| `amd64-gpu`    | x86_64 CPU + NVIDIA GPU — TensorRT 가속 |
| `jetson`       | NVIDIA Jetson (arm64 / L4T) 엣지 모듈 |

번들 내부:

- amd64-cpu-v1.5.0/
  - images/
    - amd64-cpu-v1.5.0.images.tar.zst   세 개의 서비스 이미지, 압축됨
    - manifest.txt                       이미지 태그 + 체크섬
  - compose/
    - docker-compose.release.yml         이미지 기반 스택 (빌드 단계 없음)
    - .env.template                      포트 + 시크릿 자리표시자
  - models/
    - predictive_maintenance.onnx        데모 시드 모델 (랜덤 가중치)
  - install.sh
  - update.sh
  - uninstall.sh
  - README.txt                           운영자용 한 페이지 안내서

**시드 모델은 데모용입니다**

번들에 포함된 모델은 랜덤 가중치를 가지므로 — 학습된 모델로 교체하기 전까지 예측값은
무의미합니다. 아래 설치 런북의 5단계를 참조하세요.

## 시작하기 전에

대상 박스에는 다음이 이미 설치되어 있어야 합니다(골든 OS 이미지에 함께 제공됩니다 —
설치 프로그램은 이를 **확인**하고 누락된 것이 있으면 중단합니다. 대신 설치해 주지는
않습니다):

- `docker compose` v2 플러그인을 갖춘 Docker Engine 20.10 이상
- `zstd` 및 `openssl`
- **NVIDIA Container Toolkit** — GPU 및 Jetson 번들에만 해당

**깨끗한 대상**에 설치하세요. 릴리스 스택은 개발 스택과 동일한 컨테이너 이름, 볼륨,
호스트 포트를 재사용합니다 — Xisom이 이미 실행 중인 박스에서 실행하면 충돌합니다.

## 설치 런북

1. ### 번들을 박스로 복사

   USB 미디어에서 번들 디렉터리 전체를 대상 박스로 복사한 뒤 그 안에서 터미널을
   엽니다:

   ```bash
   cd amd64-cpu-v1.5.0/
   ```

2. ### 설치 프로그램 실행

   설치 프로그램은 하드웨어 프로필을 자동 감지하고, 컨테이너 이미지를 로드하며,
   시크릿을 생성하고, 스택을 기동한 뒤 헬스 상태를 기다립니다.

   ```bash
   sudo ./install.sh
   ```

   특정 프로필을 강제하거나, 부팅 시 시작 서비스도 함께 설치하려면:

   ```bash
   sudo ./install.sh --profile amd64-cpu   # 프로필 강제 지정
   sudo ./install.sh --with-systemd        # 부팅 시 시작도 설정
   ```

   내부적으로 `install.sh`는 다음 단계를 순서대로 실행합니다:

   1. **사전 점검** — Docker, GPU 툴킷(GPU/Jetson), 디스크를 확인합니다.
   2. 이미지 아카이브 체크섬을 **검증**합니다(손상되거나 변조된 미디어 감지).
   3. **이미지 로드** — 번들 아카이브에서 `docker load`(풀, 빌드 없음).
   4. **시크릿 생성** — 박스에서 JWT 서명 시크릿과 관리자 비밀번호를 만들어 보호된
      `.env`(모드 `600`)에 기록합니다. 시크릿은 번들 안에 절대 포함되지 않습니다.
   5. **스택 시작** — `docker compose up -d`.
   6. **헬스 게이트** — 세 서비스 모두 healthy를 보고할 때까지 기다립니다.
   7. **관리자 시드** 후 **대시보드 URL + 관리자 비밀번호를 한 번만 출력**합니다.

3. ### 관리자 비밀번호 저장

   
**단 한 번만 출력됩니다**

   설치 프로그램은 실행 종료 시 대시보드 URL과 생성된 관리자 비밀번호를 **단 한 번만**
   출력합니다. 즉시 비밀번호 관리자에 복사해 두세요 — 다시 읽어볼 수 있는 곳에는 저장되지
   않습니다.
   

4. ### 시크릿이 기록되었는지 확인

   설치 프로그램이 JWT 서명 시크릿을 자동으로 생성합니다. 보통은 손댈 필요가 없지만
   보호된 `.env`가 존재하는지 확인할 수 있습니다:

   ```bash
   ls -l .env        # 모드 -rw------- (600) 예상
   ```

   직접 값을 제공해야 하는 경우(예: 회사의 시크릿 관리 정책), 첫 `up` 전에 `.env`를
   편집하고 강력한 랜덤 값을 설정하세요:

   ```ini
   # .env  (자리표시자 — 강력한 랜덤 값을 생성하고 재사용하지 마세요)
   AIBOARD_JWT_SECRET=your-strong-random-jwt-secret
   ```

5. ### 데모 모델 교체

   번들에는 랜덤 가중치를 가진 데모 모델이 포함됩니다. 예측값이 의미를 갖도록 학습된
   `predictive_maintenance.onnx`로 교체하세요:

   - **첫 설치 전:** 번들의 `models/predictive_maintenance.onnx`를 덮어쓴 뒤
     `install.sh`를 실행합니다.
   - **설치 후:** 모델을 모델 데이터 볼륨의 `/data/models`에 넣고 추론 서비스를
     재시작합니다.

   나중에 대시보드에서 모델을 업로드할 수도 있습니다 —
   [모델 배포](/configure/models/)를 참조하세요.

6. ### 헬스 검증

   세 서비스 모두 healthy인지 확인합니다:

   ```bash
   docker compose -f compose/docker-compose.release.yml ps
   ```

   세 컨테이너가 `healthy` 상태일 것으로 예상됩니다. 그런 다음 설치 프로그램이 출력한
   대시보드 URL을 열고 관리자 계정으로 로그인하세요.

   
**GPU 첫 실행은 느립니다**

   GPU 및 Jetson 프로필에서는 첫 부팅 시 TensorRT 엔진을 컴파일하는 동안 추론 서비스가
   2~3분간 `unhealthy` 상태로 머물 수 있습니다. 이는 정상이므로 — 기다린 뒤 `ps`를 다시
   확인하세요.
   

## Day-2 운영

  
**업데이트**

   더 새로운 번들을 배포합니다. 업데이트는 먼저 데이터베이스 스냅샷을 만들어 롤백 경로를
   확보합니다.

   ```bash
   sudo ./update.sh
   ```

   
**실제 운영 중인 .env를 새 번들로 가져오세요**

   `update.sh`는 번들 디렉터리의 `.env`를 읽습니다 — 여기에는 배포별 시크릿, 포트,
   이미지 참조가 들어 있습니다. 새로 내려받은 번들에는 이것이 없으므로, 업데이트를
   실행하기 전에 기존 설치본의 `.env`를 새 번들 디렉터리로 복사하세요. 그렇지 않으면
   중단됩니다.
   

   업데이트 전 스냅샷은 **데이터베이스만** 포함합니다(업로드된 모델이나 TensorRT 캐시는
   제외). 모델을 롤백해야 한다면 해당 볼륨을 별도로 백업하세요.

  
  
**제거**

   ```bash
   ./uninstall.sh          # 스택 중지, 모든 데이터 유지
   ./uninstall.sh --purge  # 모델 + 데이터베이스도 삭제 (확인 프롬프트)
   ```

  

## 문제가 발생하면

| 증상 | 의미 |
|---------|---------------|
| `Bundle manifest missing` | 조립된 번들이 아닌 소스 폴더에서 설치 프로그램을 실행했습니다. USB에서 복사한 번들 디렉터리를 사용하세요. |
| `Architecture mismatch` | 이 박스의 CPU에 맞지 않는 번들 프로필입니다. 일치하는 프로필을 사용하세요. |
| `NVIDIA toolkit not wired in` | 컨테이너 툴킷이 없는 박스에 GPU/Jetson 번들을 사용했습니다. `amd64-cpu` 번들을 사용하거나 OS 이미지의 GPU 스택을 수정하세요. |
| 추론이 `unhealthy`에 멈춤 | 첫 실행 TensorRT 컴파일(GPU)에 2~3분 소요됨 — 기다리세요. 그렇지 않으면 추론 로그를 확인하세요. |
| 아카이브 체크섬 불일치 | 손상되거나 변조된 USB 미디어입니다. 번들을 다시 복사한 뒤 재시도하세요. |

증상별 해결 방법은 전체 [문제 해결](/ko/troubleshooting/) 런북을 참조하세요.

## 다음 단계

  - [입력 데이터소스 연결](/ko/configure/input-datasources/) — 센서 데이터를 런타임으로 스트리밍합니다.
  - [모델 배포](/configure/models/) — 학습된 모델을 업로드하고 활성화합니다.
  - [첫 추론](/ko/install-deploy/first-inference/) — 모델을 시드하고 실시간 예측값을 확인합니다.