# USB 오프라인 업데이트

- USB에는 배포물, 운영 문서, 필요한 image/model만 넣습니다. secret·개발 문서를 넣지 않습니다.
- 담당자로부터 **USB와 별도 경로**로 archive SHA256를 받습니다.
- live 채널은 기존 도구로 정상 Stop/reap하고 관리 컨테이너를 정지한 후 적용합니다.
- v1은 무중단 자동 Stop/Start 도구가 아닙니다. 유지보수 정지 뒤에는 update 한 명령이 순서를 담당합니다.

## 1. 세 종류

| 종류 | 가져오는 것 | 현장 처리 |
|---|---|---|
| CONFIG | 검토된 설정/문서/도구 snapshot | image 그대로 |
| APP | Analytics `app/` 전체 snapshot | 정확한 기존 image에 앱 layer만 오프라인 build |
| FULL | 바뀐 서비스의 전체 image 등 | docker load와 ID 확인 |

APP은 native/SDK/의존성/entrypoint가 그대로이고 parent release/기존 image ID가 일치해야 합니다.
Sidecar 코드 변경, 새 의존성, C++ 변경은 현재 APP 경로에서 처리하지 않고 FULL을 사용합니다.
`docker save`는 독립 복원용 image archive라 큰 공통 layer도 포함할 수 있습니다. 이 도구는 임의 layer tar 차분을 만들지 않습니다.

## 2. 패치

```bash
CTL=/opt/contextra/deployctl
BUNDLE=/path/to/usb/contextra-v2.tar.gz
EXPECTED_SHA256=별도_전달받은_64자리_SHA256
sudo "$CTL" update "$BUNDLE" --sha256 "$EXPECTED_SHA256"
# 유지보수 정지와 계획 확인 후
sudo "$CTL" update "$BUNDLE" --sha256 "$EXPECTED_SHA256" --apply
sudo "$CTL" doctor
```

정상: HOST/DEPLOYED/RUNTIME_READY PASS, EXTERNAL_READY NOT_RUN.
실패: `recover`로 어느 단계까지 실행됐는지 보고 반복 실행하지 않습니다. [복원](ROLLBACK.ko.md).

## 3. APP의 중요한 제한

현재 APP builder는 검증한 로컬 base tag + `DOCKER_BUILDKIT=0`, `--pull=false`, `--network=none` 조합입니다.
Docker legacy builder는 deprecated이므로 **해당 서버의 고정 Docker에서 실제 오프라인 build를 검증해야 합니다.**
지원되지 않으면 임의로 인터넷 pull/다른 builder로 전환하지 않고 FULL image를 반입합니다.
`--network=none`만으로 모든 BuildKit frontend/base 조회가 차단된다는 뜻은 아닙니다.
작은 patch가 모든 미래 Docker 버전에서 실행된다고 보장하지 않습니다.

## 4. 오프라인 전환 전

최소 현재/직전 정상 image, model/ONNX, 배포 도구, private 설정 보관 위치, 복구 package를 확인합니다.
온라인 Git은 source 준비용입니다. 현장 update는 GitHub나 Git 설치를 필요로 하지 않습니다.
기존 image를 임의 prune하면 작은 APP patch와 rollback 기반이 사라질 수 있습니다.

공식 참고: https://docs.docker.com/engine/deprecated/#legacy-builder-for-linux-images