콘텐츠로 이동
X-Edge AI

오프라인 번들 설치

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

받게 되는 것

섹션 제목: “받게 되는 것”

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

번들 프로필박스가 다음에 해당할 때 사용
amd64-cpux86_64 CPU, GPU 없음 — CPU 전용 추론
amd64-gpux86_64 CPU + NVIDIA GPU — TensorRT 가속
jetsonNVIDIA 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 운영자용 한 페이지 안내서

시작하기 전에

섹션 제목: “시작하기 전에”

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

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

설치 런북

섹션 제목: “설치 런북”

  1. 번들을 박스로 복사

    섹션 제목: “번들을 박스로 복사”

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

    Terminal window
    cd amd64-cpu-v1.5.0/

  2. 설치 프로그램 실행

    섹션 제목: “설치 프로그램 실행”

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

    Terminal window
    sudo ./install.sh

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

    Terminal window
    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. 관리자 비밀번호 저장

    섹션 제목: “관리자 비밀번호 저장”

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

    섹션 제목: “시크릿이 기록되었는지 확인”

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

    Terminal window
    ls -l .env        # 모드 -rw------- (600) 예상

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

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

  5. 데모 모델 교체

    섹션 제목: “데모 모델 교체”

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

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

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

  6. 헬스 검증

    섹션 제목: “헬스 검증”

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

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

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

Day-2 운영

섹션 제목: “Day-2 운영”

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

Terminal window
sudo ./update.sh

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

문제가 발생하면

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

증상별 해결 방법은 전체 문제 해결 런북을 참조하세요.

다음 단계

섹션 제목: “다음 단계”
입력 데이터소스 연결 센서 데이터를 런타임으로 스트리밍합니다.
모델 배포 학습된 모델을 업로드하고 활성화합니다.
첫 추론 모델을 시드하고 실시간 예측값을 확인합니다.