Skip to content
Klutch.sh Docs

Deploying Flexisip

Introduction

Flexisip is a powerful, open-source SIP (Session Initiation Protocol) proxy server developed by Belledonne Communications. Designed for VoIP and real-time communications, Flexisip provides enterprise-grade SIP routing, load balancing, presence management, and push notification support for mobile devices. Built with scalability and reliability in mind, it handles millions of messages and calls daily for telecom operators and businesses worldwide.

Deploying Flexisip on Klutch.sh gives you automatic Dockerfile detection, persistent storage for configuration and logs, TCP traffic support for SIP signaling, and seamless scaling capabilities. This guide provides detailed instructions for deploying Flexisip with production-ready configuration, MySQL backend integration, Redis caching, and best practices for running a reliable VoIP infrastructure.

Why Deploy Flexisip on Klutch.sh?

  • Automatic Dockerfile Detection: Klutch.sh detects your Dockerfile automatically and builds your container
  • TCP Traffic Support: Native support for SIP signaling on TCP protocol
  • Persistent Storage: Attach volumes for configuration files, logs, and certificates
  • Instant HTTPS: Secure endpoints with automatic SSL/TLS certificates
  • Database Integration: Easy connection to MySQL for user management and Redis for caching
  • Easy Scaling: Scale your SIP infrastructure based on traffic demands
  • GitHub Integration: Deploy directly from your GitHub repository
  • High Availability: Run multiple instances for load balancing and failover

Prerequisites

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

  • A Klutch.sh account
  • A GitHub account with a repository for your project
  • Docker installed locally for testing (optional but recommended)
  • Basic familiarity with SIP protocol and VoIP concepts
  • MySQL database (see our MySQL guide for deployment instructions)
  • Redis cache (optional but recommended - see our Redis guide)
  • Understanding of network protocols and port configuration

Understanding Flexisip Architecture

Flexisip follows a modular SIP server architecture designed for scalability:

Core Components:

  • SIP Proxy: Handles SIP registration, routing, and message forwarding
  • Presence Server: Manages user presence and availability status
  • Conference Server: Enables multi-party audio/video conferencing
  • Push Notification Gateway: Delivers push notifications to mobile devices (APNs, FCM)
  • Load Balancer: Distributes traffic across multiple backend servers
  • Media Relay: TURN/STUN server for NAT traversal and media routing

Default Configuration:

  • SIP Port: 5060 (TCP/UDP)
  • SIP TLS Port: 5061 (TLS)
  • HTTP Admin Port: 8080
  • Database: MySQL (user accounts, routing tables)
  • Cache: Redis (registration cache, presence)
  • Transport Protocols: TCP, UDP, TLS, WebSocket

Directory Structure:

/etc/flexisip/
├── flexisip.conf          # Main configuration file
├── users.db               # SQLite user database (dev)
├── tls/                   # TLS certificates
│   ├── cert.pem
│   └── key.pem
└── modules/               # Module configurations


/var/log/flexisip/
├── flexisip.log           # Main log file
└── errors.log             # Error logs


/var/lib/flexisip/
├── registrations/         # Registration cache
└── presence/              # Presence data

Installation and Setup

Step 1: Create Your Repository

    Create a new GitHub repository for your Flexisip deployment:

    Terminal window
    mkdir flexisip-deployment
    cd flexisip-deployment
    git init

Step 2: Create the Dockerfile

    Create a Dockerfile in the root of your repository. This Dockerfile will set up Flexisip with all necessary dependencies:

    FROM debian:bullseye-slim
    

    # Install dependencies
    RUN apt-get update && apt-get install -y \
        wget \
        gnupg2 \
        software-properties-common \
        lsb-release \
        ca-certificates \
        curl \
        && rm -rf /var/lib/apt/lists/*
    

    # Add Belledonne Communications repository
    RUN wget -O- https://linphone.org/snapshots/belledonne-communications-release.gpg | apt-key add - && \
        echo "deb http://linphone.org/snapshots/debian bullseye main" > /etc/apt/sources.list.d/linphone.list
    

    # Install Flexisip
    RUN apt-get update && apt-get install -y \
        flexisip \
        flexisip-presence \
        mysql-client \
        redis-tools \
        && rm -rf /var/lib/apt/lists/*
    

    # Create necessary directories
    RUN mkdir -p /etc/flexisip/tls \
                 /var/log/flexisip \
                 /var/lib/flexisip/registrations \
                 /var/lib/flexisip/presence
    

    # Copy configuration files
    COPY flexisip.conf /etc/flexisip/flexisip.conf
    COPY docker-entrypoint.sh /usr/local/bin/
    RUN chmod +x /usr/local/bin/docker-entrypoint.sh
    

    # Expose ports
    # SIP: 5060 (TCP/UDP), 5061 (TLS)
    # HTTP Admin: 8080
    # WebSocket: 5062
    EXPOSE 5060/tcp 5060/udp 5061/tcp 8080 5062
    

    # Health check
    HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
        CMD flexisip --check-config || exit 1
    

    # Set entrypoint
    ENTRYPOINT ["docker-entrypoint.sh"]
    CMD ["flexisip", "--config-file", "/etc/flexisip/flexisip.conf"]

    This Dockerfile:

    • Uses Debian Bullseye as the base image
    • Installs Flexisip from official Belledonne Communications repository
    • Includes MySQL and Redis clients for backend connectivity
    • Creates necessary directories for configuration and logs
    • Exposes SIP ports (5060, 5061) and admin interface (8080)
    • Includes health checks for monitoring

Step 3: Create Flexisip Configuration

    Create flexisip.conf with production-ready settings:

    # Flexisip Configuration File
    

    ##
    ## Global Settings
    ##
    [global]
    # Server identity
    server-name=flexisip-server
    # Transports (tcp, udp, tls)
    transports=sip:*:5060;transport=tcp sip:*:5060;transport=udp sips:*:5061;transport=tls
    # Number of threads
    threads=4
    # Log level: debug, message, warning, error
    log-level=message
    # Log file
    log-file=/var/log/flexisip/flexisip.log
    

    ##
    ## Module: Forward
    ##
    [module::Forward]
    enabled=true
    # Route to backend SIP servers (if using as load balancer)
    # routes=sip:backend1.example.com;transport=tcp sip:backend2.example.com;transport=tcp
    

    ##
    ## Module: Registrar
    ##
    [module::Registrar]
    enabled=true
    # Database configuration
    db-implementation=mysql
    # MySQL connection string
    db-connection-string=db='sip' user='${MYSQL_USER}' password='${MYSQL_PASSWORD}' host='${MYSQL_HOST}' port='${MYSQL_PORT}'
    # Registration expiration time (seconds)
    reg-expire=3600
    # Maximum registrations per address
    max-contacts-per-address=10
    

    # Redis cache for registrations (optional but recommended)
    redis-server-domain=${REDIS_HOST}
    redis-server-port=${REDIS_PORT}
    redis-auth-password=${REDIS_PASSWORD}
    

    ##
    ## Module: Authentication
    ##
    [module::Authentication]
    enabled=true
    # Authentication database
    auth-domains=sip.example.com
    # Database for authentication
    db-implementation=mysql
    db-connection-string=db='sip' user='${MYSQL_USER}' password='${MYSQL_PASSWORD}' host='${MYSQL_HOST}' port='${MYSQL_PORT}'
    # Algorithm: MD5, SHA256
    hashing-algorithm=SHA256
    # Disable authentication (for testing only)
    # disable-authentication=false
    

    ##
    ## Module: Presence
    ##
    [module::Presence]
    enabled=true
    # Presence server configuration
    presence-server=sip:presence.example.com
    # Database for presence
    db-implementation=redis
    redis-server-domain=${REDIS_HOST}
    redis-server-port=${REDIS_PORT}
    redis-auth-password=${REDIS_PASSWORD}
    

    ##
    ## Module: Router
    ##
    [module::Router]
    enabled=true
    # Static routes (optional)
    # static-targets=sip:backend.example.com
    

    ##
    ## Module: PushNotification
    ##
    [module::PushNotification]
    enabled=true
    # Apple Push Notification Service (APNs)
    apns-certificate-path=/etc/flexisip/tls/apns-cert.pem
    apns-certificate-key-path=/etc/flexisip/tls/apns-key.pem
    # Firebase Cloud Messaging (FCM)
    firebase-service-account-file=/etc/flexisip/fcm-service-account.json
    # Maximum queue size
    max-queue-size=10000
    

    ##
    ## Module: MediaRelay
    ##
    [module::MediaRelay]
    enabled=false
    # STUN/TURN server configuration
    # stun-server=stun.example.com:3478
    # turn-server=turn.example.com:3478
    # turn-username=turnuser
    # turn-password=turnpassword
    

    ##
    ## Module: Transcoder
    ##
    [module::Transcoder]
    enabled=false
    # Audio codecs
    # audio-codecs=opus speex pcmu pcma
    

    ##
    ## TLS Configuration
    ##
    [tls]
    # TLS certificate and key
    tls-certificate-file=/etc/flexisip/tls/cert.pem
    tls-certificate-key-file=/etc/flexisip/tls/key.pem
    # TLS cipher suites
    tls-ciphers=HIGH:!aNULL:!MD5
    # Require client certificate
    tls-verify-client=false
    

    ##
    ## HTTP Admin Interface
    ##
    [http]
    enabled=true
    bind-address=0.0.0.0:8080
    # Enable CORS
    enable-cors=true
    # Admin authentication
    admin-username=${ADMIN_USERNAME}
    admin-password=${ADMIN_PASSWORD}

    This configuration includes:

    • Multi-transport support (TCP, UDP, TLS)
    • MySQL backend for user registration
    • Redis caching for performance
    • Push notification support for mobile devices
    • HTTP admin interface for management
    • Presence server integration
    • TLS/encryption support

Step 4: Create Docker Entrypoint Script

    Create docker-entrypoint.sh for initialization:

    #!/bin/bash
    

    set -e
    

    echo "Starting Flexisip initialization..."
    

    # Check required environment variables
    if [ -z "$MYSQL_HOST" ]; then
        echo "ERROR: MYSQL_HOST environment variable is required"
        exit 1
    fi
    

    if [ -z "$MYSQL_USER" ]; then
        echo "ERROR: MYSQL_USER environment variable is required"
        exit 1
    fi
    

    if [ -z "$MYSQL_PASSWORD" ]; then
        echo "ERROR: MYSQL_PASSWORD environment variable is required"
        exit 1
    fi
    

    # Wait for MySQL to be ready
    echo "Waiting for MySQL at ${MYSQL_HOST}:${MYSQL_PORT:-3306}..."
    until mysql -h"$MYSQL_HOST" -P"${MYSQL_PORT:-3306}" -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -e "SELECT 1" &> /dev/null
    do
        echo "MySQL is unavailable - sleeping"
        sleep 2
    done
    echo "MySQL is up and ready!"
    

    # Wait for Redis if configured
    if [ -n "$REDIS_HOST" ]; then
        echo "Waiting for Redis at ${REDIS_HOST}:${REDIS_PORT:-6379}..."
        until redis-cli -h "$REDIS_HOST" -p "${REDIS_PORT:-6379}" -a "$REDIS_PASSWORD" ping &> /dev/null
        do
            echo "Redis is unavailable - sleeping"
            sleep 2
        done
        echo "Redis is up and ready!"
    fi
    

    # Initialize MySQL database if needed
    echo "Initializing Flexisip database..."
    mysql -h"$MYSQL_HOST" -P"${MYSQL_PORT:-3306}" -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" <<-EOSQL
        CREATE DATABASE IF NOT EXISTS sip CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    

        USE sip;
    

        CREATE TABLE IF NOT EXISTS accounts (
            id INT AUTO_INCREMENT PRIMARY KEY,
            username VARCHAR(255) NOT NULL,
            domain VARCHAR(255) NOT NULL,
            password VARCHAR(255) NOT NULL,
            algorithm VARCHAR(50) DEFAULT 'SHA256',
            enabled BOOLEAN DEFAULT TRUE,
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
            UNIQUE KEY unique_account (username, domain)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
    

        CREATE TABLE IF NOT EXISTS registrations (
            id INT AUTO_INCREMENT PRIMARY KEY,
            username VARCHAR(255) NOT NULL,
            domain VARCHAR(255) NOT NULL,
            contact VARCHAR(500) NOT NULL,
            expires INT NOT NULL,
            user_agent VARCHAR(255),
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
            INDEX idx_user (username, domain),
            INDEX idx_expires (expires)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
    EOSQL
    

    echo "Database initialization complete!"
    

    # Set proper permissions
    chown -R flexisip:flexisip /var/log/flexisip /var/lib/flexisip
    

    # Validate configuration
    echo "Validating Flexisip configuration..."
    flexisip --check-config
    

    echo "Starting Flexisip..."
    exec "$@"

    Make it executable:

    Terminal window
    chmod +x docker-entrypoint.sh

Step 5: Create Environment Configuration

    Create .env.example to document environment variables:

    Terminal window
    # Flexisip Environment Configuration
    

    # Application Settings
    SERVER_NAME=flexisip-server
    LOG_LEVEL=message
    ADMIN_USERNAME=admin
    ADMIN_PASSWORD=changeme123
    

    # MySQL Database Configuration (Required)
    MYSQL_HOST=mysql.example-app.klutch.sh
    MYSQL_PORT=8000
    MYSQL_USER=flexisip
    MYSQL_PASSWORD=strongpassword123
    MYSQL_DATABASE=sip
    

    # Redis Configuration (Optional but Recommended)
    REDIS_HOST=redis.example-app.klutch.sh
    REDIS_PORT=8000
    REDIS_PASSWORD=redispassword123
    

    # SIP Domain Configuration
    SIP_DOMAIN=sip.example.com
    

    # Push Notifications (Optional)
    # APNS_CERTIFICATE_PATH=/etc/flexisip/tls/apns-cert.pem
    # APNS_KEY_PATH=/etc/flexisip/tls/apns-key.pem
    # FCM_SERVICE_ACCOUNT=/etc/flexisip/fcm-service-account.json
    

    # TLS Configuration (Optional)
    # TLS_CERTIFICATE=/etc/flexisip/tls/cert.pem
    # TLS_KEY=/etc/flexisip/tls/key.pem
    

    # Media Relay Configuration (Optional)
    # STUN_SERVER=stun.l.google.com:19302
    # TURN_SERVER=turn.example.com:3478
    # TURN_USERNAME=turnuser
    # TURN_PASSWORD=turnpassword

    Important: Never commit actual secrets to your repository. Set these as environment variables in Klutch.sh.

Step 6: Create README Documentation

    Create a README.md file:

    # Flexisip SIP Server Deployment
    

    This repository contains the Docker configuration for deploying Flexisip on Klutch.sh.
    

    ## Features
    

    - Full SIP proxy server with registration and routing
    - MySQL backend for user management
    - Redis caching for performance
    - Push notification support (APNs, FCM)
    - TLS/encryption support
    - HTTP admin interface
    - Presence server integration
    

    ## Prerequisites
    

    - MySQL database (deploy separately on Klutch.sh)
    - Redis cache (optional but recommended)
    - Valid TLS certificates (for production)
    - Push notification credentials (for mobile apps)
    

    ## Deployment
    

    1. Push this repository to GitHub
    2. Deploy MySQL and Redis on Klutch.sh
    3. Create a new app on Klutch.sh
    4. Connect your GitHub repository
    5. Set environment variables for database connection
    6. Klutch.sh automatically detects and builds the Dockerfile
    7. Configure TCP traffic on port 5060
    8. Attach persistent volumes for logs and config
    9. Deploy and test SIP connectivity
    

    ## Local Development
    

    ```bash
    docker build -t flexisip .
    docker run -p 5060:5060 -p 8080:8080 \
      -e MYSQL_HOST=localhost \
      -e MYSQL_USER=flexisip \
      -e MYSQL_PASSWORD=password \
      flexisip

    Configuration

    Edit flexisip.conf to customize:

    • SIP domain and transports
    • Authentication settings
    • Database connections
    • Module enablement
    • TLS configuration

    Monitoring

    Access the admin interface at http://localhost:8080 with configured credentials.

    </ol>
    

    ### Step 7: Push to GitHub
    

    <ol>
    

    Add all files and push to your GitHub repository:
    

    ```bash
    # Create .gitignore
    cat > .gitignore << 'EOF'
    .env
    *.log
    .DS_Store
    /var/log/
    /var/lib/
    tls/*.pem
    tls/*.key
    *.json
    EOF
    

    # Initialize git and commit
    git add Dockerfile flexisip.conf docker-entrypoint.sh .env.example README.md .gitignore
    git commit -m "Initial Flexisip deployment setup"
    git branch -M main
    git remote add origin https://github.com/YOUR_USERNAME/flexisip-deployment.git
    git push -u origin main

Deploying to Klutch.sh

Now that your repository is ready, follow these steps to deploy Flexisip on Klutch.sh:

  1. Deploy MySQL Database

    Before deploying Flexisip, you need a MySQL database. Follow our MySQL deployment guide to set up MySQL on Klutch.sh.

    Take note of:

    • MySQL hostname (e.g., mysql-app.klutch.sh)
    • Database port (8000 for TCP traffic on Klutch.sh)
    • Username and password
    • Database name

  2. Deploy Redis Cache (Optional but Recommended)

    For better performance, deploy Redis following our Redis deployment guide.

    Take note of:

    • Redis hostname (e.g., redis-app.klutch.sh)
    • Redis port (8000 for TCP traffic on Klutch.sh)
    • Redis password

  3. Log in to Klutch.sh

    Navigate to klutch.sh/app and sign in with your account.

  4. Create a New Project

    Click “Create Project” and give your project a descriptive name like “Flexisip SIP Server”.

  5. Create a New App

    Inside your project, click “Create App” to start a new deployment.

  6. Connect Your GitHub Repository

    • Select GitHub as your source
    • Authorize Klutch.sh to access your repositories if you haven’t already
    • Choose the repository containing your Flexisip Dockerfile
    • Select the branch you want to deploy (typically main)

  7. Configure Traffic Settings

    • Select TCP as the traffic type (Flexisip uses TCP for SIP signaling)
    • This enables external connections on port 8000, which routes to your internal container port

  8. Set Internal Port

    Set the internal port to 5060 (the default SIP port inside the container).

    Klutch.sh will route external traffic from port 8000 to internal port 5060.

  9. Add Environment Variables

    Configure the following environment variables in the Klutch.sh dashboard:

    Required Database Variables:

    • MYSQL_HOST: Your MySQL hostname (e.g., mysql-app.klutch.sh)
    • MYSQL_PORT: 8000 (Klutch.sh external port for TCP services)
    • MYSQL_USER: Your MySQL username
    • MYSQL_PASSWORD: Your MySQL password (mark as secret)
    • MYSQL_DATABASE: sip

    Optional Redis Variables:

    • REDIS_HOST: Your Redis hostname (e.g., redis-app.klutch.sh)
    • REDIS_PORT: 8000
    • REDIS_PASSWORD: Your Redis password (mark as secret)

    Admin Interface:

    • ADMIN_USERNAME: admin
    • ADMIN_PASSWORD: Strong password (mark as secret)

    SIP Configuration:

    • SERVER_NAME: flexisip-server
    • SIP_DOMAIN: Your SIP domain (e.g., sip.example.com)
    • LOG_LEVEL: message (or debug for troubleshooting)

  10. Attach Persistent Volumes

    This is crucial for preserving logs and configuration:

    Volume 1 - Logs:

    • Click “Add Volume”
    • Mount Path: /var/log/flexisip
    • Size: 5GB (adjust based on logging needs)

    Volume 2 - Data:

    • Click “Add Volume”
    • Mount Path: /var/lib/flexisip
    • Size: 10GB (for registration and presence cache)

    Volume 3 - Configuration (Optional):

    • Click “Add Volume”
    • Mount Path: /etc/flexisip
    • Size: 1GB (for persistent configuration and TLS certificates)

    These volumes ensure your logs, registrations, and configuration persist across deployments.

  11. Review and Deploy

    • Review all configuration settings
    • Click “Deploy” to start the build process

    Klutch.sh will:

    • Clone your repository
    • Build the Docker image using your Dockerfile
    • Install Flexisip and all dependencies
    • Configure networking for TCP traffic
    • Start the container
    • Provision an endpoint

    The build typically takes 5-8 minutes.

  12. Access Your Flexisip Server

    Once deployment completes, your Flexisip server will be accessible at:

    • SIP Endpoint: sip:example-app.klutch.sh:8000;transport=tcp
    • Admin Interface: https://example-app.klutch.sh:8080 (if HTTP admin is enabled)

Post-Deployment Configuration

Testing SIP Connectivity

  1. Test with SIP Client

    Use a SIP client like Linphone, Zoiper, or MicroSIP to test connectivity:

    1. Configure your SIP account:

      • Username: testuser@sip.example.com
      • Password: Your configured password
      • Domain: example-app.klutch.sh
      • Port: 8000
      • Transport: TCP

    2. Register the client

    3. Check registration status in Flexisip logs

  2. Verify Database Connection

    Check that Flexisip is connecting to MySQL:

    Terminal window
    # Connect to your MySQL database
    mysql -h mysql-app.klutch.sh -P 8000 -u flexisip -p
    

    # Check registrations table
    USE sip;
    SELECT * FROM registrations;

    You should see active registrations from connected clients.

  3. Monitor Logs

    Access logs through your Klutch.sh dashboard or via the persistent volume to monitor:

    • Registration requests
    • Authentication attempts
    • Routing decisions
    • Error messages

Create SIP Accounts

    You can create SIP accounts directly in the MySQL database:

    -- Connect to your MySQL database
    USE sip;
    

    -- Create a new SIP account
    INSERT INTO accounts (username, domain, password, algorithm, enabled)
    VALUES (
        'john',
        'sip.example.com',
        SHA2('password123', 256),
        'SHA256',
        TRUE
    );
    

    -- Create another account
    INSERT INTO accounts (username, domain, password, algorithm, enabled)
    VALUES (
        'jane',
        'sip.example.com',
        SHA2('password456', 256),
        'SHA256',
        TRUE
    );
    

    -- View all accounts
    SELECT id, username, domain, enabled, created_at FROM accounts;

    Alternatively, you can build a web interface or API for user management.

Configure Custom Domain (Optional)

    To use a custom domain for your SIP server:

    1. Go to your Klutch.sh dashboard
    2. Navigate to your app’s settings
    3. Add your custom domain (e.g., sip.example.com)
    4. Update your DNS records:
      • Add A record or CNAME pointing to Klutch.sh
    5. Wait for DNS propagation (usually 5-60 minutes)
    6. Update SIP_DOMAIN environment variable to match

    Klutch.sh automatically provisions SSL certificates for custom domains.

Production Best Practices

Security Hardening

  1. Strong Authentication

    • Use SHA256 for password hashing (configured in flexisip.conf)
    • Enforce strong password policies
    • Change default admin credentials immediately
    • Consider certificate-based authentication for trusted devices

  2. TLS Encryption

    Enable TLS for SIP signaling:

    1. Obtain valid TLS certificates (Let’s Encrypt, commercial CA)
    2. Upload certificates to /etc/flexisip/tls/ volume
    3. Update flexisip.conf:
    [tls]
    tls-certificate-file=/etc/flexisip/tls/cert.pem
    tls-certificate-key-file=/etc/flexisip/tls/key.pem
    tls-ciphers=HIGH:!aNULL:!MD5
    1. Use sips: URI scheme for encrypted connections

  3. Rate Limiting

    Prevent abuse by configuring rate limits in flexisip.conf:

    [module::DoSProtection]
    enabled=true
    # Maximum requests per second per IP
    max-requests-per-second=10
    # Ban duration (seconds)
    ban-time=300

  4. Firewall Rules

    While Klutch.sh handles external routing, configure internal firewall rules:

    • Allow only necessary ports (5060, 5061, 8080)
    • Restrict admin interface access
    • Implement IP whitelisting for known clients

  5. Database Security

    • Use strong database passwords
    • Create dedicated database user with minimal privileges
    • Enable MySQL SSL connections
    • Regular database backups

Performance Optimization

  1. Redis Caching

    Enable Redis for registration caching to reduce database load:

    [module::Registrar]
    redis-server-domain=${REDIS_HOST}
    redis-server-port=${REDIS_PORT}
    redis-auth-password=${REDIS_PASSWORD}
    # Cache TTL (seconds)
    redis-record-serializer=protobuf

    Benefits:

    • Faster registration lookups
    • Reduced MySQL queries
    • Better scalability

  2. Connection Pooling

    Configure MySQL connection pooling:

    [module::Registrar]
    db-connection-string=db='sip' user='${MYSQL_USER}' password='${MYSQL_PASSWORD}' host='${MYSQL_HOST}' port='${MYSQL_PORT}' poolsize=10

  3. Thread Configuration

    Adjust thread count based on CPU cores:

    [global]
    # Set to number of CPU cores
    threads=4

    Monitor CPU usage and adjust accordingly.

  4. Log Rotation

    Implement log rotation to prevent disk space issues:

    Terminal window
    # Add to docker-entrypoint.sh
    cat > /etc/logrotate.d/flexisip << 'EOF'
    /var/log/flexisip/*.log {
        daily
        rotate 14
        compress
        delaycompress
        missingok
        notifempty
        create 0644 flexisip flexisip
    }
    EOF

Monitoring and Maintenance

  1. Health Checks

    Monitor Flexisip health through:

    1. HTTP Admin Interface: Check status at https://example-app.klutch.sh:8080/status
    2. Klutch.sh Dashboard: View container health and resource usage
    3. Log Analysis: Monitor error rates and performance metrics

  2. Key Metrics to Monitor

    • Active Registrations: Number of currently registered users
    • Call Setup Time: Time to establish SIP sessions
    • Message Throughput: Messages per second
    • Database Query Performance: MySQL response times
    • Cache Hit Rate: Redis cache effectiveness
    • Error Rates: Failed registrations, authentication failures
    • Resource Usage: CPU, memory, disk, network

  3. Alerting

    Set up alerts for:

    • High error rates
    • Database connection failures
    • Memory/CPU threshold breaches
    • Disk space warnings
    • Failed health checks

  4. Backup Strategy

    Regular backups of:

    • MySQL database (user accounts, registrations)
    • Flexisip configuration files
    • TLS certificates and keys
    • Push notification credentials

    Automate backups through Klutch.sh’s volume backup features or external backup solutions.

Scaling Strategies

  1. Vertical Scaling

    Increase resources for a single Flexisip instance:

    1. Navigate to your app in Klutch.sh dashboard
    2. Adjust compute resources (CPU/Memory)
    3. Recommended for up to 1,000 concurrent users:
      • Small: 1 CPU, 1GB RAM (100-500 users)
      • Medium: 2 CPU, 2GB RAM (500-1,000 users)
      • Large: 4 CPU, 4GB RAM (1,000-5,000 users)

  2. Horizontal Scaling

    For high availability and larger deployments:

    1. Deploy multiple Flexisip instances
    2. Use Flexisip’s built-in load balancing
    3. Configure cluster mode in flexisip.conf:
    [cluster]
    enabled=true
    # Cluster name
    cluster-name=flexisip-cluster
    # Other cluster nodes
    cluster-nodes=flexisip-node-2.klutch.sh:5060 flexisip-node-3.klutch.sh:5060
    1. Share Redis cache across all instances
    2. Use external load balancer if needed

  3. Database Scaling

    For large deployments:

    • Use MySQL read replicas for registration lookups
    • Implement connection pooling
    • Partition registration tables by domain
    • Consider dedicated presence database

Troubleshooting

Common Issues and Solutions

  1. Problem: Flexisip container fails to start

    Solution:

    • Check Klutch.sh deployment logs for errors
    • Verify all required environment variables are set
    • Ensure MySQL and Redis are accessible
    • Validate flexisip.conf syntax with flexisip --check-config
    • Check entrypoint script permissions

  2. Problem: Cannot register SIP clients

    Solution:

    Terminal window
    # Check Flexisip logs
    tail -f /var/log/flexisip/flexisip.log
    

    # Verify TCP port 8000 is accessible
    nc -zv example-app.klutch.sh 8000
    

    # Check database connectivity
    mysql -h $MYSQL_HOST -P $MYSQL_PORT -u $MYSQL_USER -p
    

    # Verify accounts table
    SELECT * FROM sip.accounts WHERE username='testuser';

    Common causes:

    • Incorrect SIP domain configuration
    • Database connection issues
    • Authentication failures (wrong password)
    • Network connectivity problems

  3. Problem: Authentication failures

    Solution:

    • Verify password hashing algorithm matches (SHA256)
    • Check database credentials are correct
    • Ensure SIP domain in client matches configuration
    • Review authentication logs in Flexisip
    -- Verify password hash
    SELECT username, domain, password, algorithm FROM sip.accounts WHERE username='testuser';
    

    -- Reset password if needed
    UPDATE sip.accounts SET password=SHA2('newpassword', 256) WHERE username='testuser';

  4. Problem: Database connection errors

    Solution:

    • Verify MySQL is running and accessible
    • Check hostname resolves: ping mysql-app.klutch.sh
    • Test database connection:
    Terminal window
    mysql -h $MYSQL_HOST -P $MYSQL_PORT -u $MYSQL_USER -p
    

    # If connection fails, check:
    # - MySQL is deployed and running
    # - Port 8000 is configured for TCP traffic
    # - Credentials are correct
    # - Database 'sip' exists

  5. Problem: Redis connection issues

    Solution:

    Terminal window
    # Test Redis connectivity
    redis-cli -h $REDIS_HOST -p $REDIS_PORT -a $REDIS_PASSWORD ping
    

    # Expected response: PONG

    If Redis is not required, you can disable it:

    [module::Registrar]
    # Comment out Redis configuration
    # redis-server-domain=${REDIS_HOST}

  6. Problem: High CPU or memory usage

    Solution:

    • Monitor active registrations and call volume
    • Check for DOS attacks in logs
    • Enable rate limiting (DoSProtection module)
    • Increase thread count if CPU-bound
    • Scale vertically (more resources) or horizontally (more instances)
    • Optimize database queries
    • Enable Redis caching

  7. Problem: Push notifications not working

    Solution:

    • Verify APNs/FCM credentials are correctly configured
    • Check certificate paths are correct
    • Ensure certificates have not expired
    • Review push notification module logs
    • Test with simple notification first
    [module::PushNotification]
    enabled=true
    # Verify paths
    apns-certificate-path=/etc/flexisip/tls/apns-cert.pem
    apns-certificate-key-path=/etc/flexisip/tls/apns-key.pem

Debug Mode

    To enable debug logging for troubleshooting:

    [global]
    log-level=debug

    Or set environment variable:

    Terminal window
    LOG_LEVEL=debug

    Warning: Debug mode generates large log files. Use only for troubleshooting and disable in production.

Health Check Failures

    If health checks fail:

    1. Verify Flexisip is running:
    Terminal window
    ps aux | grep flexisip
    1. Check configuration validity:
    Terminal window
    flexisip --check-config
    1. Review recent logs for errors:
    Terminal window
    tail -n 100 /var/log/flexisip/flexisip.log
    1. Test SIP registration manually with sipclients

Advanced Configuration

Push Notification Setup

  1. Apple Push Notification Service (APNs)

    1. Obtain APNs certificate from Apple Developer Portal
    2. Convert to PEM format:
    Terminal window
    openssl pkcs12 -in cert.p12 -out apns-cert.pem -nodes -clcerts
    openssl pkcs12 -in cert.p12 -out apns-key.pem -nodes -nocerts
    1. Upload to persistent volume at /etc/flexisip/tls/
    2. Configure in flexisip.conf:
    [module::PushNotification]
    apns-certificate-path=/etc/flexisip/tls/apns-cert.pem
    apns-certificate-key-path=/etc/flexisip/tls/apns-key.pem

  2. Firebase Cloud Messaging (FCM)

    1. Download service account JSON from Firebase Console
    2. Upload to /etc/flexisip/fcm-service-account.json
    3. Configure in flexisip.conf:
    [module::PushNotification]
    firebase-service-account-file=/etc/flexisip/fcm-service-account.json

Media Relay (TURN/STUN)

    For NAT traversal and media routing:

    [module::MediaRelay]
    enabled=true
    # STUN server (free public servers available)
    stun-server=stun.l.google.com:19302
    # TURN server (deploy your own or use service)
    turn-server=turn.example.com:3478
    turn-username=turnuser
    turn-password=turnpassword
    # TURN transport
    turn-transport=udp

    Public STUN servers:

    • stun.l.google.com:19302
    • stun1.l.google.com:19302
    • stun2.l.google.com:19302

    For production, deploy your own TURN server (coturn is popular).

Presence Server

    Enable presence for showing user availability:

    [module::Presence]
    enabled=true
    presence-server=sip:presence.example.com
    # Use Redis for presence data
    db-implementation=redis
    redis-server-domain=${REDIS_HOST}
    redis-server-port=${REDIS_PORT}
    # Presence expiration time (seconds)
    presence-expires=3600

Conference Server

    For multi-party conferencing:

    [module::Conference]
    enabled=true
    # Conference URI format
    conference-uri=sip:conf@example.com
    # Maximum participants per conference
    max-participants=10
    # Audio mixing
    enable-audio-mixing=true

Load Balancing

    Configure Flexisip as a load balancer:

    [module::Forward]
    enabled=true
    # Backend SIP servers
    routes=sip:backend1.example.com:5060;transport=tcp sip:backend2.example.com:5060;transport=tcp
    # Load balancing algorithm: round-robin, hash, least-connections
    route-selection=round-robin

Integration Examples

SIP Client Configuration

Linphone (Desktop/Mobile):

Username: john
Password: password123
Domain: example-app.klutch.sh
Transport: TCP
Port: 8000

Zoiper:

Account Type: SIP
Username: jane
Domain: example-app.klutch.sh:8000
Password: password456
Outbound Proxy: example-app.klutch.sh:8000
Transport: TCP

Asterisk Integration

Connect Asterisk PBX to Flexisip:

; In Asterisk pjsip.conf
[flexisip-trunk]
type=endpoint
context=from-flexisip
disallow=all
allow=ulaw
allow=alaw
transport=transport-tcp
aors=flexisip-aor


[flexisip-aor]
type=aor
contact=sip:example-app.klutch.sh:8000;transport=tcp


[flexisip-identify]
type=identify
endpoint=flexisip-trunk
match=example-app.klutch.sh

WebRTC Integration

For web-based calling:

// JavaScript SIP client (JsSIP example)
const socket = new JsSIP.WebSocketInterface('wss://example-app.klutch.sh:5062');
const configuration = {
  sockets: [socket],
  uri: 'sip:john@sip.example.com',
  password: 'password123',
  display_name: 'John Doe'
};


const ua = new JsSIP.UA(configuration);
ua.start();


// Make a call
ua.call('sip:jane@sip.example.com', {
  mediaConstraints: { audio: true, video: true }
});

Additional Resources

  1. Official Documentation: Flexisip Wiki

  2. GitHub Repository: Flexisip on GitHub

  3. SIP Protocol: RFC 3261

  4. Linphone SDK: Linphone Project

  5. MySQL Documentation: MySQL Docs

  6. Redis Documentation: Redis Docs

  7. Docker Documentation: Docker Docs

  8. TURN Server (coturn): coturn on GitHub

  9. Klutch.sh Support: For platform-specific questions, visit the Klutch.sh documentation

Production Checklist

Before going live with your Flexisip deployment, verify:

    • Dockerfile builds successfully
    • MySQL database deployed and accessible
    • Redis cache deployed (optional but recommended)
    • Environment variables configured correctly
    • Persistent volumes attached for logs and data
    • TCP traffic configured on port 8000 → 5060
    • SIP domain configured correctly
    • TLS certificates installed and valid
    • Strong admin password set
    • Database credentials are secure
    • SIP accounts created and tested
    • Client registration successful
    • Call routing working correctly
    • Push notifications configured (if using mobile)
    • Rate limiting enabled (DoS protection)
    • Log rotation configured
    • Monitoring and alerting setup
    • Backup strategy implemented
    • Health checks passing consistently
    • Performance tested under expected load
    • Security audit completed
    • Documentation updated for team
    • Disaster recovery plan in place

Conclusion

Deploying Flexisip on Klutch.sh gives you a production-ready SIP server with enterprise-grade features for VoIP and real-time communications. The combination of Flexisip’s robust architecture and Klutch.sh’s scalable infrastructure makes it an ideal solution for building reliable telephony systems.

With this guide, you now have:

  • A production-ready Dockerfile for Flexisip
  • Complete configuration for MySQL and Redis integration
  • TCP traffic setup for SIP signaling
  • Persistent storage for logs and data
  • Security best practices for VoIP systems
  • Performance optimization strategies
  • Comprehensive troubleshooting solutions
  • Advanced features like push notifications and load balancing

Start building your VoIP infrastructure with the reliability of Flexisip and the simplicity of Klutch.sh. Your SIP server is ready to handle millions of calls and messages with confidence.

For questions or issues specific to Klutch.sh deployments, refer to the platform documentation or contact support. Happy calling!