Bluecherry

Bluecherry is a fully‑self‑hosted video surveillance stack that runs natively on Linux. At its core, it captures, stores, and streams video from IP or analog cameras while providing a web‑based UI for playback, configuration, and analytics. The platform is released under the GPL, making it attractive to developers who need a flexible, license‑free solution that can be extended or embedded into larger monitoring infrastructures.

Technical Overview

The application is a multi‑component system:

• Capture Daemon (bluecherry-apps): written in C/C++ and built against libav (FFmpeg) for decoding/encoding, libconfig for configuration files, and MySQL client libraries for metadata persistence.
• Web Server: PHP‑based (using the legacy php5-dev stack) that serves a responsive UI and exposes REST endpoints for camera control, event retrieval, and user management.
• Database: MySQL/MariaDB stores camera definitions, event logs, user credentials, and playback metadata.
• Auxiliary Services: udev rules enable hot‑plug detection of USB cameras, while ALSA libraries support audio capture.

The build system is script‑driven (scripts/build_pkg_native.sh), which generates version headers, Debian control files, and pulls in bundled libraries such as libav. This approach keeps the source tree minimal while still allowing distribution‑specific packaging.

Architecture

• Languages & Frameworks: C/C++ for performance‑critical capture, PHP 5 for the web API and UI.
• Libraries: libav (FFmpeg) for media handling, libconfig for flexible configuration, libbsd for portability utilities.
• Database: MySQL/MariaDB relational schema; no ORM, direct SQL access from PHP.
• Networking: Uses RTSP/RTMP for camera streaming and WebSocket support for real‑time event notifications.
• Deployment: Designed to run on Debian/Ubuntu servers; can be containerized with Docker (Dockerfile available in the repo) or deployed on bare metal. The daemon listens on configurable ports, and the PHP frontend can be served via Apache or Nginx.

Core Capabilities & APIs

• Camera Management: Add, edit, and delete cameras via a RESTful API (/api/cameras). Supports RTSP URLs, ONVIF discovery, and local USB devices.
• Event Recording: Motion detection triggers event creation; events are stored as video segments in a time‑stamped directory structure.
• Playback & Streaming: HLS/MPEG‑TS streaming endpoints for web playback; RTSP endpoints for third‑party players.
• Analytics Hooks: Webhooks can be configured to fire on motion or alarm events, enabling integration with home automation systems or custom dashboards.
• Extensibility: The PHP codebase exposes hooks (before_event, after_event) that developers can override in a dedicated plugin directory. Additionally, the capture daemon accepts command‑line options to plug in custom transcoding pipelines.

Deployment & Infrastructure

• Self‑Hosting Requirements: A 64‑bit Linux server with at least 4 GB RAM (8 GB recommended for high camera counts), a modern multi‑core CPU, and SSD storage for low‑latency video writes.
• Scalability: Horizontal scaling is possible by running multiple capture daemons behind a load balancer, each feeding into a shared MySQL cluster. Video storage can be offloaded to NFS or object stores with custom scripts.
• Containerization: Official Docker images are available, simplifying CI/CD pipelines and enabling quick spin‑ups in Kubernetes or Docker Swarm. The container exposes environment variables for database credentials and camera lists.

Integration & Extensibility

• Plugin System: The PHP layer allows third‑party modules to register new UI components and API endpoints.
• Webhooks & Callbacks: JSON payloads are sent to configurable URLs on motion, alarm, or recording events.
• Custom Analytics: Developers can replace the default motion detector with a machine‑learning model by writing a wrapper around the capture daemon’s output.
• SDK: While no official SDK exists, the open source nature means developers can fork the repo and expose a Go or Python client library that mirrors the REST API.

Developer Experience

• Documentation: The README provides build instructions, dependency lists, and a high‑level architecture diagram. Community forums and Discord offer rapid support for configuration questions.
• Community: An active Discord channel, forum discussions, and open issue tracker mean bugs are addressed quickly.
• Configuration: All settings reside in config.ini files; camera lists are JSON arrays, allowing scripted generation.
• Testing: Unit tests exist for the PHP API; developers can run them with PHPUnit. The C/C++ components are covered by a minimal set of integration tests using check.

Use Cases

1. Home Automation – Embed Bluecherry in a Raspberry Pi‑based home security system, exposing motion events to Home Assistant via webhooks.
2. Enterprise Monitoring – Deploy on a dedicated server to monitor multiple IP cameras across an office, using the API to trigger alerts in Slack or Teams.
3. IoT Edge Devices – Run the capture daemon on edge devices with limited resources, streaming compressed video to a central server for long‑term storage.
4. Custom Analytics Pipelines – Hook the video stream into a Tensor