Deploying OpenSIPS

Introduction

OpenSIPS is a high-performance, multi-functional SIP (Session Initiation Protocol) server that handles call setup, routing, and management for VoIP and real-time communication systems. As one of the most widely deployed open-source SIP servers, OpenSIPS powers telecommunications infrastructure for carriers, enterprises, and service providers worldwide.

Built in C for maximum performance, OpenSIPS can handle thousands of concurrent calls while consuming minimal resources. The modular architecture allows extending functionality through over 170 modules covering authentication, accounting, load balancing, presence, messaging, and integration with external systems.

Key highlights of OpenSIPS:

• Carrier-Grade Performance: Handle thousands of calls per second with sub-millisecond latency
• SIP Proxy and Registrar: Full SIP proxy functionality with user location and registration services
• Load Balancing: Distribute calls across multiple media servers or gateways
• Failover and Redundancy: Automatic failover for high availability deployments
• Real-Time Billing: Integrate with rating engines for prepaid and postpaid billing
• WebRTC Gateway: Bridge WebRTC clients with traditional SIP infrastructure
• REST API: Modern HTTP-based management interface
• Modular Design: Enable only the features you need through the module system
• Extensive Protocol Support: SIP over UDP, TCP, TLS, and WebSocket

This guide walks through deploying OpenSIPS on Klutch.sh using Docker, configuring the SIP server for basic call routing, and preparing for production telecommunications deployments.

Why Deploy OpenSIPS on Klutch.sh

Deploying OpenSIPS on Klutch.sh provides several advantages for telecommunications infrastructure:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds OpenSIPS without complex orchestration. Push to GitHub, and your SIP server deploys automatically.

Persistent Storage: Attach persistent volumes for configuration files, call detail records, and user databases. Your telephony settings survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for the management interface and secure SIP over TLS connections.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments for configuration changes.

Scalable Resources: Allocate CPU and memory based on expected call volume and concurrent registrations.

Environment Variable Management: Securely store database credentials and API keys through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain for SIP services and the management interface.

Always-On Availability: Your telecommunications infrastructure remains accessible 24/7 for uninterrupted voice services.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your OpenSIPS configuration
• Basic familiarity with Docker and containerization concepts
• Understanding of SIP protocol fundamentals
• (Optional) A database for user authentication and call records
• (Optional) A custom domain for your SIP services

Understanding OpenSIPS Architecture

OpenSIPS follows a modular architecture optimized for telecommunications:

Core Engine: The main process handles SIP message parsing, transaction management, and routing logic with minimal overhead.

Module System: Functionality is extended through loadable modules. Core modules handle SIP functions, while database, authentication, and integration modules connect to external systems.

Script Routing: The opensips.cfg configuration file contains routing logic executed for each SIP message. The scripting language supports conditions, transformations, and module function calls.

Database Backend: User credentials, location data, and call records can be stored in MySQL, PostgreSQL, or other databases through database modules.

Management Interface: The MI (Management Interface) provides runtime control and monitoring through various transports including HTTP/JSON.

Preparing Your Repository

To deploy OpenSIPS on Klutch.sh, create a GitHub repository with your Dockerfile and configuration.

Repository Structure

opensips-deploy/
├── Dockerfile
├── README.md
├── .dockerignore
└── conf/
    └── opensips.cfg

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM opensips/opensips:3.4

# Install additional modules if needed
RUN apt-get update && apt-get install -y \
    opensips-restclient-module \
    opensips-json-module \
    && rm -rf /var/lib/apt/lists/*

# Copy custom configuration
COPY conf/opensips.cfg /etc/opensips/opensips.cfg

# Set environment variables
ENV SIP_DOMAIN=${SIP_DOMAIN:-localhost}
ENV LISTEN_IP=${LISTEN_IP:-0.0.0.0}
ENV DB_URL=${DB_URL}

# Expose SIP and management ports
EXPOSE 5060/udp 5060/tcp 5061/tcp 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD opensips-cli -x mi get_statistics core: || exit 1

CMD ["opensips", "-FE"]

Basic Configuration File

Create conf/opensips.cfg:

####### Global Parameters #########

log_level=3
log_stderror=no
log_facility=LOG_LOCAL0

udp_workers=4

socket=udp:0.0.0.0:5060
socket=tcp:0.0.0.0:5060

####### Modules Section ########

mpath="/usr/lib/x86_64-linux-gnu/opensips/modules/"

loadmodule "signaling.so"
loadmodule "sl.so"
loadmodule "tm.so"
loadmodule "rr.so"
loadmodule "maxfwd.so"
loadmodule "usrloc.so"
loadmodule "registrar.so"
loadmodule "textops.so"
loadmodule "sipmsgops.so"
loadmodule "mi_http.so"

modparam("mi_http", "mi_http_root", "mi")
modparam("mi_http", "mi_http_method", 1)
modparam("usrloc", "db_mode", 0)

####### Routing Logic ########

route {
    if (!mf_process_maxfwd_header(10)) {
        sl_send_reply(483,"Too Many Hops");
        exit;
    }

    if (has_totag()) {
        if (loose_route()) {
            if (is_method("INVITE")) {
                record_route();
            }
            route(relay);
        }
        exit;
    }

    if (is_method("CANCEL")) {
        if (t_check_trans())
            t_relay();
        exit;
    }

    t_check_trans();

    if (is_method("REGISTER")) {
        if (!save("location"))
            sl_reply_error();
        exit;
    }

    if (!lookup("location")) {
        t_reply(404, "Not Found");
        exit;
    }

    record_route();
    route(relay);
}

route[relay] {
    if (!t_relay()) {
        sl_reply_error();
    }
    exit;
}

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Environment Variables Reference

Variable	Required	Default	Description
SIP_DOMAIN	No	localhost	SIP domain for the server
LISTEN_IP	No	0.0.0.0	IP address to listen on
DB_URL	No	-	Database connection URL for persistent storage
LOG_LEVEL	No	3	Logging verbosity (0-4)

Deploying OpenSIPS on Klutch.sh

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore conf/ README.md
git commit -m "Initial OpenSIPS deployment configuration"
git remote add origin https://github.com/yourusername/opensips-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “opensips” or “sip-server”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your OpenSIPS Dockerfile.

Configure HTTP Traffic

For the management interface:

• Select HTTP as the traffic type
• Set the internal port to 8080 (OpenSIPS MI HTTP port)

Note: SIP traffic requires UDP/TCP ports that may need additional configuration depending on your deployment requirements.

Set Environment Variables

In the environment variables section, add:

Variable	Value
SIP_DOMAIN	your-app-name.klutch.sh
LOG_LEVEL	3

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/etc/opensips	100 MB	Configuration files
/var/log/opensips	5 GB	Log files and CDRs

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build and deploy your OpenSIPS instance.

Access Management Interface

Once deployment completes, access the MI interface at https://your-app-name.klutch.sh/mi/.

Initial Setup and Configuration

Verifying the Installation

Test OpenSIPS is running through the management interface:

1. Access https://your-app-name.klutch.sh/mi/get_statistics/all
2. Verify core statistics are returned
3. Check active processes and memory usage

Configuring SIP Clients

To register SIP clients:

1. Configure clients with your OpenSIPS domain
2. Set the registrar to your deployment URL
3. Use SIP port 5060 for UDP/TCP connections
4. Configure TLS if using secure SIP on port 5061

Adding Authentication

For production deployments, add user authentication:

1. Enable the auth and auth_db modules
2. Configure database connection for user credentials
3. Add authentication checks in the routing script
4. Create user accounts in the database

Troubleshooting Common Issues

Registration Failures

• Verify SIP domain matches configuration
• Check firewall rules for SIP ports
• Review authentication credentials
• Examine SIP trace logs

Call Routing Issues

• Verify user location lookups succeed
• Check routing script logic
• Enable debug logging temporarily
• Use SIP debugging tools

Performance Problems

• Increase UDP workers for higher call volumes
• Monitor memory usage
• Review timer and transaction settings
• Consider database connection pooling

Additional Resources

• Official OpenSIPS Website
• OpenSIPS Tutorials
• OpenSIPS 3.4 Manual
• OpenSIPS GitHub Repository
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying OpenSIPS on Klutch.sh provides a foundation for carrier-grade VoIP and real-time communications infrastructure. The combination of OpenSIPS’s powerful SIP processing capabilities and Klutch.sh’s deployment simplicity enables building telecommunications services without managing physical infrastructure.

Whether you’re building a small office phone system or a large-scale telecommunications platform, OpenSIPS on Klutch.sh offers the performance and reliability required for production voice services.