9596d1bad6
0.9.0 까지가 "감지하는 시스템"이었다면 1.0.0 은 "감지에 대응하는 시스템"이다. 그 차이를
만드는 것은 e00ad69 의 통보 경로이고, 이 커밋은 그것을 실제로 납품 가능한 형태로 만든다.
VERSION 0.9.0 -> 1.0.0
릴리스 규칙 위반 3건 수정 (rules/release-versioning.md)
- 산출물 파일명에 버전·날짜가 없었다. move-detect-cafe24.zip / 2_pi_install-<arch>.tar.gz
는 같은 날 두 번 빌드하면 구분이 안 되고, 현장이 무엇을 돌리는지 파일명으로 답할 수
없었다. 이제 move-detect-cafe24-<VERSION>-<YYYYMMDD>.zip /
move-detect-pi-<VERSION>-<YYYYMMDD>-<arch>-<abi>-<hailo>.tar.gz.
- 두 빌드 스크립트가 VERSION 파일이 없으면 "unknown" 으로 넘어갔다. 무버전 산출물은
빌드머신을 떠나는 순간 커밋과 대조할 방법이 사라진다 — 이제 exit 1 로 거부한다.
- deploy/README.md 의 stale 파일명 표기 갱신.
납품 동봉물 (skill delivery-audit: "설명서 + 점검 리포트 동봉")
- CHANGELOG.md 신설. 업그레이드 절차와 알려진 제약(모델 미확보 3종)을 명시.
- 역할별 사용 설명서를 패키지에 동봉. 운영자/안전관리자/시스템관리자 3역할 14절 + FAQ 6항,
실제 화면 캡처 8장을 base64 로 박은 단일 HTML(665KB). 폐쇄망에서 메일·USB 로 돌아다녀도
도판이 깨지지 않아야 하므로 단일 파일이다.
생성물은 커밋하지 않는다 — 소스(manual.json + shots/)만 두고 패키저가 매번 빌드한다.
커밋된 사본은 화면이 바뀐 뒤에도 최신처럼 보이고, 구 UI 캡처가 남은 매뉴얼은 납품물
자체의 결함이다.
- 감사 리포트를 '납품점검-리포트.md' 로 동봉. 무엇을 점검했고 무엇이 잔여인지 패키지가
스스로 답하지 못하면, 인수인계 몇 달 뒤 그 답을 아는 사람이 남지 않는다.
README-UPLOAD 에 크론 안내 신설 (누락이었다)
설치 안내서에 자동 실행 등록이 아예 없었다. 이 릴리스의 핵심인 통보가 크론 없이는 한 건도
나가지 않는데, 운영자가 읽는 유일한 문서가 그 사실을 말하지 않았다.
8번(알림 켜기: 크론 2개 + --dry-run 선행 + 경광등 우선) / 9번(설치 점검 /setup) 추가,
마지막 체크리스트에 3항목 추가.
부수 수정
- 셸 스크립트에 CRLF 가 섞여 bash 가 여는 중괄호에서 죽었다(빌드 자체가 불가). LF 로 정규화.
cafe24 스크립트에는 bash -n 가드가 이미 있어 이번에 실제로 잡았고, Pi 쪽에는 없어서
그대로 지나갈 뻔했다 — tests/test_deploy_artifacts.py 에 CRLF·bash -n 가드 추가.
산출물
dist/move-detect-cafe24-1.0.0-20260818.zip
dist/move-detect-pi-1.0.0-20260818-aarch64-cp311-hailo8.tar.gz
검증: pytest 통과(skip 3 = 하드웨어·환경) · PHPUnit 224 (skip 0).
매뉴얼 실렌더 확인(목차 정합·도판 8장·콜아웃). 패키지 내부 검증: 버전 스탬프 1.0.0,
마이그레이션 8/8 동봉, config.php 는 CHANGEME 템플릿, tools/ 는 www 밖에만,
웹 루트 PHP 는 index.php/_preflight.php 뿐.
180 lines
8.8 KiB
Markdown
180 lines
8.8 KiB
Markdown
# Edge deployment (Raspberry Pi 5, air-gapped / 폐쇄망)
|
|
|
|
Offline-installable bundle + systemd unit for the `move-detect` edge daemon.
|
|
The bundle is fully self-contained (all wheels + pose model + source): the Pi
|
|
performs **zero network fetches** at install or run time. The only runtime
|
|
network use is the server POST / config-poll / heartbeat, and even that tolerates
|
|
being offline (events buffer in the local sqlite queue and flush on reconnect).
|
|
|
|
> Scope: the delivered bundle is **Hailo-8 + `yolov8s_pose.hef`**, which
|
|
> `build_offline_bundle.sh` fetches (sha256-pinned) and stages into `models/`.
|
|
> The CPU MoveNet fallback is **not** bundled: its upstream ONNX URL 404s, so
|
|
> `install_offline.sh` configures the unit for whatever backend is actually
|
|
> present and refuses to install if none is. Camera side: USB (UVC) and CSI are
|
|
> both wired; CSI needs `hailo-all`/`picamera2` from the Pi OS image.
|
|
> Device validation for both is `docs/hardware-bringup.md` (still OFF-HW).
|
|
|
|
## Files
|
|
|
|
| File | Runs on | Purpose |
|
|
|------|---------|---------|
|
|
| `bundle/build_offline_bundle.sh` | build machine (has internet) | downloads wheels + model, stages source, emits one tarball |
|
|
| `bundle/install_offline.sh` | the Pi (no internet) | venv + `--no-index` install, systemd unit, service account |
|
|
| `systemd/move-detect-edge.service` | the Pi | the daemon unit (auto-restart, device access, hardening) |
|
|
| `systemd/move-detect-edge.env.example` | the Pi | env template → `/etc/move-detect/edge.env` |
|
|
|
|
## Quick start — Pi with internet (one command)
|
|
|
|
If the Pi itself has internet, skip the offline bundle entirely. Copy the built delivery
|
|
folder onto the Pi — **copy the working tree, not a fresh `git clone`**: the pose model
|
|
`models/yolov8s_pose.hef` is git-ignored (a build artifact), so a clone arrives without it.
|
|
Use `scp -r`/USB from a build machine that has already staged `models/` (see step 1). Then:
|
|
|
|
```bash
|
|
sudo deploy/setup_online.sh
|
|
```
|
|
|
|
It installs the system packages (`python3-picamera2`, and `hailo-all` if present), builds
|
|
the venv, pip-installs the runtime deps, **places the pose model from the delivery's
|
|
`models/`** (it does NOT download models on the Pi — the HEF/ONNX are fetched on the build
|
|
machine per the air-gap rule, `build pulls, target doesn't`), writes `/etc/move-detect/edge.env`
|
|
(prompting for `DEVICE_ID` / `DEVICE_SECRET` / `CAFE24_URL` / `CAMERAS`, or take them from env
|
|
vars), probes every camera, installs the systemd unit, and starts the service. It uses Hailo
|
|
when `models/yolov8s_pose.hef` is present (or pass `HAILO_HEF=/path/to.hef`), else CPU MoveNet
|
|
when `models/movenet_lightning.onnx` + onnxruntime are present. The rest of this doc is the
|
|
**air-gapped** path.
|
|
|
|
### Secret handling (`deploy/device.env`)
|
|
|
|
If you pre-provision with `deploy/device.env`, that file holds this device's **HMAC secret in
|
|
plaintext**. It is gitignored (never committed), but it rides onto the Pi with the "copy the
|
|
working tree" transfer. After a successful install:
|
|
|
|
1. **Delete it:** `shred -u deploy/device.env` (the live secret now lives only in
|
|
`/etc/move-detect/edge.env`, `0640 root:movedetect`). The installer already `chmod 600`s it
|
|
while running, but that is defense-in-depth, not a substitute for removing it.
|
|
2. **Rotate if it was ever exposed** (shared over chat, a shell history, a shared drive):
|
|
update `move_devices.secret` on the server and the `DEVICE_SECRET` in the Pi's
|
|
`/etc/move-detect/edge.env`, then restart the service. A leaked secret lets anyone forge
|
|
signed events/heartbeats for this device.
|
|
|
|
Prefer `device.env` over passing `DEVICE_SECRET=...` on the `sudo` command line, which leaves the
|
|
secret in the shell history.
|
|
|
|
---
|
|
|
|
## 1. Build the bundle (on a machine WITH internet)
|
|
|
|
**Most reliable: build on an aarch64 host** (a Pi 5, or an arm64 CI runner) so the
|
|
downloaded wheels match the target exactly:
|
|
|
|
```bash
|
|
deploy/bundle/build_offline_bundle.sh # native aarch64 wheels
|
|
```
|
|
|
|
From an x86 box you can attempt a cross build (best-effort — onnxruntime/opencv
|
|
wheel tags may not resolve; if it fails, build natively):
|
|
|
|
```bash
|
|
deploy/bundle/build_offline_bundle.sh --cross # target aarch64 / cp311
|
|
```
|
|
|
|
Output: the folder `dist/2_pi_install/` (+ `MANIFEST.txt` listing the bundled
|
|
wheels). Copy the WHOLE FOLDER across the air gap as-is — no archive step.
|
|
Set `MAKE_TARBALL=1` if you would rather transfer one file. The tarball is named
|
|
`dist/move-detect-pi-<VERSION>-<YYYYMMDD>-aarch64-cp311-hailo8.tar.gz` — version and
|
|
build date so a site can say exactly what it is running, and the arch/ABI/Hailo triple
|
|
because a hailo8 and a hailo8l bundle are byte-different and crash-loop on the wrong board.
|
|
|
|
## 2. Transfer + install (on the air-gapped Pi)
|
|
|
|
Copy `dist/2_pi_install/` across the gap (USB, one-way transfer, etc.), then:
|
|
|
|
```bash
|
|
# tarball variant only (MAKE_TARBALL=1): tar xzf move-detect-pi-<VERSION>-<날짜>-aarch64-cp311-hailo8.tar.gz
|
|
cd 2_pi_install
|
|
sudo ./install_offline.sh
|
|
```
|
|
|
|
The installer: creates the `movedetect` service account (in `video`/`render`/
|
|
`plugdev`/`hailo` groups), lays down source + model under `/opt/move-detect`,
|
|
builds a venv and installs the bundled wheels with `--no-index`, verifies the
|
|
package imports, seeds `/etc/move-detect/edge.env`, and installs the systemd unit.
|
|
|
|
## 3. Configure + start
|
|
|
|
```bash
|
|
sudo nano /etc/move-detect/edge.env # DEVICE_ID, DEVICE_SECRET, CAFE24_URL, ...
|
|
sudo systemctl enable --now move-detect-edge
|
|
journalctl -u move-detect-edge -f
|
|
```
|
|
|
|
`DEVICE_ID`/`DEVICE_SECRET` must match a `move_devices` row in the server (see
|
|
`server/docs/server-deploy.md` §6). `HAILO_HEF` points at the bundled model
|
|
(`/opt/move-detect/models/yolov8s_pose.hef`); the installer sets it for you and
|
|
only falls back to `MOVENET_ONNX` if a MoveNet bundle was built.
|
|
|
|
## 4. Verify the air gap (do this before trusting a build)
|
|
|
|
- [ ] On a host with **networking disabled**, `install_offline.sh` completes —
|
|
the `--no-index` installs prove nothing is fetched. If pip tries to reach
|
|
PyPI, a wheel is missing from the bundle: rebuild (step 1) natively.
|
|
- [ ] Step [4/6] of the installer prints `edge import OK` (cv2 + numpy + requests
|
|
import from the venv; onnxruntime only if a MoveNet bundle was built).
|
|
- [ ] `systemctl status move-detect-edge` is `active (running)`; the log shows
|
|
frames processed and (if the server is reachable) heartbeats.
|
|
- [ ] Pull the network cable → events keep queueing (`QUEUE_DB` grows) → restore
|
|
→ the queue flushes. (End-to-end behavior verified in the edge e2e harness.)
|
|
|
|
## Hailo-8 HAT + CSI camera path (optional, faster)
|
|
|
|
The default bundle runs CPU MoveNet + USB webcam. To use the Hailo-8 accelerator
|
|
and/or a CSI camera, add these SYSTEM packages on the Pi (they are apt packages, not
|
|
pip wheels — the venv sees them because it is created with `--system-site-packages`):
|
|
|
|
```bash
|
|
sudo apt install -y hailo-all python3-picamera2 python3-opencv
|
|
```
|
|
|
|
- `hailo-all` — HailoRT runtime + driver + the Python `hailo_platform` bindings.
|
|
- `python3-picamera2` — CSI camera stack (libcamera).
|
|
|
|
Then place the pose model and switch backends in `/etc/move-detect/edge.env`:
|
|
|
|
```ini
|
|
POSE_BACKEND=hailo
|
|
HAILO_HEF=/opt/move-detect/models/yolov8s_pose.hef # copy the compiled HEF here
|
|
CAMERA_BACKEND=csi
|
|
CSI_DEVICE=0
|
|
```
|
|
|
|
Validate on device per `docs/hardware-bringup.md` before trusting output (the Hailo
|
|
decode is unit-locked, but the HailoRT inference + picamera2 color order are hardware-
|
|
validated). USB webcam stays available anytime via `CAMERA_BACKEND=uvc`.
|
|
|
|
**Multiple cameras at once.** Set `CAMERAS=backend:device:camera_id,...` to run several
|
|
cameras in one daemon — each gets its own detection pipeline and `camera_id`, they share
|
|
the Hailo device (round-robin) and the offline queue, and server zones are routed to the
|
|
matching camera. Example — CSI + USB together:
|
|
|
|
```ini
|
|
CAMERAS=csi:0:cam-01,uvc:0:cam-02
|
|
```
|
|
|
|
Each `camera_id` must match the `camera_id` on that camera's zones in the server.
|
|
|
|
> **Air gap:** `hailo-all` / `python3-picamera2` are the ONE piece this bundle can't
|
|
> carry (Hailo's own driver + apt tree). Pre-install them on the Pi image, or transfer
|
|
> their `.deb`s separately, before running `install_offline.sh`. The pose HEF is
|
|
> likewise supplied out-of-band (compiled from the Hailo Model Zoo).
|
|
|
|
## Not bundled (by design)
|
|
|
|
- **MySQL / the server app** — a separate host; see `server/docs/server-deploy.md`.
|
|
- **HailoRT + picamera2** — Hailo's runtime/driver and the CSI camera stack are Pi
|
|
system packages, installed out-of-band (above). Note the HEF itself **is** bundled
|
|
(`models/yolov8s_pose.hef`); only the driver is not.
|
|
- **`python3-venv`** — `install_offline.sh` runs `python3 -m venv`, which Pi OS Lite
|
|
does not always include. Install it with the Hailo packages, before going air-gapped.
|
|
- **MoveNet ONNX (CPU fallback)** — its upstream URL 404s, so the bundle is Hailo-only.
|
|
If you need the CPU path, supply the ONNX to the build machine and rebuild.
|