오프라인 번들 설치

이 방법은 인터넷이 없고, 레지스트리 접근이 불가능하며, 박스에서 이미지를 빌드하지 않는 고객 엣지 현장에서 권장하는 설치 방식입니다. USB 미디어로 제공되는 단일 자체 완결형 릴리스 번들에서 모든 것을 설치합니다.

이 페이지를 사용할 시점

공장이나 OT 현장의 프로덕션 엣지 박스에는 오프라인 번들을 사용하세요. 인터넷 접근이 가능한 환경에서 노트북으로 빠르게 평가하려면 빠른 시작이 더 빠릅니다.

받게 되는 것

릴리스 번들은 하드웨어 프로파일과 버전을 이름으로 하는 단일 디렉터리입니다(예: 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 이미지 기반 스택 (빌드 단계 없음)
    • docker-compose.certs.yml 데이터소스 TLS 인증서 오버레이 (선택 사항, 아래 참고)
    • .env.template 포트 + 시크릿 플레이스홀더
  • 디렉터리models/

    • predictive_maintenance.onnx 데모 시드 모델 (랜덤 가중치)
  • 디렉터리certs/ 데이터소스 MQTT/OPC UA CA + 클라이언트 인증서/키 (선택 사항)

    • …
  • install.sh
  • update.sh
  • uninstall.sh
  • README.txt 운영자용 한 장 요약

시드 모델은 데모입니다

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

시작하기 전에

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

• Docker Engine 20.10 이상, docker compose v2 플러그인 포함
• zstd 및 openssl
• NVIDIA Container Toolkit — GPU 및 Jetson 번들 전용

주의

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

설치 런북

1. 박스로 번들 복사

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

   cd amd64-cpu-v1.5.0/

2. 설치 프로그램 실행

   설치 프로그램은 하드웨어 프로파일을 자동 감지하고, 컨테이너 이미지를 로드하며, 시크릿을 생성하고, 스택을 기동한 뒤 상태가 정상이 될 때까지 대기합니다.

   sudo ./install.sh

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

   sudo ./install.sh --profile amd64-cpu   # force the profile
   sudo ./install.sh --with-systemd        # also start on boot

   내부적으로 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가 존재하는지 확인할 수 있습니다:

   ls -l .env        # expect mode -rw------- (600)

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

   # .env  (placeholder — generate a strong random value, do not reuse)
   AIBOARD_JWT_SECRET=your-strong-random-jwt-secret

5. 데모 모델 교체

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

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

   나중에 대시보드에서 모델을 업로드할 수도 있습니다 — 모델 배포를 참고하세요.

6. 상태 확인

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

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

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

   GPU 첫 실행은 느립니다

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

2일차 운영

업데이트

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

sudo ./update.sh

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

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

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

제거

./uninstall.sh          # stop the stack, KEEP all data
./uninstall.sh --purge  # also delete models + database (confirmation prompt)

데이터소스 TLS 인증서

(v1.22.1) 데이터소스 측 TLS — MQTT 또는 OPC UA 데이터소스가 보안된 브로커나 서버에 연결하는 데 사용하는 CA / 클라이언트 인증서 / 키로, 박스 자체의 HTTPS 인증서와는 별개입니다 — 는 번들 경로에서 기본적으로 꺼져 있습니다. AIBOARD_TLS_ENABLED와 대칭을 이루는 파일 기반 .env 플래그입니다:

.env

AIBOARD_CERTS_ENABLED=1

이 플래그가 켜지면, install.sh는 절대 경로 AIBOARD_CERTS_DIR=<bundle>/certs를 기록하고 번들에 포함된 docker-compose.certs.yml 오버레이를 기본 릴리스 스택 위에 겹쳐 적용합니다. 플래그를 활성화하기 전에 MQTT/OPC UA CA와 클라이언트 인증서/키 파일을 번들의 certs/ 디렉터리에 넣으세요.

인증서 경로는 서버 측이며 격리되어 있습니다

데이터소스의 인증서 경로 필드(CA 파일, 클라이언트 인증서, 클라이언트 키)는 운영자 자신의 머신이 아니라 마운트된 certs/ 루트로 한정된 백엔드 컨테이너의 파일 시스템에서 해석됩니다. 값을 설정할 위치는 데이터소스 연결과 출력 데이터소스를 참고하세요.

update.sh는 인증서를 이어서 가져갑니다

인증서는 박스 자체의 TLS 인증서처럼 재생성할 수 없습니다. update.sh는 AIBOARD_CERTS_DIR를 다시 지정하기 전에 운영자의 인증서 파일을 이전 번들에서 새 번들로 가져오므로, 일상적인 업데이트가 정상 동작하는 MQTT/OPC UA TLS 설정을 망가뜨리지 않습니다.

uid-101이 certs/를 읽을 수 있어야 합니다

백엔드 컨테이너는 uid 101로 인증서 파일을 읽습니다. 번들의 certs/ 디렉터리(및 그 안의 모든 파일)에 소유권/권한을 설정하여 uid 101이 읽기 권한을 갖도록 하세요 — 그렇지 않으면 데이터소스 어댑터가 연결 시점에 인증서를 로드하는 데 실패합니다.

문제가 발생하면

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

증상별 해결책은 전체 문제 해결 런북을 참고하세요.

다음 단계

입력 데이터소스 연결 센서 데이터를 런타임으로 스트리밍합니다.

모델 배포 학습된 모델을 업로드하고 활성화합니다.

첫 추론 모델을 시드하고 실시간 예측값을 확인합니다.