From 9615f0263fff21f9fc11c2242b1e7ee6e1aab608 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 5 Aug 2026 07:34:08 -0400 Subject: [PATCH] =?UTF-8?q?Initial=20project=20documentation:=20NVR=20Shie?= =?UTF-8?q?ld=20=E2=80=94=20Reolink=20NVR=20monitoring=20agent?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: project overview, pricing, deployment model - ARCHITECTURE: system design, data flow, components, security - DECISIONS: Pi Zero 2W, Tailscale, reolink-aio, Wasabi S3 choices - ROADMAP: 3-phase plan (MVP, monetization, expansion) - CHANGELOG: concept (Aug 1) and full documentation (Aug 5) - Customer onboarding information request sheet --- ARCHITECTURE.md | 130 ++++++++++++++++++++++++++++++++++++ CHANGELOG.md | 20 ++++++ DECISIONS.md | 55 +++++++++++++++ README.md | 39 +++++++++++ ROADMAP.md | 35 ++++++++++ customer-onboarding-form.md | 128 +++++++++++++++++++++++++++++++++++ 6 files changed, 407 insertions(+) create mode 100644 ARCHITECTURE.md create mode 100644 CHANGELOG.md create mode 100644 DECISIONS.md create mode 100644 README.md create mode 100644 ROADMAP.md create mode 100644 customer-onboarding-form.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..63b05ad --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,130 @@ +# NVR Shield — Architecture + +## System Overview + +``` +┌─────────────────────────────────────────────────────────┐ +│ CUSTOMER SITE │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ NVR #1 │ │ NVR #2 │ │ NVR #3 │ (Reolink) │ +│ │ 192.168.x│ │ 192.168.x│ │ 192.168.x│ │ +│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ +│ │ │ │ │ +│ └──────────────┼──────────────┘ │ +│ │ HTTP API (port 80/443) │ +│ ┌───────┴────────┐ │ +│ │ Pi Zero 2W │ │ +│ │ NVR Shield │ │ +│ │ Agent │ │ +│ └───────┬────────┘ │ +│ │ Tailscale (WireGuard) │ +└──────────────────────┼───────────────────────────────────┘ + │ + INTERNET │ + │ +┌──────────────────────┼───────────────────────────────────┐ +│ ITPP CORE (netcup) │ +│ │ │ +│ ┌───────┴────────┐ │ +│ │ NVR Shield │ │ +│ │ Dashboard │ │ +│ │ API (:8090) │ │ +│ └───────┬────────┘ │ +│ │ │ +│ ┌────────────┼────────────┐ │ +│ │ │ │ │ +│ ┌────┴────┐ ┌────┴────┐ ┌───┴──────┐ │ +│ │ Wasabi │ │ Alerting │ │ Monthly │ │ +│ │ S3 │ │ (Email/ │ │ Reports │ │ +│ │ Backups │ │ SMS) │ │ Generator│ │ +│ └─────────┘ └─────────┘ └──────────┘ │ +└───────────────────────────────────────────────────────────┘ +``` + +## Components + +### 1. Pi Zero 2W Agent (`agent.py`) + +Runs on Raspberry Pi Zero 2W at customer site. Python 3. + +**Responsibilities:** +- Poll each configured NVR every 60s via Reolink HTTP API (`reolink-aio`) +- Collect: camera online status, HDD health, storage %, firmware version, uptime +- Push metrics to Core heartbeat endpoint +- Dump full NVR config to Wasabi S3 nightly +- Capture motion/AI-triggered clips and upload to S3 (Pro/Enterprise tiers) +- Accept remote config and update commands from Core +- Run custom AI filtering rules (Enterprise tier) + +**Config schema (`config.yaml`):** +```yaml +site_id: "cust-shortname" +heartbeat_url: "https://core.itpropartner.com/nvr-shield/heartbeat" +s3_bucket: "nvr-shield-customer-backups" +s3_prefix: "cust-shortname/" +poll_interval: 60 # seconds +config_backup_time: "03:00" # daily + +nvrs: + - name: "Warehouse" + ip: "192.168.1.10" + port: 443 + user: "admin" + password: "${NVR_PASSWORD_WAREHOUSE}" + - name: "Front Office" + ip: "192.168.1.11" + port: 443 + user: "admin" + password: "${NVR_PASSWORD_FRONTOFFICE}" +``` + +### 2. Core Dashboard / API + +FastAPI backend on Core (:8090 path `/nvr-shield/`). + +**Endpoints:** +| Method | Path | Purpose | +|---|---|---| +| POST | `/nvr-shield/heartbeat` | Agent pushes metrics (site_id, nvrs[], metrics) | +| GET | `/nvr-shield/dashboard` | Admin dashboard — all sites, health, alerts | +| GET | `/nvr-shield/site/{id}` | Per-site detail (cameras, history, clips) | +| GET | `/nvr-shield/report/{id}/{month}` | Monthly report PDF/HTML | +| POST | `/nvr-shield/agent/{id}/config` | Push updated config to agent | + +### 3. Wasabi S3 Storage + +**Bucket:** `nvr-shield-customer-backups` +**Structure:** +``` +s3://nvr-shield-customer-backups/ + {site_id}/ + configs/ + 2026-08-01-config.json + 2026-08-02-config.json + clips/ + 2026-08-01/ + 14-32-15-NVR-Warehouse-Cam3-motion.mp4 + reports/ + 2026-07-monthly-report.pdf +``` + +### 4. Tailscale Network + +All Pi Zero 2W devices connect via Tailscale to ITPP's tailnet. Each device tagged `tag:nvr-shield`. Core communicates with agents over Tailscale IPs, not public internet. + +## Data Flow + +1. **Health polling (every 60s):** Agent → NVR HTTP API → metrics JSON → Core heartbeat endpoint +2. **Nightly config backup:** Agent → NVR HTTP API → config JSON → Wasabi S3 +3. **Incident clips (Pro/Enterprise):** NVR motion/AI event → agent detects → clip upload to S3 → notification to Core +4. **Monthly report:** Core cron (1st of month) → aggregates metrics from DB + S3 → generates PDF → emails customer +5. **Alerts:** Core evaluates heartbeat gaps (>2 min = alert), disk thresholds (>90% = alert), camera offline + +## Security + +- Pi filesystem is read-only (overlayfs) to prevent SD card corruption +- SSH key-only, no password auth +- NVR passwords stored in env vars, never in git +- Tailscale WireGuard for all agent-Core communication +- S3 credentials scoped to per-customer prefix only diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a387964 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,20 @@ +# NVR Shield — Changelog + +## 2026-08-05 + +### Added +- Project folder created at `/root/projects/nvr-shield/` +- Full documentation: README, ARCHITECTURE, DECISIONS, ROADMAP, CHANGELOG +- Customer onboarding form (`customer-onboarding-form.md`) +- Marketplace listing added to my.itpropartner.com +- Git repo initialized at `git.itpropartner.com/ippadmin/nvr-shield.git` + +## 2026-08-01 (Initial Concept) + +### Added +- Concept defined: Pi Zero 2W agent to monitor Reolink NVRs +- BOM calculated: ~$41/unit, sold at $149 +- Pricing tiers: Basic $49/mo, Pro $97/mo, Enterprise $147/mo +- Deployment plan: pre-flash at office, ship ready to plug in +- Multi-NVR support: one Pi handles all NVRs at a single site +- 4 tasks queued: agent script, pre-flash image, Core dashboard, product page diff --git a/DECISIONS.md b/DECISIONS.md new file mode 100644 index 0000000..3efacc0 --- /dev/null +++ b/DECISIONS.md @@ -0,0 +1,55 @@ +# NVR Shield — Decisions + +## Why Pi Zero 2W? + +- **Cost:** $15/unit keeps BOM at ~$41, enabling $149 retail with healthy margin +- **Power:** 5V micro-USB, can share NVR's UPS or any USB port +- **Size:** Tiny, fits behind NVR or in structured media panel +- **OS:** Raspberry Pi OS Lite (Bookworm) — mature, read-only overlayfs support, Tailscale package + +**Alternatives considered:** +- Pi 4/5: Overkill. 4x the cost, no benefit for API polling workload +- ESP32: Too constrained. No Python, limited HTTP client, no Tailscale +- On-NVR agent: Reolink NVRs don't support custom agents. Would require rooting + +## Why Tailscale Instead of Direct VPN? + +- Zero customer firewall configuration needed — Tailscale punches through NAT +- Pre-configured at flash time, ships ready to connect +- Tag-based ACLs (`tag:nvr-shield`) keep devices isolated from rest of tailnet +- Customer never sees or manages the VPN + +## Why reolink-aio Library? + +- Active open-source Python client for Reolink cameras/NVRs +- Supports both HTTP and HTTPS API +- Handles login/session management +- Maintained, documented, tested against Reolink firmware + +**Alternative:** Direct HTTP calls with `requests`. Rejected — reolink-aio handles auth, errors, and data parsing. + +## Why One Pi Per Site (Not Per NVR)? + +- Single Pi Zero 2W can poll 5-10 NVRs with zero performance issues (lightweight HTTP calls, no video) +- Simplifies deployment: one device per physical location +- Cleaner pricing: per-site, not per-NVR +- Reduces BOM for multi-NVR sites + +## Why Core Dashboard on :8090? + +- Existing Ops Portal runs on :8090. NVR Shield is a natural extension +- Shares auth (central auth JWT validation) +- Path-based routing: `/nvr-shield/` sits alongside existing `/backup-restore/`, `/ops/` + +## Why Wasabi S3? + +- Already used for all ITPP backups (hermes, app1, app2, app3) +- No egress fees for clip retrieval/viewing +- Per-bucket IAM policies for customer isolation +- Immutability for compliance/audit trail + +## Pricing Decisions + +- Hardware at $149: 3.6x BOM ($41) — covers labor (flashing, packaging, shipping), still competitive with off-the-shelf NVR monitoring appliances ($200-500) +- Monthly tiers: $49 (monitoring) / $97 (clip vault) / $147 (AI rules) — follows ITPP convention: annual = monthly, simple increments +- No per-NVR surcharge: cleaner pitch, fewer objections diff --git a/README.md b/README.md new file mode 100644 index 0000000..f9fb082 --- /dev/null +++ b/README.md @@ -0,0 +1,39 @@ +# NVR Shield + +**Status:** PLANNED | **Owner:** Germaine Brown | **Type:** Product (ITPP Marketplace) + +Onsite monitoring agent for Reolink NVRs deployed via Raspberry Pi Zero 2W. Monitors NVR health, backs up configs, captures incident clips, delivers monthly reports, and supports custom AI filtering rules. Sold as hardware + recurring monthly subscription through the IT Pro Partner Marketplace. + +**Tagline:** "Professional monitoring for your security camera system." + +## Access + +| Resource | Location | Access | +|---|---|---| +| Agent repo | `git.itpropartner.com/ippadmin/nvr-shield.git` | ippadmin token | +| Core dashboard | TBD (Core :8090 backend) | TBD | +| Marketplace listing | `my.itpropartner.com/#marketplace` | Public | +| Customer info sheet | `/root/projects/nvr-shield/customer-onboarding-form.md` | Internal | + +## Pricing + +| Tier | Monthly | What's Included | +|---|---|---| +| **Basic** | $49/mo | Health monitoring, config backups, heartbeat alerts, monthly report | +| **Pro** | $97/mo | Everything in Basic + incident clip vault (30-day retention), trends dashboard | +| **Enterprise** | $147/mo | Everything in Pro + custom AI filtering rules, API access, dedicated support | + +**Hardware:** NVR Shield device sold at $149 (BOM ~$41). Pre-flashed, hardened, Tailscale-connected. One device handles all NVRs at a single site. + +## Target Market + +- Existing ITPP customers who purchased Reolink camera systems (4 known, upsell target) +- New Reolink NVR deployments sold through ITPP +- Small/medium businesses with multi-NVR sites + +## Deployment Model + +1. Customer fills out onboarding form (NVR IPs, credentials, site details) +2. Pi Zero 2W pre-flashed at ITPP office with agent, Tailscale, and customer-specific config +3. Device shipped to customer ready to plug in (5-minute onsite deploy) +4. Agent phones home to Core via Tailscale, begins health polling and config backups diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..a3d9319 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,35 @@ +# NVR Shield — Roadmap + +## Phase 1: MVP (Current) + +- [ ] Build agent script (`agent.py`) — poll NVR health, push to Core +- [ ] Config schema and validation +- [ ] Pre-flash Pi Zero 2W image / flashing script +- [ ] Core heartbeat endpoint +- [ ] Core dashboard (site list, health status) +- [ ] Nightly config backup to S3 +- [ ] Marketplace listing on my.itpropartner.com +- [ ] Customer onboarding form + +## Phase 2: Monetization (Post-Validation) + +- [ ] Upsell to 4 existing Reolink customers +- [ ] Incident clip vault (Pro tier) — motion/AI-triggered clip retention +- [ ] Monthly report generation (PDF/email) +- [ ] Alerting rules (disk threshold, camera offline, heartbeat gap) +- [ ] Billing integration (SyncroMSP or manual invoicing) + +## Phase 3: Expansion + +- [ ] Custom AI filtering rules (Enterprise tier) +- [ ] Multi-site dashboard for MSPs with many customers +- [ ] Self-service customer portal (view own cameras, download clips) +- [ ] ONVIF support for non-Reolink NVRs +- [ ] Direct integration with ITPP ticket system (auto-create ticket on NVR fault) + +## Future Possibilities + +- White-label variant for other MSPs/security integrators +- PoE HAT for the Pi (single cable for power + data) +- Rack-mount enclosure for multi-NVR sites +- Mobile app for push notifications on camera outages diff --git a/customer-onboarding-form.md b/customer-onboarding-form.md new file mode 100644 index 0000000..e12e425 --- /dev/null +++ b/customer-onboarding-form.md @@ -0,0 +1,128 @@ +# NVR Shield — Customer Onboarding Form + +> IT Pro Partner · my.itpropartner.com · info@itpropartner.com · (833) 545-4425 + +--- + +## What This Is + +To set up your NVR Shield monitoring, we need details about your Reolink NVR(s) and site network. Fill out what you can below. If you're unsure about anything, skip it — we'll fill in the gaps during a quick onboarding call. + +--- + +## Section 1: Your Information + +| Field | Your Answer | +|---|---| +| Company Name | | +| Contact Name | | +| Contact Email | | +| Contact Phone | | +| Site Address (where NVRs are located) | | +| Best Time for 10-Min Onboarding Call | | + +--- + +## Section 2: Your NVR(s) + +> One NVR Shield device monitors all NVRs at a single site. List every NVR you want monitored. + +### NVR #1 (Primary) + +| Field | Your Answer | Where to Find It | +|---|---|---| +| NVR Model | (e.g. RLN8-410, RLN16-410) | Sticker on NVR or in Reolink app under Device Info | +| NVR IP Address | 192.168.___.___ | Reolink app → Device Settings → Network | +| NVR Admin Username | (default: admin) | If you changed it, use your custom login | +| NVR Admin Password | | We need this to poll health — stored encrypted | +| Number of Cameras Connected | | Reolink app → Camera list | +| Any Cameras Already Offline? | Y / N | If yes, which ones: _____________ | +| Installed Hard Drive Size | (e.g. 2TB, 4TB) | Reolink app → Storage | + +### NVR #2 + +| Field | Your Answer | +|---|---| +| NVR Model | | +| NVR IP Address | | +| NVR Admin Username | | +| NVR Admin Password | | +| Number of Cameras Connected | | +| Any Cameras Already Offline? | Y / N — which: _____________ | +| Installed Hard Drive Size | | + +### NVR #3 + +| Field | Your Answer | +|---|---| +| NVR Model | | +| NVR IP Address | | +| NVR Admin Username | | +| NVR Admin Password | | +| Number of Cameras Connected | | +| Any Cameras Already Offline? | Y / N — which: _____________ | +| Installed Hard Drive Size | | + +> **More than 3 NVRs?** List them on a separate page with the same fields, or tell us the count during onboarding. + +--- + +## Section 3: Network Information + +| Field | Your Answer | +|---|---| +| Internet Provider | (e.g. Comcast, AT&T, Spectrum) | +| Do you have a static IP? | Y / N / Don't Know | +| Network Equipment (router/firewall brand) | (e.g. MikroTik, UniFi, Netgear) | +| Do you have an available Ethernet port near the NVR(s)? | Y / N | +| WiFi Network Name (SSID) — fallback only | | +| WiFi Password — fallback only | | + +> **Note:** NVR Shield prefers a wired Ethernet connection. WiFi is used only as a fallback. We include a USB Ethernet adapter with the device. + +--- + +## Section 4: Plan Selection + +| Tier | Monthly | Includes | +|---|---|---| +| **Basic** | $49/mo | Health monitoring, nightly config backups, heartbeat alerts, monthly report | +| **Pro** | $97/mo | Basic + incident clip vault (30-day retention), trends dashboard | +| **Enterprise** | $147/mo | Pro + custom AI filtering rules, API access, priority support | + +**Hardware:** $149 one-time (NVR Shield device, pre-configured and ready to plug in) + +**Your selection:** ☐ Basic ☐ Pro ☐ Enterprise + +--- + +## Section 5: Agreement + +By signing below, you authorize IT Pro Partner to: + +- Connect NVR Shield to your local network to monitor Reolink NVR health +- Securely store encrypted NVR credentials for automated polling +- Back up NVR configuration files nightly to encrypted cloud storage (Wasabi S3) +- Send automated alerts for camera outages, storage issues, and device health + +**Access is read-only.** NVR Shield does not modify NVR settings, camera configurations, or recording schedules without explicit approval. + +| Signature | Date | +|---|---| +| | | + +--- + +## What Happens Next + +1. Return this form to **info@itpropartner.com** +2. We'll schedule a 10-minute call to verify the details and confirm your WiFi fallback +3. Your NVR Shield device ships within 2 business days, pre-configured and ready to plug in +4. Plug it into power and Ethernet at your site — it phones home automatically +5. You'll receive a welcome email confirming monitoring is active, with a link to your dashboard + +**Questions?** Call (833) 545-4425 or email info@itpropartner.com + +--- + +*IT Pro Partner — Professional Monitoring for Your Security Camera System*