f02dbaad8c
Front-door for the repo. Pitches the project, surfaces known limitations honestly (timeline not live, CTR not authenticated, no migrations), and links into the three doc trees: home user guide, operator guide, and architecture overview + 12 subsystem references. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
132 lines
5.4 KiB
Markdown
132 lines
5.4 KiB
Markdown
# Vigilar
|
|
|
|
> DIY offline-first home security. Your cameras, your house, your data.
|
|
|
|
Vigilar runs on a small mini PC in your home, records from your IP cameras,
|
|
detects motion, and pushes notifications to your phone — with no cloud, no
|
|
account, and no external service in the critical path.
|
|
|
|
<!-- Screenshot placeholder: replace with a real UI grid shot when available. -->
|
|
|
|
|
|
## Why Vigilar
|
|
|
|
- **Offline-first.** No cloud dependency. No external calls in the hot path.
|
|
- **Multi-camera live view.** HLS grid for bandwidth efficiency, MJPEG single
|
|
view for low-latency focus.
|
|
- **On-device motion detection.** OpenCV MOG2 with a 5-second pre-motion ring
|
|
buffer, so the run-up to a trigger is captured.
|
|
- **Adaptive FPS.** Cameras idle at 2 FPS and jump to 30 FPS on motion.
|
|
- **Event timeline and highlight reels.** Plus timelapses and visitor, pet,
|
|
and wildlife tracking as separate views.
|
|
- **Phone push notifications.** PWA + VAPID web push. No Firebase, no
|
|
Google Cloud Messaging.
|
|
- **Encrypted recordings at rest.** AES-256-CTR `.vge` files, key stays on
|
|
your box. (Confidential, not tamper-evident — see the
|
|
[Operator Guide](docs/operator-guide.md) for the details of the threat
|
|
model.)
|
|
- **UPS aware.** NUT integration, graceful shutdown on critical battery.
|
|
- **Runs on a cheap mini PC.** 4 GB RAM, 128 GB SSD, any modern x86_64 box.
|
|
|
|
## Quick paths
|
|
|
|
| I want to… | Start here |
|
|
|----------------------------------------------|--------------------------------------------------------------|
|
|
| Set it up at home on a mini PC | [Home User Guide](docs/home-user-guide.md) |
|
|
| Run it as a self-hoster / sysadmin | [Operator Guide](docs/operator-guide.md) |
|
|
| Understand how it works internally | [Architecture Overview](docs/architecture/overview.md) |
|
|
| Pick cameras that work well with it | [Camera Hardware Guide](docs/camera-hardware-guide.md) |
|
|
|
|
## 60-second overview
|
|
|
|
```
|
|
[IP cameras] ──RTSP──▶ [mini PC running Vigilar] ──LAN──▶ [phone / browser]
|
|
│
|
|
└── optional nightly ──▶ [NAS]
|
|
```
|
|
|
|
- **Language:** Python 3.11+
|
|
- **Web:** Flask + Bootstrap 5 dark + `hls.js`
|
|
- **Storage:** SQLite (WAL) via SQLAlchemy Core
|
|
- **Bus:** Local Mosquitto on `127.0.0.1:1883`
|
|
- **Video:** OpenCV (capture + motion), FFmpeg subprocess (recording, HLS)
|
|
|
|
## Status
|
|
|
|
**Alpha.** Works on the author's hardware. Expect rough edges and breaking
|
|
changes. Not recommended for anyone who cannot read a stack trace.
|
|
|
|
Known limitations worth calling out up front:
|
|
|
|
- The in-browser event timeline does not yet update live. Push
|
|
notifications to your phone work in real time; the timeline itself
|
|
needs a page refresh.
|
|
- Recording encryption is AES-256-CTR: confidential at rest, but not
|
|
tamper-evident.
|
|
- There is no automated database migration framework yet. Schema changes
|
|
are forward-only.
|
|
|
|
See the [Operator Guide](docs/operator-guide.md) for the full list.
|
|
|
|
## Installation (TL;DR)
|
|
|
|
```bash
|
|
git clone <repo URL> vigilar
|
|
cd vigilar
|
|
sudo ./scripts/install.sh
|
|
sudo systemctl enable --now vigilar
|
|
```
|
|
|
|
Then open `http://<mini-pc-ip>:49735` on your LAN.
|
|
|
|
For the full walkthrough (OS install, camera setup, PIN, push
|
|
notifications, NAS backup), see the
|
|
[Home User Guide](docs/home-user-guide.md).
|
|
|
|
For configuration, CLI, secrets, backups, and upgrades, see the
|
|
[Operator Guide](docs/operator-guide.md).
|
|
|
|
## Documentation
|
|
|
|
- **User guides**
|
|
- [Home User Guide](docs/home-user-guide.md) — mini PC to working cameras,
|
|
step by step.
|
|
- [Operator Guide](docs/operator-guide.md) — configuration, CLI, backups,
|
|
security, upgrades.
|
|
- [Camera Hardware Guide](docs/camera-hardware-guide.md) — picking and
|
|
wiring up cameras.
|
|
- **Architecture**
|
|
- [Overview](docs/architecture/overview.md) — process model, MQTT bus,
|
|
data flow, storage layout.
|
|
- [Conventions](docs/architecture/conventions.md) — coding rules for
|
|
contributors.
|
|
- [Subsystems](docs/architecture/subsystems/) — one short reference per
|
|
subsystem: [camera](docs/architecture/subsystems/camera.md),
|
|
[detection](docs/architecture/subsystems/detection.md),
|
|
[events](docs/architecture/subsystems/events.md),
|
|
[alerts](docs/architecture/subsystems/alerts.md),
|
|
[sensors](docs/architecture/subsystems/sensors.md),
|
|
[ups](docs/architecture/subsystems/ups.md),
|
|
[storage](docs/architecture/subsystems/storage.md),
|
|
[highlights](docs/architecture/subsystems/highlights.md),
|
|
[presence](docs/architecture/subsystems/presence.md),
|
|
[pets](docs/architecture/subsystems/pets.md),
|
|
[health](docs/architecture/subsystems/health.md),
|
|
[web](docs/architecture/subsystems/web.md).
|
|
|
|
## License
|
|
|
|
Vigilar is distributed under the **GNU General Public License v3.0**. See
|
|
`LICENSE` for the full text. (If the `LICENSE` file is not yet in the tree,
|
|
it will be added in a follow-up.)
|
|
|
|
## Contributing
|
|
|
|
Issues and pull requests are welcome. Before sending a PR:
|
|
|
|
- Read [`CLAUDE.md`](CLAUDE.md) for the project's code conventions, or the
|
|
human-friendly distillation at
|
|
[`docs/architecture/conventions.md`](docs/architecture/conventions.md).
|
|
- Run `ruff check vigilar/` and `pytest` — both must pass.
|
|
- Keep commits small and focused.
|