# Contextra Deployment Kit — 현장 안내

- 평소에는 `deployctl` 하나에서 시작합니다. 인자 없이 실행하면 메뉴가 나옵니다.
- `--apply` 없는 설치·갱신 명령은 **계획만** 보여줍니다. 실제 변경은 `sudo`와 승인 후 진행합니다.
- 이 배포 도구와 실제 이미지·모델은 별도입니다. 이미지/ONNX/엔진·private 설정이 없으면 설치 완료가 아닙니다.
- 코드 검증과 실제 GPU·Web 수용을 구분합니다. `RUNTIME_READY`는 첫 카메라 프레임이나 Web 성공이 아닙니다.

## 1. 무엇부터 읽나요?

현재 준비 상태와 보완 계약은 [첫 FULL 배포 준비](LOCAL_PREPARATION.ko.md)를 먼저 확인하세요.

| 상황 | 문서 |
|---|---|
| 처음 배포 | [빠른 시작](QUICK_START.ko.md), [첫 서버 입력 준비](FIRST_SITE.ko.md) |
| Docker부터 없음 | [Host 준비](HOST_BOOTSTRAP.ko.md) |
| USB 패치 | [오프라인 업데이트](OFFLINE_UPDATE.ko.md) |
| 경로/디스크 혼동 | [저장소](STORAGE.ko.md) |
| 모델 준비 | [모델 도구](MODEL_TOOLING.ko.md) |
| 문제 발생 | [상황별 대응](TROUBLESHOOTING.ko.md), [오류 사전](ERROR_CATALOG.ko.md) |
| 이전 버전으로 복귀 | [복원](ROLLBACK.ko.md) |

## 2. 쉽게 보는 구조

```mermaid
flowchart TD
  USB[USB 배포물과 별도로 확인한 SHA256] --> VERIFY[배포물 검증]
  VERIFY --> STAGE[새 release 준비]
  STAGE --> CONFIG[기존 private 설정과 Compose 순서 검증]
  CONFIG --> APPLY[명시 승인 후 설치]
  APPLY --> CHECK[컨테이너와 모델 readiness]
  CHECK --> CURRENT[current 활성 버전 기록]
```

프로그램은 교체할 수 있는 설명서이고, DATA_ROOT는 보존해야 하는 창고입니다. 설명서를 바꿀 때 창고를 비우지 않습니다.

## 3. v1의 중요한 수동 경계

최초 private env/overlay·계정·인증서·승인 이미지 준비는 담당 엔지니어가 합니다. 마법처럼 값을 추측하지 않습니다.
실행 중인 시스템은 기존 운영 도구로 채널 Stop/reap와 writer 정리를 완료하고 **관리 컨테이너를 정지한 뒤** 패치합니다.
이 도구는 아직 live maintenance를 자동 조합하지 않습니다. 따라서 v1은 무중단·완전 원클릭 업데이트가 아닙니다.
`storage move`는 복사/검증 계획만 출력합니다. 실제 대용량 이동과 fstab 변경은 자동 실행하지 않습니다.

## 4. 시작 명령

```bash
./deployctl
./deployctl --help
./deployctl guide quick
```

기본 설치 후에는 `<INSTALL_ROOT>/deployctl`이 해당 서버의 site 파일을 자동 선택합니다.
진단에서 권한이 부족하면 같은 읽기 명령만 sudo로 다시 실행합니다. Docker 그룹은 필수가 아닙니다.