How sipcapture/homer works
Project Type & Purpose
• HOMER 10 is a full-stack, headless observability platform for VoIP/RTC packet and event capture, built around the HEP/EEP protocol.
• It comprises capture agents (heplify), ingestion servers (heplify-server), API services (homer-app), a UI layer (homer-ui), and ancillary pieces (docker manifests, installer script).
File-Structure Analysis
• Top-level modules:
• heplify – CLI-based packet-capture agent
• heplify-server – ingestion microservice(s)
• homer-app – API/backend application
• homer-ui – front-end/dashboard (Grafana-based)
• homer-docker – Docker Compose / container orchestration definitions
• homer-installer – setup automation script
• CI/CD: several GitHub Actions workflows for building each component.
• Submodules: shared libraries or protocol definitions.
README Insights
• Data types: SIP, RTP/RTCP, logs, metrics, traces, CDRs, syslog.
• Storage: “NoSQL” Observability APIs (qryn), Prometheus/InfluxDB (timeseries), Loki (logs).
• UI: Grafana dashboards, headless architecture, backwards-compatible HEP encapsulation.
1. Agents (“heplify” binaries)
2. Ingestion Cluster (“heplify-server” microservices)
3. Message/Events Bus (internal queue or direct write to qryn API)
4. Storage Backends
– Event store (qryn)
– Metrics store (Prometheus/InfluxDB)
– Logs store (Loki or syslog receivers)
5. API Layer (“homer-app”)
6. Visualization/UI (“homer-ui” via Grafana)
7. Orchestration / Deployment (Docker Compose / Kubernetes manifests from homer-docker, installer scripts)
8. External Integrations: SIP platforms, Kamailio/OpenSIPS/Asterisk clients, CDR producers
B. Relationships & Data Flows
– Agents capture traffic → encapsulate in HEP → send via UDP/TCP → heplify-server ingestion endpoint
– heplify-server parses HEP packets → publishes events/metrics/logs → writes to qryn, Prometheus, Loki
– homer-app queries storage backends (qryn for events, Prom/Influx for metrics, Loki for logs) → exposes REST/gRPC APIs
– homer-ui (Grafana) fetches via API → renders dashboards
– Docker/installer module deploys all services, wires internal networking
C. Architectural Patterns & Principles
– Microservices: separate capture, ingestion, API, and UI
– Event-driven pipeline: HEP ingestion → fan-out to multiple stores
– Headless observability: standardized API layer decoupled from UI
– Backwards compatibility: HEPv3 encapsulation preserved end-to-end
D. Key Technologies
– Protocol: HEP/EEP over UDP/TCP
– Ingestion: Go-based heplify-server
– Storage: qryn API (NoSQL for events), Prometheus/InfluxDB, Loki
– API: Node/Go (homer-app)
– UI: Grafana dashboards configured by homer-ui module
– Deployment: Docker Compose, bash installer