Deploying SIPCAPTURE Homer

Introduction

Homer is the leading open-source VoIP capture and monitoring platform, developed by SIPCAPTURE. It provides enterprise-grade capabilities for capturing, indexing, and analyzing SIP, RTP, and RTCP traffic at massive scale. Used by telecommunications providers worldwide, Homer transforms raw VoIP data into actionable insights.

The platform consists of capture agents (HEPlify), a processing backend, and a modern web interface (Homer 7/HOMER-APP) for visualization and analysis. Homer supports the HEP protocol for efficient, standardized VoIP data transmission and can handle billions of calls with proper infrastructure.

Key highlights of SIPCAPTURE Homer:

Massive Scale: Handle billions of call records with efficient indexing
HEP Protocol: Industry-standard encapsulation for VoIP data
Call Flow Visualization: Interactive ladder diagrams for SIP message flows
RTP Quality Analysis: Jitter, packet loss, and MOS score monitoring
Multi-Protocol Support: SIP, RTCP, RTCP-XR, ISUP, and more
Advanced Search: Full-text search across all call metadata
Custom Dashboards: Build tailored monitoring views
Alerting System: Configure alerts for quality and error thresholds
API Integration: RESTful API for automation and integration
Grafana Integration: Export metrics to Grafana dashboards
Open Source: Apache 2.0 licensed with active community

This guide walks through deploying Homer on Klutch.sh using Docker, configuring capture agents, and setting up the platform for VoIP monitoring.

Why Deploy Homer on Klutch.sh

Deploying Homer on Klutch.sh provides several advantages for VoIP monitoring:

Simplified Deployment: Klutch.sh automatically builds your Homer configuration without complex infrastructure setup.

Persistent Storage: Attach persistent volumes for call data. Historical records survive container restarts and redeployments.

HTTPS by Default: Secure access to your monitoring dashboard with automatic SSL certificates.

Scalable Resources: Allocate CPU and memory based on call volume and retention needs.

GitHub Integration: Store configuration in version control for reproducible deployments.

Always-On Monitoring: 24/7 availability ensures continuous visibility into your VoIP infrastructure.

Prerequisites

Before deploying Homer on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Homer configuration
Basic familiarity with Docker and containerization concepts
Understanding of SIP protocol and VoIP infrastructure
PostgreSQL database (managed or self-hosted)
(Optional) A custom domain for your Homer instance

Homer Architecture

Homer consists of several components:

HEPlify: Capture agent for SIP/RTP traffic
HEPlify-Server: HEP collector and processor
Homer-APP: Web interface for visualization
PostgreSQL: Primary database for call records
Prometheus: Optional metrics collection

Deploying Homer on Klutch.sh

Create Your Repository

Create a new GitHub repository for your Homer deployment. Add a Dockerfile:

FROM sipcapture/homer-app:latest

ENV HTTP_PORT=8080
ENV DB_HOST=your-postgres-host
ENV DB_USER=homer
ENV DB_PASS=your-password
ENV DB_NAME=homer

EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/api/v3/status || exit 1

Push to GitHub

Commit and push your Dockerfile to your GitHub repository.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “homer” or “voip-capture”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8080

Set Environment Variables

Add the following environment variables:

Variable	Value
`DB_HOST`	PostgreSQL host address
`DB_USER`	Database username
`DB_PASS`	Database password
`DB_NAME`	Database name
`HTTP_PORT`	`8080`

Attach Persistent Volumes

Add the following volumes for data persistence:

Mount Path	Recommended Size	Purpose
`/homer-config`	1 GB	Configuration files
`/homer-data`	10 GB	Local data cache

Deploy Your Application

Click Deploy to start the build process.

Access Homer Dashboard

Once deployment completes, access your Homer dashboard at the provided URL. Default credentials are admin/admin.

Database Configuration

PostgreSQL Setup

Homer requires PostgreSQL for storing call data:

Create PostgreSQL database for Homer
Run Homer schema initialization
Configure connection in environment variables
Set up appropriate indexes for performance

Database Schema

Homer uses multiple schemas for different data types:

hep_proto_1_default: SIP messages
hep_proto_5_default: RTCP reports
hep_proto_100_default: Logs

Retention Policies

Configure data retention:

Access Homer settings
Set retention periods per data type
Schedule cleanup jobs
Monitor storage usage

Capture Agent Deployment

Installing HEPlify

Deploy capture agents on your VoIP servers:

FROM sipcapture/heplify:latest

ENV HEPLIFY_HEPSERVER=your-heplify-server:9060
ENV HEPLIFY_CAPTURE=sip,rtcp
ENV HEPLIFY_INTERFACE=eth0

HEPlify Configuration

Configure capture parameters:

Option	Description
`HEPLIFY_INTERFACE`	Network interface to capture
`HEPLIFY_HEPSERVER`	HEPlify-server destination
`HEPLIFY_CAPTURE`	Protocols to capture
`HEPLIFY_FILTER`	BPF filter expression

HEPlify-Server Deployment

Deploy the HEP collector:

FROM sipcapture/heplify-server:latest

ENV HEPLIFYSERVER_DBADDR=postgres-host:5432
ENV HEPLIFYSERVER_DBUSER=homer
ENV HEPLIFYSERVER_DBPASS=password
ENV HEPLIFYSERVER_DBNAME=homer

EXPOSE 9060/udp
EXPOSE 9061/tcp

Call Analysis Features

Call Flow Visualization

Analyze SIP message flows:

Search for a call by caller/callee
Click on call record
View interactive ladder diagram
Examine individual messages
Export as image or PCAP

Quality Metrics

Monitor call quality indicators:

RTCP Metrics: Jitter, packet loss, round-trip time
RTCP-XR: Extended quality reports
MOS Estimation: Mean Opinion Score calculation
Network Metrics: IP-level analysis

Advanced Search

Find specific calls using:

Correlation ID: Track calls across proxies
Phone Numbers: Search by caller or callee
IP Addresses: Filter by endpoints
Time Range: Specify date/time windows
Quality Filters: Find degraded calls

Dashboard Configuration

Built-in Dashboards

Homer includes pre-configured dashboards:

Home: Overview of call activity
Search: Advanced call search
Call Flow: Message visualization
Statistics: Aggregate metrics

Custom Dashboards

Create custom monitoring views:

Navigate to dashboard builder
Add widgets from library
Configure data queries
Arrange layout
Save and share

Available visualization widgets:

Line/bar charts
Pie charts
Tables
Counters
Maps
Text panels

Alerting System

Configuring Alerts

Set up alerts for issues:

Access alerting configuration
Define alert conditions
Set notification channels
Configure frequency and throttling

Alert Types

Monitor various conditions:

Error Rates: SIP error response thresholds
Quality Degradation: MOS below threshold
Volume Anomalies: Unusual call patterns
Registration Failures: Authentication issues

Notification Channels

Configure alert delivery:

Email notifications
Webhook integrations
Slack/Teams channels
PagerDuty integration

Grafana Integration

Prometheus Metrics

Export metrics to Prometheus:

Enable Prometheus exporter in Homer
Configure scrape target in Prometheus
Access metrics at /metrics endpoint

Grafana Dashboards

Import Homer dashboards in Grafana:

Add Prometheus data source
Import community dashboards
Customize as needed

API Usage

Authentication

Obtain API token:

POST /api/v3/auth
{
  "username": "admin",
  "password": "password"
}

Search API

Query call records programmatically:

POST /api/v3/search/call/message
Authorization: Bearer YOUR_TOKEN
{
  "param": {
    "search": {"from_user": "1001"},
    "timestamp": {"from": 1704067200, "to": 1704153600}
  }
}

Best Practices

Performance Optimization

Capture Filtering: Filter at capture point to reduce volume
Index Optimization: Ensure proper PostgreSQL indexes
Retention Policies: Implement aggressive retention for large volumes

Security Considerations

Change Default Credentials: Update admin password immediately
Network Segmentation: Restrict HEP traffic to trusted sources
HTTPS: Always use encrypted connections

High Availability

Database Replication: Use PostgreSQL replication
Multiple Collectors: Deploy redundant HEPlify-servers
Load Balancing: Distribute capture agent traffic

Troubleshooting

No Data Appearing

Verify HEPlify agents are running
Check HEPlify-server connectivity
Confirm database connection
Review capture filters

Performance Issues

Check database performance
Review index usage
Optimize retention policies
Scale resources as needed

Search Returning Empty

Verify time range includes data
Check search syntax
Confirm data exists in database

Additional Resources

Conclusion

Deploying SIPCAPTURE Homer on Klutch.sh provides enterprise-grade VoIP monitoring capabilities for your infrastructure. With comprehensive capture, analysis, and visualization features, you can maintain visibility into your telecommunications systems and quickly troubleshoot issues. The combination of Homer’s powerful analysis engine with Klutch.sh’s reliable hosting ensures your VoIP monitoring platform is always available.