managed-portal/managed/people_flow_project/docs/plans/2026-04-08-lightweight-native-bundle-design.md

Lightweight Native Bundle Design

Date: 2026-04-08

Goal: Deliver a lightweight native deployment bundle for Ubuntu 24.04 x86_64 that includes project code, required weights, a single editable RTSP run script, and a small setup path on the target host without bundling a full Python environment in the archive.

Scope

• Target host: xiaozheng@192.168.5.154
• Target path: /home/x/people/people_flow_project
• Bundle contents:
  • project code
  • YOLO weight
  • DeepFace weights
  • one editable run script
  • setup and usage documentation
• Exclude the virtual environment from the compressed bundle to keep size down.

Deployment Model

The target host already has:

• Ubuntu 24.04 x86_64
• Python 3.12
• Docker available, but Docker is intentionally not used here
• NVIDIA driver and CUDA-capable GPU

The bundle will therefore rely on:

1. a project-local .venv created on the target host
2. host driver compatibility for GPU wheels
3. project-relative weight paths so no external downloads are needed

User Editing Surface

The main operator interface is a single shell script:

• run_rtsp.sh

The user edits only:

• RTSP_URL
• OUTPUT_DIR

The script activates .venv, points to the native x86 config, and runs the RTSP pipeline.

Config Strategy

Add a dedicated native x86 config file with:

• yolo.model_path pointing to the local weights/yolo11n.pt
• RTSP timing settings
• output defaults for RTSP mode

This avoids modifying the existing Jetson-oriented config and keeps host deployment deterministic.

Setup Strategy

Provide a small setup script that:

• creates .venv
• upgrades pip/setuptools/wheel
• installs CUDA-enabled PyTorch wheels
• installs TensorFlow, tf-keras, and application dependencies

The setup script keeps the archive light while still making the target directory self-contained after one install step.

Bundle Output

On the target host, create a compressed archive such as:

• /home/x/people/people_flow_project_native_bundle_2026-04-08.tar.gz

The archive will exclude .venv so it stays close to the size of code plus weights.

Success Criteria

• The target host contains a runnable native project directory
• run_rtsp.sh is the only file the operator needs to edit for RTSP URL and output directory
• All required weights are present locally
• The lightweight tarball is created successfully