Skip to content
Klutch.sh Docs

Deploying FusionPBX

Introduction

FusionPBX is a powerful, open-source web-based graphical user interface that provides advanced management capabilities for FreeSWITCH, one of the world’s most capable and flexible telephony platforms. Built with PHP and featuring an intuitive interface, FusionPBX transforms the robust FreeSWITCH core into an enterprise-grade PBX solution that’s accessible to both administrators and end users without requiring deep knowledge of FreeSWITCH’s configuration syntax.

FusionPBX delivers comprehensive telephony features including multi-tenant support, call routing, IVR (Interactive Voice Response) menus, call center functionality, voicemail-to-email, fax server capabilities, and extensive reporting tools. Whether you’re deploying a small office phone system or building a multi-tenant hosted PBX platform serving thousands of users, FusionPBX provides the scalability and features you need.

Deploying FusionPBX on Klutch.sh gives you automatic Docker detection, persistent storage for call recordings and voicemails, seamless database integration, TCP traffic support for SIP signaling, and a streamlined deployment workflow. This guide walks you through deploying FusionPBX with production-ready configuration, including PostgreSQL database setup, persistent volume configuration, and best practices for running a reliable VoIP infrastructure.

Why Deploy FusionPBX on Klutch.sh?

  • Simplified Infrastructure: Deploy a complete PBX system without managing complex server infrastructure
  • Automatic HTTPS: Built-in SSL certificates for secure web interface access
  • Persistent Storage: Reliable volume storage for call recordings, voicemails, and configuration
  • TCP Traffic Support: Native support for SIP signaling and RTP media routing
  • Custom Domains: Use your own domain for professional branding
  • Database Integration: Connect to PostgreSQL for robust data persistence
  • Environment Variables: Secure configuration management through the dashboard
  • Easy Scaling: Adjust resources as your call volume grows
  • Container Benefits: Isolated, reproducible environment with version control
  • GitHub Integration: Automated deployments from your repository
  • Multi-Tenant Ready: Support multiple organizations from a single deployment

Prerequisites

Before you begin, ensure you have:

Understanding FusionPBX Architecture

FusionPBX is built on a modern, multi-layered architecture optimized for telephony operations:

Core Components:

  • FreeSWITCH Core: High-performance telephony engine handling SIP, RTP, and media processing
  • Web Interface: PHP-based administrative and user portals for system management
  • PostgreSQL Database: Stores extensions, call detail records, voicemails, and configuration
  • Nginx/Apache: Web server for hosting the management interface
  • Event Socket: Real-time communication between FusionPBX and FreeSWITCH
  • Memcache/Redis: Optional caching layer for improved performance

Default Ports:

  • HTTP/HTTPS: 80/443 (Web interface)
  • SIP: 5060 (TCP/UDP), 5061 (TLS)
  • RTP Media: 16384-32768 (UDP)
  • Event Socket: 8021 (Internal communication)

Key Features:

  • Multi-tenant architecture with domain isolation
  • Extension management with dial plans
  • Call routing and time conditions
  • IVR menus with advanced options
  • Call center queues and agent management
  • Ring groups and hunt groups
  • Voicemail with email delivery
  • Call recording and monitoring
  • Fax server (T.38 support)
  • Conference bridges
  • Hot desking and follow-me
  • Click-to-call integration
  • Comprehensive CDR reporting
  • WebRTC support
  • REST API for integrations

When deploying on Klutch.sh, we’ll containerize FusionPBX with FreeSWITCH and connect it to a separately deployed PostgreSQL instance for optimal performance and maintainability.

Preparing Your Repository

Step 1: Create Project Directory

Create a new directory for your FusionPBX deployment:

Terminal window
mkdir fusionpbx-deploy
cd fusionpbx-deploy
git init

Step 2: Understanding FusionPBX Requirements

FusionPBX requires the following components to run successfully:

  • FreeSWITCH: The core telephony engine (version 1.10+ recommended)
  • Web Server: Nginx or Apache to serve the PHP application
  • PHP: Version 7.4 or higher with required extensions
  • PostgreSQL: Version 12+ for storing configuration and call data
  • Storage: Persistent storage for recordings, voicemails, and fax documents
  • Network: TCP access for SIP signaling and web interface

Deploying with a Dockerfile

Klutch.sh automatically detects a Dockerfile in your repository’s root directory and uses it to build your application. This approach provides reproducible builds, full control over dependencies, and consistency across environments.

Sample Dockerfile for FusionPBX

Create a Dockerfile in your repository root with the following content:

FROM fusionpbx/fusionpbx:latest


# Set timezone (adjust as needed)
ENV TZ=America/New_York


# Configure system user
ENV SYSTEM_USERNAME=admin
ENV SYSTEM_PASSWORD=changeme


# The web interface runs on port 80/443 internally
# FreeSWITCH SIP runs on port 5060
EXPOSE 80 443 5060 5061 8021


# Health check for the web interface
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost/ || exit 1


# The base image already has an entrypoint configured
# This starts both FreeSWITCH and the web server

This Dockerfile uses the official fusionpbx/fusionpbx image, which includes:

  • FreeSWITCH with all necessary modules
  • Nginx web server pre-configured
  • PHP with required extensions
  • Automatic database schema initialization
  • Startup scripts for both services
  • Logging and monitoring capabilities

Alternative: Custom Build from Source

If you need more control or want to build from source, create this alternative Dockerfile:

FROM debian:bullseye-slim


# Install system dependencies
RUN apt-get update && apt-get install -y \
    wget \
    gnupg2 \
    apt-transport-https \
    ca-certificates \
    lsb-release \
    curl \
    git \
    nginx \
    php-fpm \
    php-cli \
    php-pgsql \
    php-odbc \
    php-curl \
    php-imap \
    php-xml \
    php-gd \
    php-mbstring \
    supervisor \
    && rm -rf /var/lib/apt/lists/*


# Install FreeSWITCH
RUN wget -O - https://files.freeswitch.org/repo/deb/debian-release/fsstretch-archive-keyring.asc | apt-key add - && \
    echo "deb https://files.freeswitch.org/repo/deb/debian-release/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/freeswitch.list && \
    apt-get update && apt-get install -y \
    freeswitch-meta-all \
    && rm -rf /var/lib/apt/lists/*


# Clone FusionPBX
WORKDIR /var/www
RUN git clone https://github.com/fusionpbx/fusionpbx.git fusionpbx && \
    chown -R www-data:www-data /var/www/fusionpbx


# Configure Nginx
COPY nginx.conf /etc/nginx/sites-available/fusionpbx
RUN ln -sf /etc/nginx/sites-available/fusionpbx /etc/nginx/sites-enabled/fusionpbx && \
    rm -f /etc/nginx/sites-enabled/default


# Configure Supervisor to manage services
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf


# Expose ports
EXPOSE 80 443 5060 5061 8021


# Start services with Supervisor
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/supervisord.conf"]

For the custom build, you’ll also need supporting configuration files.

nginx.conf:

server {
    listen 80;
    server_name _;


    root /var/www/fusionpbx;
    index index.php;


    access_log /var/log/nginx/fusionpbx-access.log;
    error_log /var/log/nginx/fusionpbx-error.log;


    client_max_body_size 80M;
    client_body_timeout 1800;


    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }


    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_read_timeout 1800;
    }


    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires max;
        log_not_found off;
    }
}

supervisord.conf:

[supervisord]
nodaemon=true
logfile=/var/log/supervisor/supervisord.log
pidfile=/var/run/supervisord.pid


[program:nginx]
command=/usr/sbin/nginx -g "daemon off;"
autostart=true
autorestart=true
stdout_logfile=/var/log/nginx/stdout.log
stderr_logfile=/var/log/nginx/stderr.log


[program:php-fpm]
command=/usr/sbin/php-fpm7.4 -F
autostart=true
autorestart=true
stdout_logfile=/var/log/php-fpm/stdout.log
stderr_logfile=/var/log/php-fpm/stderr.log


[program:freeswitch]
command=/usr/bin/freeswitch -nonat -nc
autostart=true
autorestart=true
stdout_logfile=/var/log/freeswitch/stdout.log
stderr_logfile=/var/log/freeswitch/stderr.log

Note: For most deployments, the official fusionpbx/fusionpbx image is recommended as it’s maintained by the FusionPBX team and includes all necessary optimizations.

Step-by-Step Deployment on Klutch.sh

1. Push Your Repository to GitHub

    1. Commit your Dockerfile and any configuration files to your repository:

      Terminal window
      git add Dockerfile
      git commit -m "Add FusionPBX Dockerfile for Klutch.sh deployment"
      git push origin main

2. Create a New App on Klutch.sh

    1. Log in to the Klutch.sh dashboard

    2. Create a new project or select an existing one

    3. Create a new app and configure it:

      • Repository: Select your FusionPBX GitHub repository
      • Branch: Choose the branch to deploy (e.g., main or production)
      • Traffic Type: Select TCP (FusionPBX requires SIP signaling)
      • Internal Port: Set to 5060 (FreeSWITCH SIP port)

Important: For TCP traffic applications like VoIP systems, Klutch.sh makes them accessible on port 8000 externally, while traffic is routed to your configured internal port inside the container. This means SIP clients will connect to example-app.klutch.sh:8000, and Klutch.sh routes traffic to port 5060 inside your container.

3. Configure Persistent Volumes

FusionPBX requires persistent storage for recordings, voicemails, faxes, and other data. Set up volumes in your app configuration:

    1. In your app settings, navigate to the Volumes section

    2. Add the following volumes:

      Volume 1 - Recordings and Voicemails:

      • Mount Path: /var/lib/freeswitch/recordings
      • Size: Start with 20GB, scale based on call recording needs

      Volume 2 - Database Backups and Storage:

      • Mount Path: /var/lib/freeswitch/storage
      • Size: 10GB

      Volume 3 - Application Logs:

      • Mount Path: /var/log/freeswitch
      • Size: 5GB

      Volume 4 - Configuration Files:

      • Mount Path: /etc/freeswitch
      • Size: 2GB

Storage Recommendations by Scale:

  • Small Office (10-50 extensions, limited recording): 20GB recordings + 5GB logs
  • Medium Business (50-200 extensions, moderate recording): 100GB recordings + 10GB logs
  • Enterprise (200+ extensions, extensive recording): 500GB+ recordings + 20GB logs

When configuring volumes on Klutch.sh, you only specify the mount path and size. The platform handles volume naming and management automatically.

4. Set Environment Variables

Configure the required environment variables for FusionPBX to connect to your database and configure the system:

    1. In your app settings, navigate to the Environment Variables section

    2. Add the following required variables (mark sensitive values as secrets):

      Database Configuration:

      Terminal window
      # PostgreSQL connection details
      DATABASE_HOST=postgres-app.klutch.sh
      DATABASE_PORT=8000
      DATABASE_NAME=fusionpbx
      DATABASE_USERNAME=fusionpbx
      DATABASE_PASSWORD=your-secure-database-password
      DATABASE_TYPE=pgsql

      Application Configuration:

      Terminal window
      # System admin credentials (change these immediately)
      SYSTEM_USERNAME=admin
      SYSTEM_PASSWORD=changeme-secure-password
      

      # Domain configuration
      DOMAIN_NAME=example-app.klutch.sh
      DEFAULT_LANGUAGE=en-us
      DEFAULT_TIMEZONE=America/New_York

      FreeSWITCH Configuration:

      Terminal window
      # Event Socket password (used for internal communication)
      EVENT_SOCKET_PASSWORD=ClueCon
      

      # SIP profile settings
      SIP_PORT=5060
      SIP_TLS_PORT=5061
      RTP_START_PORT=16384
      RTP_END_PORT=32768
      

      # External IP for SIP/RTP (use your Klutch.sh app domain)
      EXTERNAL_SIP_IP=example-app.klutch.sh
      EXTERNAL_RTP_IP=example-app.klutch.sh

      Optional - SMTP Configuration for Voicemail:

      Terminal window
      SMTP_HOST=smtp.gmail.com
      SMTP_PORT=587
      SMTP_SECURE=tls
      SMTP_AUTH=true
      SMTP_USERNAME=your-email@gmail.com
      SMTP_PASSWORD=your-app-specific-password
      SMTP_FROM=voicemail@yourdomain.com
      SMTP_FROM_NAME=FusionPBX Voicemail

Security Note: Always mark sensitive values like DATABASE_PASSWORD, SYSTEM_PASSWORD, EVENT_SOCKET_PASSWORD, and SMTP_PASSWORD as secrets in Klutch.sh to prevent them from appearing in logs or being exposed.

5. Configure Additional Settings

    1. Region: Choose a region closest to your users for optimal call quality and low latency

    2. Compute: Select an instance size based on your expected call volume:

      • Small (2 CPU, 2GB RAM): Development or very small office (up to 10 concurrent calls)
      • Medium (4 CPU, 4GB RAM): Small to medium business (10-50 concurrent calls)
      • Large (8 CPU, 8GB RAM): Medium to large business (50-100 concurrent calls)
      • XLarge (16 CPU, 16GB RAM): Enterprise deployment (100+ concurrent calls)

    3. Instances: Start with 1 instance (multi-instance VoIP requires advanced load balancing configuration)

6. Deploy Your Application

    1. Review your configuration settings

    2. Click “Create” to start the deployment

    3. Klutch.sh will:

      • Detect your Dockerfile automatically
      • Build your Docker image
      • Deploy the container with your configured volumes and environment variables
      • Route TCP traffic to port 5060 inside your container (accessible externally on port 8000)
      • Generate a public URL like example-app.klutch.sh

    4. Monitor the build and deployment progress in the dashboard

    5. Wait for the deployment to complete (initial deployment may take 5-10 minutes as FreeSWITCH initializes)

7. Initial FusionPBX Setup

    1. Once deployment is complete, access the web interface:

      • Open your browser and navigate to https://example-app.klutch.sh (if you have HTTP traffic enabled for the web UI)
      • Alternatively, if only TCP is configured, you’ll need to set up a separate HTTP app pointing to port 80

    2. Complete the FusionPBX installation wizard:

      • Accept the default database settings (already configured via environment variables)
      • Create your admin account (or use the credentials from SYSTEM_USERNAME and SYSTEM_PASSWORD)
      • Set up your first domain (typically your app URL)

    3. Configure your first extensions:

      • Navigate to Accounts > Extensions
      • Click Add to create extensions for your users
      • Note the extension number and password for SIP client configuration

    4. Test your setup:

      • Register a SIP client to example-app.klutch.sh:8000
      • Make a test call between extensions
      • Verify audio quality and two-way communication

Database Setup and Configuration

FusionPBX requires PostgreSQL for storing configuration, call detail records, and voicemail metadata.

Deploy a PostgreSQL database as a separate app on Klutch.sh:

    1. Create a new app with the PostgreSQL Docker image
    2. Configure it with TCP traffic type (not HTTP)
    3. Set internal port to 5432
    4. Set up persistent storage at /var/lib/postgresql/data (minimum 10GB)
    5. Configure environment variables for database credentials
    6. Note the app URL (e.g., postgres-app.klutch.sh)

See our PostgreSQL deployment guide for detailed instructions.

Option 2: Use a Managed Database Service

For production deployments with high availability requirements, consider managed database services:

These services provide automatic backups, point-in-time recovery, high availability, and simplified maintenance.

Database Initialization

FusionPBX will automatically create the necessary database schema on first startup. The initial setup includes:

  • User accounts and permissions tables
  • Extension configuration tables
  • Call detail record (CDR) tables
  • Voicemail metadata tables
  • Fax log tables
  • System settings tables

Initial Database Size: Start with 10GB and monitor growth. CDR tables can grow significantly with high call volumes.

SIP Client Configuration

To connect SIP clients (softphones or hardware phones) to your FusionPBX deployment:

Softphone Configuration Example

Zoiper, Linphone, or similar softphone:

Domain: example-app.klutch.sh
Port: 8000
Transport: TCP
Username: 1001 (your extension number)
Password: your-extension-password
Proxy: example-app.klutch.sh:8000

Hardware Phone Configuration

For IP phones like Yealink, Polycom, or Cisco:

SIP Server: example-app.klutch.sh
SIP Port: 8000
Outbound Proxy: example-app.klutch.sh:8000
Transport: TCP
User ID: 1001
Auth ID: 1001
Password: your-extension-password

WebRTC Configuration

FusionPBX supports WebRTC for browser-based calling:

    1. Enable WebRTC in FusionPBX:

      • Navigate to Advanced > Default Settings
      • Search for “webrtc”
      • Enable WebRTC support

    2. Configure secure WebSocket transport (requires HTTPS)

    3. Use the built-in WebRTC client in FusionPBX or integrate with your own web application

SIP Trunk Configuration

Connect FusionPBX to a SIP trunk provider for external calling (PSTN):

Configuring a SIP Trunk in FusionPBX

    1. Navigate to Accounts > Gateways in FusionPBX

    2. Click Add to create a new gateway

    3. Configure the gateway settings:

      Gateway: trunk-provider
      Username: your-account-username
      Password: your-account-password
      From Domain: sip.provider.com
      Proxy: sip.provider.com
      Register: true

    4. Save the gateway configuration

    5. Configure outbound routes:

      • Navigate to Dialplan > Outbound Routes
      • Create routes for different dial patterns (e.g., 10-digit US numbers)
      • Associate routes with your SIP trunk gateway

    6. Test outbound calling by dialing an external number

Example Outbound Route Configuration

For US numbers (10 digits):

Dialplan: outbound-routes
Order: 100
Gateway: trunk-provider
Prefix: 1
Destination Number: ^(\d{10})$
Description: US 10-digit numbers

Advanced Features

Call Recording

FusionPBX supports automatic or on-demand call recording:

    1. Enable Call Recording:

      • Navigate to Accounts > Extensions
      • Edit an extension
      • Set Record to “all”, “inbound”, “outbound”, or “local”

    2. Access Recordings:

      • Recordings are stored in /var/lib/freeswitch/recordings
      • Access via web interface: Accounts > Call Recordings

    3. Storage Management: Monitor recording volume usage and increase persistent volume size as needed

IVR (Interactive Voice Response) Menus

Create automated phone menus:

    1. Navigate to Dialplan > IVR Menus

    2. Click Add to create a new IVR

    3. Configure menu options:

      • Upload or record greeting audio
      • Define digit options (press 1 for sales, press 2 for support, etc.)
      • Set timeout and invalid entry behavior

    4. Link IVR to a phone number in Dialplan > Inbound Routes

Call Center / Queue Configuration

Set up call queues for customer service:

    1. Navigate to Apps > Call Center

    2. Create a new queue:

      • Set queue name and extension
      • Configure agent timeout and wrap-up time
      • Set music on hold

    3. Add agents to the queue:

      • Agents can log in/out via phone (*22 to log in,*23 to log out)
      • Monitor agent status in real-time

    4. Configure queue routing in Dialplan > Inbound Routes

Voicemail Configuration

FusionPBX includes comprehensive voicemail functionality:

    1. Voicemail-to-Email:

      • Configure SMTP settings in environment variables
      • Enable voicemail-to-email in extension settings
      • Voicemail recordings are attached to email notifications

    2. Voicemail Portal:

      • Users dial *98 to access their voicemail
      • Web-based voicemail access at Accounts > Voicemail

    3. Storage: Voicemail files are stored in persistent volumes and metadata in PostgreSQL

Fax Server

FusionPBX supports T.38 fax with these features:

    1. Navigate to Apps > Fax Server

    2. Configure fax extension and email delivery

    3. Send faxes via:

      • Email-to-fax gateway
      • Web interface upload
      • Virtual fax printer

    4. Receive faxes and have them delivered to email as PDF attachments

Network Configuration and NAT Traversal

VoIP applications require proper network configuration for optimal performance:

Understanding RTP Ports

RTP (Real-time Transport Protocol) carries the actual voice audio. FusionPBX uses ports 16384-32768 by default.

Important: Klutch.sh TCP traffic mode is designed for signaling (SIP). For production VoIP deployments with significant call volumes, you may need additional configuration:

  • Use TCP for SIP signaling (configured via port 8000)
  • For RTP media, consider:
    • Using TURN/STUN servers for NAT traversal
    • Deploying on infrastructure with full UDP support
    • Using WebRTC for browser-based clients

STUN/TURN Configuration

To improve connectivity for users behind NAT:

    1. Configure STUN server in FreeSWITCH:

      <!-- In /etc/freeswitch/autoload_configs/sofia.conf.xml -->
      <param name="stun-server" value="stun.l.google.com"/>
      <param name="stun-port" value="19302"/>

    2. For WebRTC clients, configure TURN servers to relay media traffic

    3. Test connectivity with various network configurations

Monitoring and Maintenance

Application Monitoring

    1. FreeSWITCH Status:

      • Access FreeSWITCH console: fs_cli
      • Check active calls: show channels
      • Monitor registration: sofia status

    2. Web Interface Monitoring:

      • Status > Dashboard: Real-time system overview
      • Advanced > Command: Execute FreeSWITCH commands

    3. Log Files:

      • Application logs: /var/log/freeswitch/freeswitch.log
      • SIP traces: Enable SIP debug for troubleshooting
      • Web server logs: /var/log/nginx/ or /var/log/apache2/

Call Detail Records (CDR)

Track and analyze call history:

    1. Access CDR reports: Apps > Call Detail Records

    2. Generate reports:

      • Calls by extension
      • Calls by time period
      • Call duration statistics
      • Failed call analysis

    3. Export CDR data for billing or external analysis

Backup Strategy

    1. Database Backups:

      • Use PostgreSQL’s pg_dump for regular backups
      • Configure automated daily backups
      • Store backups in object storage (S3, GCS, etc.)
      Terminal window
      # Example backup command
      pg_dump -h postgres-app.klutch.sh -p 8000 -U fusionpbx fusionpbx > backup-$(date +%Y%m%d).sql

    2. Persistent Volume Backups:

      • Regularly backup recordings and voicemails
      • Copy to off-site storage
      • Test restore procedures

    3. Configuration Backups:

      • Export FusionPBX configuration via web interface
      • Store FreeSWITCH configuration files in version control
      • Document custom dialplans and modifications

    4. Backup Schedule:

      • Database: Daily incremental, weekly full backups
      • Recordings: Daily backups with 30-day retention
      • Configuration: On every change

Performance Optimization

    1. Database Optimization:

      • Create indexes on frequently queried CDR columns
      • Implement CDR archiving strategy (move old records to archive tables)
      • Run VACUUM and ANALYZE regularly on PostgreSQL

    2. FreeSWITCH Optimization:

      • Adjust codec preferences for bandwidth optimization
      • Configure appropriate RTP buffer sizes
      • Optimize dialplan for efficiency

    3. Resource Monitoring:

      • Monitor CPU usage during peak call times
      • Track memory consumption
      • Monitor disk I/O for recordings
      • Scale compute resources as needed

Security Best Practices

Authentication and Access Control

    1. Strong Passwords:

      • Use complex passwords for all extensions (minimum 12 characters)
      • Change default admin password immediately
      • Rotate passwords regularly

    2. SIP Authentication:

      • Enable SIP authentication on all profiles
      • Use strong extension passwords
      • Implement IP-based access control where possible

    3. Web Interface Security:

      • Enable HTTPS only (disable HTTP)
      • Configure strong session timeout
      • Limit admin access by IP address
      • Enable two-factor authentication if available

Network Security

    1. Firewall Configuration:

      • Limit SIP access to known IP ranges
      • Use fail2ban to block brute force attempts
      • Monitor failed registration attempts

    2. SIP Security:

      • Disable guest calling
      • Require authentication for all calls
      • Implement rate limiting on registrations

    3. Encryption:

      • Use SIP over TLS (SIPS) for signaling encryption
      • Enable SRTP for media encryption
      • Configure proper TLS certificates

Fraud Prevention

VoIP fraud can result in significant costs. Implement these protections:

    1. Call Restrictions:

      • Limit international calling by default
      • Implement least-cost routing
      • Set up toll fraud detection

    2. Monitoring:

      • Monitor unusual call patterns
      • Set up alerts for high-cost destinations
      • Review CDR regularly for suspicious activity

    3. Cost Controls:

      • Implement per-extension spending limits
      • Require authorization for premium rate numbers
      • Set up real-time billing alerts with your SIP provider

Troubleshooting Common Issues

Registration Issues

Problem: Extensions won’t register

Solutions:

    1. Verify SIP credentials (username and password)
    2. Check network connectivity to example-app.klutch.sh:8000
    3. Confirm transport protocol (TCP/UDP) matches server configuration
    4. Review FreeSWITCH logs: /var/log/freeswitch/freeswitch.log
    5. Test with sofia status profile internal in fs_cli

One-Way Audio

Problem: Can hear the other party, but they can’t hear you (or vice versa)

Solutions:

    1. NAT Configuration:

      • Verify EXTERNAL_RTP_IP is set correctly
      • Configure STUN server
      • Check firewall RTP port ranges (16384-32768)

    2. Codec Issues:

      • Ensure both parties support a common codec
      • Check codec priorities in extension configuration
      • Test with different codecs (G.711 ulaw/alaw are most compatible)

    3. Network Issues:

      • Check for packet loss or high latency
      • Verify sufficient bandwidth for RTP streams
      • Test network connectivity between endpoints

Call Quality Issues

Problem: Echo, choppy audio, or dropped calls

Solutions:

    1. Bandwidth:

      • Ensure adequate bandwidth (100 Kbps per concurrent call minimum)
      • Implement QoS on network equipment
      • Check for network congestion

    2. Codec Selection:

      • Use appropriate codecs for available bandwidth
      • G.711 (ulaw/alaw): Best quality, high bandwidth (87 Kbps)
      • G.729: Good quality, low bandwidth (31 Kbps)
      • Opus: Excellent quality and bandwidth adaptation

    3. Jitter Buffer:

      • Adjust jitter buffer settings in FreeSWITCH
      • Configure appropriate values based on network conditions

    4. Echo Issues:

      • Enable echo cancellation in FreeSWITCH
      • Check for acoustic echo (hardware microphone issues)
      • Adjust echo cancellation parameters

Database Connection Issues

Problem: FusionPBX can’t connect to PostgreSQL

Solutions:

    1. Verify DATABASE_HOST and DATABASE_PORT are correct

    2. Confirm PostgreSQL is running and accessible

    3. Test database connection from FusionPBX container:

      Terminal window
      psql -h postgres-app.klutch.sh -p 8000 -U fusionpbx -d fusionpbx

    4. Check firewall rules allow traffic between apps

    5. Verify database credentials are correct

Web Interface Not Loading

Problem: Can’t access FusionPBX web interface

Solutions:

    1. Verify the application is running:

      • Check deployment status in Klutch.sh dashboard
      • Review container logs for errors

    2. Check web server status:

      • Confirm Nginx/Apache is running
      • Review web server error logs

    3. Clear browser cache and cookies

    4. Try accessing from different network/device

Voicemail Not Working

Problem: Voicemail not recording or emailing

Solutions:

    1. Recording Issues:

      • Verify persistent volume is mounted correctly
      • Check disk space availability
      • Review voicemail configuration in extension settings

    2. Email Delivery:

      • Confirm SMTP settings are correct
      • Test SMTP connectivity
      • Check spam folders
      • Review mail server logs

    3. Permission Issues:

      • Ensure web server has write permissions to voicemail directory
      • Check file ownership: chown -R www-data:www-data /var/lib/freeswitch

Production Deployment Checklist

Before going live with FusionPBX:

  • PostgreSQL database properly configured with automated backups
  • Persistent volumes configured and tested (recordings, voicemails, logs, config)
  • All environment variables set (especially secrets)
  • Strong passwords set for admin and all extensions
  • SIP trunk configured and tested for outbound calling
  • Inbound routes configured for incoming calls
  • Extension dial plans created and tested
  • Voicemail configured and email delivery tested
  • Call recording tested and storage monitored
  • Network configuration optimized (NAT, STUN/TURN if needed)
  • SSL/TLS certificate active (automatic with Klutch.sh)
  • Firewall rules and security measures implemented
  • Fail2ban or rate limiting configured
  • Fraud prevention measures in place
  • Monitoring and alerting configured
  • Backup schedule established and tested
  • Load testing performed for expected call volume
  • Documentation updated with your specific configuration
  • Emergency contact and failover procedures documented
  • Team trained on system administration
  • SIP clients configured and distributed to users
  • Call quality tested from multiple locations/networks

Advanced Configuration

Custom Domain Setup

To use a custom domain with your FusionPBX deployment:

    1. Configure your custom domain in the Klutch.sh dashboard (see Custom Domains Guide)

    2. Update your DNS records:

      • A record pointing to your Klutch.sh app
      • SRV records for SIP (optional but recommended)
      _sip._tcp.yourdomain.com. 3600 IN SRV 10 5 5060 pbx.yourdomain.com.
      _sips._tcp.yourdomain.com. 3600 IN SRV 10 5 5061 pbx.yourdomain.com.

    3. Update environment variables:

      Terminal window
      DOMAIN_NAME=pbx.yourdomain.com
      EXTERNAL_SIP_IP=pbx.yourdomain.com
      EXTERNAL_RTP_IP=pbx.yourdomain.com

    4. Klutch.sh automatically manages TLS certificates for your domain

Multi-Tenant Configuration

FusionPBX supports multiple domains (tenants) in a single deployment:

    1. Create Additional Domains:

      • Navigate to Advanced > Domains
      • Click Add to create a new domain
      • Configure domain-specific settings

    2. Isolate Resources:

      • Each domain has its own extensions, dialplans, and settings
      • Separate call routing for each tenant
      • Individual voicemail and recording storage per domain

    3. Billing and Reporting:

      • Generate per-tenant CDR reports
      • Implement separate billing for each domain
      • Track resource usage by tenant

High Availability Configuration

For mission-critical deployments, implement redundancy:

    1. Database Replication:

      • Configure PostgreSQL streaming replication
      • Use managed database services with built-in HA
      • Implement automatic failover

    2. Load Balancing (Advanced):

      • Deploy multiple FusionPBX instances
      • Use external load balancer for SIP traffic
      • Share database and persistent storage

    3. Monitoring and Failover:

      • Implement health checks
      • Configure automatic failover procedures
      • Test disaster recovery procedures regularly

Integration Examples

CRM Integration

Integrate FusionPBX with popular CRM systems:

Salesforce:

  • Use FusionPBX API to push CDR data to Salesforce
  • Screen pops for incoming calls with customer information
  • Click-to-dial from Salesforce interface

HubSpot:

  • Log calls automatically to HubSpot timeline
  • Sync contacts between systems
  • Track call outcomes and notes

Custom Applications

FusionPBX provides several integration methods:

    1. REST API:

      • Access extensions, CDR, and configuration via REST endpoints
      • Authenticate with API keys
      • Build custom dashboards or integrations

    2. Event Socket:

      • Real-time call control and monitoring
      • Build custom IVR applications
      • Implement advanced call routing logic

    3. Webhooks:

      • Configure webhooks for call events
      • Receive notifications for missed calls, voicemails, etc.
      • Trigger external workflows based on telephony events

Example: Python API Client

import requests


# FusionPBX API configuration
API_URL = "https://example-app.klutch.sh/api/v1"
API_KEY = "your-api-key"


# Get list of extensions
response = requests.get(
    f"{API_URL}/extensions",
    headers={"Authorization": f"Bearer {API_KEY}"}
)


extensions = response.json()
for ext in extensions:
    print(f"Extension {ext['extension']}: {ext['effective_caller_id_name']}")


# Create a new extension
new_extension = {
    "extension": "1003",
    "effective_caller_id_name": "John Doe",
    "password": "secure-password-here"
}


response = requests.post(
    f"{API_URL}/extensions",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json=new_extension
)


print(f"Created extension: {response.json()}")

Resources and Further Reading

Conclusion

Deploying FusionPBX on Klutch.sh provides a robust, scalable solution for building a complete VoIP communications system. With automatic Docker detection, persistent storage for recordings and voicemails, seamless database integration, TCP traffic support for SIP signaling, and built-in SSL/TLS, you can focus on configuring your telephony features while Klutch.sh handles the infrastructure complexity.

This guide covered everything from basic deployment to advanced configuration, security best practices, troubleshooting, and integrations. Whether you’re running a small office phone system or building a multi-tenant hosted PBX platform, FusionPBX on Klutch.sh offers the flexibility, features, and reliability you need to deliver professional telecommunications services.

With FusionPBX’s rich feature set including multi-tenant support, IVR menus, call centers, voicemail-to-email, fax server, call recording, and comprehensive reporting, combined with Klutch.sh’s simplified deployment and scaling capabilities, you have a complete solution for modern business communications.

For additional help or questions, refer to the resources above or reach out to the FusionPBX community and Klutch.sh support team.