Skip to content
Klutch.sh Docs

Deploying FreePBX

Introduction

FreePBX is the world’s most popular open-source graphical user interface for managing Asterisk PBX systems. Created in 2004, FreePBX transforms the powerful but complex Asterisk telephony engine into an accessible, user-friendly platform that anyone can use to build and manage a complete business phone system without needing deep technical knowledge of VoIP protocols or Asterisk configuration.

At its core, FreePBX provides a comprehensive web-based interface that simplifies every aspect of PBX administration—from creating extensions and configuring voicemail to setting up call routing, IVR menus, ring groups, and advanced features like call recording, time conditions, and feature codes. What would typically require editing dozens of Asterisk configuration files by hand becomes a matter of clicking through intuitive forms and dialogs.

FreePBX includes a powerful module architecture with over 100 commercial and open-source modules available, allowing you to extend functionality with features like CRM integration, billing systems, call center tools, advanced reporting, SMS messaging, and more. It handles everything from small office deployments with a handful of extensions to large enterprise installations supporting thousands of users across multiple locations.

Deploying FreePBX on Klutch.sh combines the power of a professional PBX system with the convenience of managed cloud infrastructure. You get automatic HTTPS for secure web administration, persistent storage for recordings and voicemail, reliable networking for SIP traffic, and the ability to scale resources as your phone system grows—all without managing physical servers or complex networking configurations.

This guide walks you through deploying FreePBX on Klutch.sh using Docker, configuring the database backend, setting up persistent volumes for critical data, connecting to SIP trunks, and implementing production-ready best practices for security, backup, and monitoring.

Why Deploy FreePBX on Klutch.sh?

  • Simplified Management: Web-based PBX administration without command-line complexity
  • Automatic HTTPS: Secure web interface with built-in SSL certificates
  • Persistent Storage: Reliable volume storage for recordings, voicemail, and backups
  • Scalable Infrastructure: Easily adjust resources as your phone system grows
  • Professional Reliability: Enterprise-grade uptime for mission-critical communications
  • Easy Updates: Deploy new FreePBX versions without server maintenance
  • Custom Domains: Use your own domain for professional branding
  • Integrated Database: Simple MariaDB deployment for FreePBX backend
  • GitHub Integration: Version-controlled deployment and configuration management
  • Cost-Effective: No physical hardware or dedicated server costs

Prerequisites

Before you begin, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your deployment
  • Basic understanding of PBX systems and VoIP concepts
  • A SIP trunk provider account (optional, for external calling)

Technical Requirements:

FreePBX requires substantial resources due to Asterisk and web services:

  • Minimum 2GB RAM (4GB recommended for production)
  • At least 10GB persistent storage (20GB+ for call recordings)
  • MariaDB or MySQL database (can be deployed separately on Klutch.sh)
  • Stable internet connection with proper firewall configuration

Dependencies:

FreePBX requires a database. You’ll need to deploy either:

  • MariaDB (recommended) - see our MariaDB deployment guide
  • MySQL - see our MySQL deployment guide

Understanding FreePBX Architecture

FreePBX is built as a comprehensive web application that sits on top of Asterisk:

Core Components:

  • Asterisk PBX: The underlying telephony engine (see our Asterisk deployment guide)
  • FreePBX Framework: PHP-based web interface for configuration management
  • Apache Web Server: Hosts the FreePBX web interface
  • MariaDB/MySQL: Stores all FreePBX configuration and CDR data
  • Node.js: Powers the User Control Panel (UCP) interface
  • Asterisk Manager Interface (AMI): Communication bridge between FreePBX and Asterisk

Key Features:

  • Extension management with BLF (Busy Lamp Field) support
  • Inbound and outbound call routing
  • Interactive Voice Response (IVR) system
  • Ring groups and call queues
  • Voicemail with email notification
  • Time conditions for after-hours routing
  • Call recording with on-demand capabilities
  • Conference bridges
  • Feature codes for quick access
  • Call Detail Records (CDR) reporting
  • Module marketplace for extensions

Data Flow:

When you make configuration changes in FreePBX’s web interface, the framework:

  1. Updates the MySQL/MariaDB database
  2. Generates appropriate Asterisk configuration files
  3. Reloads Asterisk via AMI to apply changes
  4. Provides real-time feedback through the web interface

This architecture allows for powerful PBX functionality while maintaining ease of use through the graphical interface.

Preparing Your Repository

Step 1: Create Project Directory

Create a new directory for your FreePBX deployment:

Terminal window
mkdir freepbx-deploy
cd freepbx-deploy

Step 2: Create Dockerfile

FreePBX requires a complete environment with Asterisk, Apache, and PHP. Create a Dockerfile:

FROM tiredofit/freepbx:16


# FreePBX 16 includes:
# - Asterisk 18
# - PHP 7.4
# - Apache 2.4
# - FreePBX Framework
# - All core modules


# Set timezone
ENV TIMEZONE=America/New_York


# Database configuration (set via environment variables in Klutch.sh)
ENV DB_EMBEDDED=false


# Enable FreePBX services
ENV ENABLE_FAIL2BAN=true \
    ENABLE_CERTIFICATES=true \
    ENABLE_CRON=true \
    ENABLE_SMTP=true


# RTP port range for media
ENV RTP_START=10000 \
    RTP_FINISH=10200


# Set admin email for notifications
ENV ADMIN_EMAIL=admin@example.com


# Expose ports
# 80: HTTP (web interface)
# 443: HTTPS (web interface)
# 5060: SIP (UDP)
# 5061: SIP TLS
# 10000-10200: RTP media
EXPOSE 80 443 5060/udp 5060/tcp 5061/tcp 10000-10200/udp


# Volume mounts for persistent data
VOLUME ["/data", "/var/log", "/var/lib/asterisk/sounds", "/var/spool/asterisk"]


# Health check
HEALTHCHECK --interval=60s --timeout=10s --start-period=120s \
  CMD curl -f http://localhost/admin/config.php || exit 1


# Start FreePBX (inherited from base image)

Alternative: Minimal Custom Build

For more control, you can build from scratch:

FROM debian:bullseye


# Install system dependencies
RUN apt-get update && \
    apt-get install -y \
    apache2 \
    mariadb-client \
    php7.4 \
    php7.4-cli \
    php7.4-mysql \
    php7.4-curl \
    php7.4-gd \
    php7.4-mbstring \
    php7.4-xml \
    sox \
    mpg123 \
    sqlite3 \
    curl \
    wget \
    gnupg2 \
    git \
    unixodbc \
    && apt-get clean


# Install Asterisk
RUN cd /usr/src && \
    wget http://downloads.asterisk.org/pub/telephony/asterisk/asterisk-18-current.tar.gz && \
    tar -xzf asterisk-18-current.tar.gz && \
    cd asterisk-18* && \
    ./configure --with-jansson-bundled && \
    make && \
    make install && \
    make samples && \
    make config && \
    ldconfig


# Install FreePBX
RUN cd /usr/src && \
    wget http://mirror.freepbx.org/modules/packages/freepbx/freepbx-16.0-latest.tgz && \
    tar -xzf freepbx-16.0-latest.tgz && \
    cd freepbx && \
    ./install -n


# Configure Apache for FreePBX
RUN a2enmod rewrite && \
    sed -i 's/AllowOverride None/AllowOverride All/' /etc/apache2/apache2.conf


# Create necessary directories
RUN mkdir -p /var/www/html/admin \
    /var/log/asterisk \
    /var/log/httpd \
    /var/spool/asterisk


EXPOSE 80 5060


CMD ["/usr/sbin/apache2ctl", "-D", "FOREGROUND"]

Step 3: Create Environment Configuration

Create a .env.example file for documentation:

# Database Configuration
DB_HOST=mariadb-app.klutch.sh
DB_PORT=8000
DB_NAME=freepbx
DB_USER=freepbxuser
DB_PASSWORD=your-secure-password


# FreePBX Configuration
FREEPBX_ADMIN_USER=admin
FREEPBX_ADMIN_PASSWORD=your-admin-password
ADMIN_EMAIL=admin@yourdomain.com


# Timezone
TIMEZONE=America/New_York


# SMTP Configuration (for email notifications)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-smtp-password
SMTP_FROM=noreply@yourdomain.com


# SIP Configuration
SIP_BIND_PORT=5060
RTP_START=10000
RTP_FINISH=10200


# Security
ENABLE_FAIL2BAN=true
FAIL2BAN_MAXRETRY=5
FAIL2BAN_BANTIME=600

Step 4: Create .gitignore

Create a .gitignore file to exclude sensitive data:

# Environment files
.env
.env.local
.env.production


# FreePBX data
/data/
/recordings/
/backups/


# Logs
*.log
/var/log/


# System files
.DS_Store
Thumbs.db


# Asterisk
/etc/asterisk/*.conf

Step 5: Create README.md

Document your deployment:

# FreePBX on Klutch.sh


Open-source PBX system with web-based management interface.


## Quick Start


1. Deploy MariaDB database on Klutch.sh
2. Push this repository to GitHub
3. Deploy FreePBX on Klutch.sh
4. Access web interface at your assigned URL
5. Complete initial setup wizard


## Features


- Extension Management
- Call Routing & IVR
- Voicemail
- Call Recording
- Ring Groups
- Time Conditions
- Conference Bridges
- And more...


## Configuration


See Klutch.sh dashboard for environment variables and volume configuration.


## Documentation


- [FreePBX Wiki](https://wiki.freepbx.org/)
- [Asterisk Documentation](https://www.asterisk.org/community/documentation/)

Step 6: Push to GitHub

Initialize git and push your repository:

Terminal window
git init
git add Dockerfile .env.example .gitignore README.md
git commit -m "Initial FreePBX deployment setup"
git branch -M main
git remote add origin https://github.com/your-username/freepbx-deploy.git
git push -u origin main

Deploying the Database

FreePBX requires a MariaDB or MySQL database. Deploy the database first before deploying FreePBX.

    1. Follow our MariaDB deployment guide to set up a database server

    2. Configure the MariaDB deployment with:

      • TCP Traffic on port 8000
      • Persistent Volume: /var/lib/mysql with at least 5GB
      • Environment Variables:
        • MYSQL_ROOT_PASSWORD: Strong root password
        • MYSQL_DATABASE: freepbx
        • MYSQL_USER: freepbxuser
        • MYSQL_PASSWORD: Strong user password

    3. Note the connection details:

      • Host: your-mariadb-app.klutch.sh
      • Port: 8000
      • Database: freepbx
      • Username: freepbxuser
      • Password: Your configured password

Option 2: Use External Managed Database

You can also use external managed database services:

Deploying FreePBX on Klutch.sh

Step 1: Create New App

    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 FreePBX GitHub repository
      • Branch: Choose the branch to deploy (e.g., main or production)
      • Traffic Type: Select HTTP (FreePBX web interface runs on HTTP/HTTPS)
      • Internal Port: Set to 80 (FreePBX’s Apache server listens on port 80)

Step 2: Configure Persistent Volumes

FreePBX requires persistent storage for recordings, voicemail, configurations, and backups.

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

    2. Add a volume for FreePBX data:

      • Mount Path: /data
      • Size: 10GB minimum (20GB recommended for call recordings)

    3. Add a volume for Asterisk spool (voicemail, recordings):

      • Mount Path: /var/spool/asterisk
      • Size: 5GB (scale based on voicemail and recording needs)

    4. Add a volume for Asterisk sounds (optional):

      • Mount Path: /var/lib/asterisk/sounds
      • Size: 2GB

    5. (Optional) Add a volume for logs:

      • Mount Path: /var/log
      • Size: 2GB

Step 3: Configure Environment Variables

Set essential environment variables for your FreePBX deployment:

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

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

      Database Configuration:

      Terminal window
      DB_HOST=your-mariadb-app.klutch.sh
      DB_PORT=8000
      DB_NAME=freepbx
      DB_USER=freepbxuser
      DB_PASSWORD=your-database-password

      FreePBX Administration:

      Terminal window
      FREEPBX_ADMIN_USER=admin
      FREEPBX_ADMIN_PASSWORD=your-secure-admin-password
      ADMIN_EMAIL=admin@yourdomain.com

      System Configuration:

      Terminal window
      TIMEZONE=America/New_York
      DB_EMBEDDED=false

      RTP Media Ports:

      Terminal window
      RTP_START=10000
      RTP_FINISH=10200

      Security Settings:

      Terminal window
      ENABLE_FAIL2BAN=true
      FAIL2BAN_MAXRETRY=5

      SMTP Configuration (for notifications):

      Terminal window
      SMTP_HOST=smtp.gmail.com
      SMTP_PORT=587
      SMTP_USER=your-email@gmail.com
      SMTP_PASSWORD=your-smtp-password

Step 4: Deploy Your Application

    1. Click Deploy to start the build process

    2. Klutch.sh will:

      • Pull your GitHub repository
      • Detect the Dockerfile automatically
      • Build the FreePBX container image
      • Deploy it with your configured volumes and environment variables

    3. Monitor the build logs for any errors

    4. Once deployed, your FreePBX will be available at https://example-app.klutch.sh

    5. Initial deployment may take 5-10 minutes as FreePBX initializes the database

Initial Setup and Configuration

After deployment, complete the FreePBX initial setup:

Step 1: Access Web Interface

    1. Navigate to https://example-app.klutch.sh in your browser

    2. You should see the FreePBX welcome screen

    3. If prompted for activation, you can skip commercial module activation for open-source use

Step 2: Complete Setup Wizard

    1. Create your admin account (if not set via environment variables):

      • Username: admin
      • Password: Strong password (minimum 12 characters)
      • Email: Your email for notifications

    2. Configure initial settings:

      • Time Zone: Select your time zone
      • Language: Choose your preferred language
      • Number Format: Select your region’s format

    3. Click through the setup wizard to completion

Step 3: Verify Database Connection

    1. Navigate to Admin → System Admin → Database

    2. Verify connection to your MariaDB instance

    3. Ensure all database tables are created successfully

Step 4: Configure Asterisk Settings

    1. Navigate to Settings → Asterisk SIP Settings

    2. Configure SIP settings:

      • Bind Address: 0.0.0.0 (listen on all interfaces)
      • External Address: Your Klutch.sh app URL
      • Local Networks: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16

    3. Configure RTP settings:

      • RTP Start: 10000
      • RTP End: 10200

    4. Click Submit and Apply Config

Creating Your First Extension

Set up a basic SIP extension to test your FreePBX installation:

Create SIP Extension

    1. Navigate to Applications → Extensions

    2. Click Add Extension → Add New Chan_SIP Extension

    3. Configure the extension:

      • User Extension: 1000 (or your preferred number)
      • Display Name: Test User
      • Secret: Generate a strong password
      • Voicemail: Enable voicemail
      • Email: User’s email for voicemail notifications

    4. Under Advanced tab:

      • Context: from-internal
      • Host: dynamic
      • NAT: yes

    5. Click Submit and Apply Config

Test Extension with Softphone

    1. Download a SIP softphone:

      • Linphone (Windows, Mac, Linux, Mobile)
      • Zoiper (Windows, Mac, Linux, Mobile)
      • Bria (Commercial option)

    2. Configure the softphone:

      • Server/Domain: example-app.klutch.sh
      • Username: 1000
      • Password: Extension secret
      • Port: 5060

    3. The extension should register successfully

    4. Create a second extension (e.g., 1001) and test calling between extensions

Configuring Inbound Routes

Set up how incoming calls are handled:

Basic Inbound Route

    1. Navigate to Connectivity → Inbound Routes

    2. Click Add Inbound Route

    3. Configure the route:

      • Description: Main Line
      • DID Number: Your phone number from SIP trunk (or leave blank for catch-all)
      • Caller ID: Leave blank to match all callers

    4. Set destination:

      • Set Destination: Choose destination type (Extension, Ring Group, IVR, etc.)
      • Select specific destination

    5. Click Submit and Apply Config

Create IVR (Auto Attendant)

    1. Navigate to Applications → IVR

    2. Click Add IVR

    3. Configure the IVR:

      • Name: Main Menu
      • Announcement: Record or upload greeting
      • Timeout: 10 seconds
      • Invalid Retry Recording: Select recording

    4. Add IVR entries:

      • Option 1: Sales (extension or ring group)
      • Option 2: Support (extension or ring group)
      • Option 0: Operator (specific extension)

    5. Click Submit and Apply Config

    6. Update inbound route to point to this IVR

Connecting to SIP Trunk Provider

Connect FreePBX to a SIP trunk for external calling:

Configure Trunk

    1. Navigate to Connectivity → Trunks

    2. Click Add Trunk → Add SIP (chan_pjsip) Trunk

    3. Configure trunk details:

      • Trunk Name: MyProvider
      • Outbound CallerID: Your main number

    4. In pjsip Settings tab:

      • Username: Provided by trunk provider
      • Secret: Provided by trunk provider
      • SIP Server: Trunk provider’s server address
      • SIP Server Port: Usually 5060
      • Context: from-pstn

    5. In Advanced tab:

      • Registration: Enable if required by provider
      • DTMF Mode: RFC 4733 (recommended)
      • Codecs: Select ulaw, alaw, g729 as supported

    6. Click Submit and Apply Config

Create Outbound Route

    1. Navigate to Connectivity → Outbound Routes

    2. Click Add Outbound Route

    3. Configure the route:

      • Route Name: US/Canada
      • Route CID: Your caller ID number
      • Route Password: Leave blank
      • Override Extension: No

    4. Add dial patterns:

      • Dial Pattern: NXXNXXXXXX (10-digit US/Canada)
      • Prefix: Leave blank
      • Prepend: 1 (if required by trunk)

    5. Select trunk:

      • Move your trunk to Trunk Sequence list

    6. Click Submit and Apply Config

Setting Up Voicemail

Configure voicemail for extensions:

Global Voicemail Settings

    1. Navigate to Settings → Voicemail Admin

    2. Configure general settings:

      • Email Subject: New voicemail from [VM_CALLERID]
      • Email Body: Customize message template
      • Format: Choose WAV or MP3 for attachments
      • Delete After Email: Choose based on preference

    3. Configure advanced options:

      • Max Messages: 100 (or preferred limit)
      • Max Message Time: 300 seconds (5 minutes)
      • Min Message Time: 2 seconds

    4. Click Submit and Apply Config

Configure Extension Voicemail

    1. Navigate to Applications → Extensions

    2. Select an extension to edit

    3. In Voicemail section:

      • Status: Enabled
      • Voicemail Password: Set 4-digit PIN
      • Email Address: User’s email
      • Pager Email: Optional
      • Email Attachment: Yes to include recording
      • Play CID: Yes to hear caller info
      • Play Envelope: Yes to hear date/time
      • Delete Vmail: Yes to delete after emailing

    4. Click Submit and Apply Config

Call Recording Configuration

Set up call recording for quality assurance:

Enable Call Recording

    1. Navigate to Admin → Call Recording

    2. Configure recording settings:

      • Recording Format: WAV (best quality) or MP3 (smaller size)
      • Recording Directory: /var/spool/asterisk/monitor
      • Custom Format: Choose filename format

    3. Enable recording methods:

      • On-Demand: Allow users to start/stop recording with feature code
      • Automatic: Record all calls automatically
      • On-Demand with Notification: Announce recording is active

Configure Per-Extension Recording

    1. Navigate to Applications → Extensions

    2. Select extension to edit

    3. In Recording Options:

      • Inbound External Calls: Choose recording mode
      • Outbound External Calls: Choose recording mode
      • Internal Calls: Choose recording mode
      • On Demand Recording: Enable for user control

    4. Feature codes for recording:

      • Start Recording: *1
      • Stop Recording: *0

    5. Click Submit and Apply Config

Ring Groups and Call Queues

Create Ring Group

Ring groups allow multiple extensions to ring simultaneously:

    1. Navigate to Applications → Ring Groups

    2. Click Add Ring Group

    3. Configure the group:

      • Group Number: 2000
      • Group Description: Sales Team
      • Ring Strategy: Choose strategy:
        • ringall: Ring all extensions simultaneously
        • hunt: Ring in order until someone answers
        • memoryhunt: Like hunt, but remembers last answered
      • Ring Time: 20 seconds per extension
      • Extension List: Add extensions (e.g., 1000, 1001, 1002)

    4. Configure destination:

      • Destination if No Answer: Voicemail, IVR, or other destination

    5. Click Submit and Apply Config

Create Call Queue

Call queues are for high-volume call centers:

    1. Navigate to Applications → Queues

    2. Click Add Queue

    3. Configure the queue:

      • Queue Number: 3000
      • Queue Name: Support Queue
      • Queue Password: Optional password to join queue
      • CID Name Prefix: Q- to identify queue calls
      • Max Wait Time: 300 seconds before routing elsewhere
      • Max Callers: 25 maximum callers in queue

    4. Add static agents:

      • Select extensions to add as queue agents
      • Agents will automatically receive queue calls

    5. Configure options:

      • Agent Announcement: Announce to agent before connecting
      • Join Announcement: Message for caller entering queue
      • Music on Hold: Select hold music category
      • Strategy: ringall, leastrecent, fewestcalls, etc.

    6. Set destination if queue full or timeout

    7. Click Submit and Apply Config

Time Conditions

Route calls differently based on time of day:

Create Time Condition

    1. Navigate to Applications → Time Conditions

    2. Click Add Time Condition

    3. Configure the condition:

      • Time Condition Name: Business Hours
      • Time Group: Create new time group

    4. Create time group:

      • Group Name: Business Hours
      • Time to Start: 08:00
      • Time to Finish: 17:00
      • Week Days: Monday through Friday
      • Month Days: All

    5. Set destinations:

      • Matching: Route to receptionist or IVR
      • Not Matching: Route to voicemail or after-hours message

    6. Click Submit and Apply Config

    7. Update inbound routes to use this time condition

Custom Domain Configuration

For production use, configure a custom domain:

Step 1: Configure Domain in Klutch.sh

    1. In the Klutch.sh dashboard, navigate to your app settings

    2. Go to the Domains section

    3. Add your custom domain (e.g., pbx.yourdomain.com)

    4. Klutch.sh will provide DNS records to configure

Step 2: Update DNS Records

    1. Log in to your domain registrar

    2. Add the DNS records provided by Klutch.sh:

      • CNAME record pointing to your Klutch.sh app
      • Wait for DNS propagation (up to 48 hours)

    3. Klutch.sh will automatically provision SSL certificates

Step 3: Update FreePBX Configuration

    1. Access your FreePBX admin panel

    2. Navigate to Settings → Asterisk SIP Settings

    3. Update the External Address to your custom domain

    4. Navigate to Admin → System Admin → Port Management

    5. Update any references to use your custom domain

    6. Click Apply Config to activate changes

Security Best Practices

Strong Authentication

    1. Use Strong Passwords:

      • Admin password: Minimum 16 characters
      • Extension secrets: Minimum 12 characters, alphanumeric + symbols
      • Database password: Minimum 16 characters
      • Use a password manager

    2. Enable Two-Factor Authentication:

      • Navigate to Admin → System Admin → User Management
      • Enable 2FA for admin accounts
      • Use authenticator app like Google Authenticator or Authy

    3. Regular Password Rotation:

      • Change admin passwords quarterly
      • Rotate extension secrets annually
      • Update service passwords semi-annually

Network Security

    1. Configure Firewall:

      • Navigate to Admin → System Admin → Firewall
      • Enable responsive firewall
      • Add trusted IP addresses
      • Set fail2ban rules for SIP authentication failures

    2. Fail2Ban Configuration:

      • Navigate to Admin → Intrusion Detection
      • Enable Fail2Ban protection
      • Set ban time: 600 seconds (10 minutes)
      • Set max retries: 5
      • Monitor banned IPs regularly

    3. Enable TLS for SIP:

      • Navigate to Settings → Asterisk SIP Settings
      • Enable TLS on port 5061
      • Configure certificates
      • Update extensions to use TLS transport

Extension Security

    1. Permit/Deny Settings:

      • Navigate to Applications → Extensions
      • For each extension, under Advanced:
        • Set Permit to specific IP ranges
        • Or set Deny to 0.0.0.0/0.0.0.0 and Permit to trusted IPs

    2. Disable Unused Extensions:

      • Regularly audit extension list
      • Disable or delete unused extensions
      • Monitor extension registration status

    3. Feature Code Restrictions:

      • Navigate to Admin → Feature Codes
      • Restrict sensitive features to specific extensions
      • Disable unnecessary feature codes

Monitoring and Alerts

    1. Enable System Notifications:

      • Navigate to Admin → System Admin → Notifications
      • Enable email alerts for:
        • System updates
        • Security events
        • Service failures
        • Disk space warnings

    2. CDR Monitoring:

      • Navigate to Reports → CDR Reports
      • Review call patterns regularly
      • Look for unusual call destinations
      • Monitor international calls

    3. Log Review:

      • Navigate to Admin → Log Files
      • Review Asterisk logs for errors
      • Check security logs for intrusion attempts
      • Monitor failed authentication attempts

Backup and Recovery

Automated Backups

    1. Configure Backup Schedule:

      • Navigate to Admin → Backup & Restore
      • Click Add Backup
      • Configure backup:
        • Name: Daily Backup
        • Type: Full Backup
        • Items: Select all (configurations, voicemail, recordings, etc.)
        • Maintenance: Delete backups older than 30 days

    2. Set Backup Schedule:

      • Schedule: Daily at 2:00 AM
      • Email Notification: Send report after backup

    3. Backup Destination:

      • Local: Store on persistent volume
      • Remote: Configure FTP, SFTP, or S3 storage
      • Recommended: Use both local and remote

    4. Click Submit to save backup configuration

Manual Backup

    1. Navigate to Admin → Backup & Restore

    2. Click Backup tab

    3. Select items to backup:

      • System configurations
      • Voicemail messages
      • Call recordings
      • Custom sounds
      • CDR data

    4. Click Run Backup Now

    5. Download backup file once complete

Restoration Procedure

    1. Access Backup & Restore:

      • Navigate to Admin → Backup & Restore
      • Click Restore tab

    2. Upload Backup File:

      • Click Browse to select backup file
      • Or select from available backups

    3. Select Restore Items:

      • Choose which components to restore
      • Warning: Restoration will overwrite current configuration

    4. Execute Restore:

      • Click Restore button
      • System will restart services after restoration
      • Wait for completion (may take several minutes)

    5. Verify Restoration:

      • Check extensions are configured correctly
      • Test inbound and outbound calling
      • Verify voicemail is accessible
      • Review call routing

Volume Snapshots

Use Klutch.sh volume snapshots for additional protection:

    1. In Klutch.sh dashboard, navigate to Volumes

    2. Select volume to snapshot

    3. Click Create Snapshot

    4. Name snapshot with date: freepbx-data-2024-01-15

    5. Schedule regular snapshots before major changes

    6. Restore from snapshot if needed by creating new volume

Performance Optimization

Resource Allocation

    1. CPU and Memory:

      • Monitor resource usage in Klutch.sh dashboard
      • Scale up if call quality degrades
      • Recommended minimums:
        • Small office (<10 extensions): 2 vCPU, 2GB RAM
        • Medium business (<50 extensions): 4 vCPU, 4GB RAM
        • Large enterprise (>50 extensions): 8 vCPU, 8GB RAM

    2. Database Optimization:

      • Navigate to Admin → System Admin → Database
      • Run database optimization weekly
      • Enable query cache
      • Purge old CDR records regularly

    3. Audio Codec Selection:

      • Navigate to Settings → Asterisk SIP Settings
      • Prioritize codecs by quality/bandwidth:
        • Best quality: g722, opus
        • Balance: ulaw, alaw
        • Low bandwidth: g729
      • Disable unused codecs to reduce negotiation time

Call Quality Optimization

    1. RTP Quality of Service (QoS):

      • Navigate to Settings → Asterisk SIP Settings → Other SIP Settings
      • Set tos_audio to ef (Expedited Forwarding)
      • Set cos_audio to 5

    2. Jitter Buffer:

      • Navigate to Settings → Asterisk SIP Settings → Chan SIP Settings
      • Enable jitter buffer: yes
      • Set jbmaxsize to 200 (adjust based on network conditions)

    3. Network Testing:

      • Use tools to test network quality:
      • Monitor packet loss, jitter, and latency
      • Aim for: <1% packet loss, <30ms jitter, <150ms latency

Monitoring and Maintenance

System Monitoring

    1. Dashboard Overview:

      • Navigate to Dashboard in FreePBX
      • Monitor real-time statistics:
        • Active calls
        • Extension status
        • Trunk registration
        • System resources

    2. Call Reports:

      • Navigate to Reports → CDR Reports
      • Review call statistics:
        • Call volume by hour/day
        • Average call duration
        • Failed call attempts
        • Top destinations

    3. Extension Status:

      • Navigate to Applications → Extensions
      • Monitor extension registration
      • Check for offline or expired registrations
      • Review extension usage patterns

Regular Maintenance Tasks

    1. Weekly Tasks:

      • Review call quality reports
      • Check for system updates
      • Verify backups completed successfully
      • Monitor disk space usage
      • Review security logs

    2. Monthly Tasks:

      • Update FreePBX modules
      • Optimize database
      • Purge old CDR records (if desired)
      • Review and adjust call routing
      • Audit extension list

    3. Quarterly Tasks:

      • Update Asterisk (if available)
      • Review and update security policies
      • Conduct disaster recovery drill
      • Review trunk utilization and costs
      • Update documentation

Troubleshooting Common Issues

FreePBX Won’t Start

    1. Check Container Logs:

      • View logs in Klutch.sh dashboard
      • Look for initialization errors
      • Check database connection errors

    2. Verify Database Connection:

      • Ensure database is running and accessible
      • Check DB_HOST, DB_PORT environment variables
      • Test database connectivity: mysql -h DB_HOST -P DB_PORT -u DB_USER -p

    3. Check Volume Mounts:

      • Ensure volumes are properly attached
      • Verify mount paths are correct
      • Check for sufficient storage space

    4. Restart Services:

      • Redeploy the app from Klutch.sh dashboard
      • Wait for initialization to complete (5-10 minutes)

Extensions Won’t Register

    1. Check Extension Configuration:

      • Navigate to Applications → Extensions
      • Verify extension details are correct
      • Check secret is set properly

    2. Verify Network Settings:

      • Navigate to Settings → Asterisk SIP Settings
      • Check External Address is set correctly
      • Verify Local Networks includes your network
      • Ensure NAT settings are correct

    3. Check Firewall:

      • Verify SIP port 5060 is accessible
      • Check if firewall is blocking registration
      • Review Fail2Ban banned IPs

    4. Test with Softphone:

      • Enable debug mode on softphone
      • Check registration errors
      • Verify server address and credentials

No Audio or One-Way Audio

    1. RTP Port Configuration:

      • Navigate to Settings → Asterisk SIP Settings → Chan SIP Settings
      • Verify RTP port range: 10000-10200
      • Ensure ports are not blocked by firewall

    2. NAT Configuration:

      • Navigate to Settings → Asterisk SIP Settings
      • Set External Address to your public domain
      • Set Local Networks correctly
      • Enable NAT on extensions

    3. Codec Issues:

      • Check both ends support common codec
      • Navigate to Settings → Asterisk SIP Settings
      • Ensure ulaw and alaw are enabled
      • Check trunk codec settings

    4. Network Quality:

      • Test for packet loss and jitter
      • Check bandwidth availability
      • Run network diagnostic tools

Calls Drop After 15-30 Seconds

    1. SIP Session Timer Issue:

      • Navigate to Settings → Asterisk SIP Settings → Chan SIP Settings
      • Set session-timers to refuse or accept
      • Adjust session timer values

    2. RTP Timeout:

      • Navigate to Settings → Asterisk SIP Settings → Chan SIP Settings
      • Increase rtptimeout to 300 seconds
      • Adjust rtpholdtimeout as needed

    3. Firewall Connection Tracking:

      • Ensure firewall allows established connections
      • Check NAT session timeout on router
      • Consider using SIP over TCP instead of UDP

Trunk Registration Fails

    1. Check Trunk Configuration:

      • Navigate to Connectivity → Trunks
      • Verify credentials are correct
      • Check SIP server address and port
      • Review trunk provider documentation

    2. Test Connectivity:

      • Use SIP debug to see registration attempts
      • Navigate to Admin → Asterisk CLI
      • Run: pjsip set logger on
      • Attempt registration and review output

    3. Contact Trunk Provider:

      • Verify account is active and funded
      • Check for IP whitelist requirements
      • Confirm registration is required
      • Request technical support if needed

Production Deployment Checklist

Before going live with FreePBX:

  • Database deployed and accessible
  • Persistent volumes configured and tested (minimum 10GB for /data)
  • All environment variables set correctly
  • Admin account created with strong password
  • Two-factor authentication enabled
  • SSL/HTTPS working correctly (automatic via Klutch.sh)
  • Extensions created and tested
  • Softphones registered successfully
  • Internal calling tested (extension to extension)
  • SIP trunk configured and registered
  • Outbound calling tested
  • Inbound routes configured
  • Voicemail set up and tested
  • Email notifications working
  • Call recording configured (if needed)
  • IVR or auto-attendant configured
  • Ring groups/queues set up (if needed)
  • Time conditions configured
  • Backup schedule configured and tested
  • Security settings reviewed (Fail2Ban, firewall)
  • Monitoring and alerting configured
  • Custom domain configured (optional)
  • User training completed
  • Documentation updated with specific configuration

Advanced Configuration

Multi-Site Deployment

Connect multiple FreePBX instances:

    1. Configure IAX2 Trunk:

      • Navigate to Connectivity → Trunks
      • Add IAX2 trunk between sites
      • Configure authentication

    2. Set Up Dial Plan:

      • Create site-specific extensions (Site A: 1xxx, Site B: 2xxx)
      • Configure outbound routes for inter-site calling

    3. Enable DUNDi (optional):

      • Distributed Universal Number Discovery
      • Allows automatic extension lookup across sites
      • Navigate to Settings → DUNDi Settings

CRM Integration

Integrate FreePBX with CRM systems:

    1. Enable UCP (User Control Panel):

      • Navigate to Settings → User Control Panel
      • Enable UCP access for users
      • Configure permissions

    2. Install CRM Modules:

      • Navigate to Admin → Module Admin
      • Search for CRM integration modules:
        • SugarCRM
        • Salesforce
        • HubSpot
        • Custom integration via REST API

    3. Configure Screen Pops:

      • Automatic customer lookup on incoming calls
      • Display customer information
      • Click-to-dial functionality

Advanced Call Routing

Implement sophisticated routing logic:

    1. Custom Contexts:

      • Edit dialplan in Admin → Config Edit
      • Create custom contexts for special routing
      • Use AGI scripts for dynamic routing

    2. Database Lookups:

      • Use MySQL/MariaDB for routing decisions
      • Query customer database for personalized routing
      • Implement time-based routing rules

    3. API Integration:

      • Use Asterisk REST Interface (ARI)
      • Integrate with external services
      • Build custom applications

Migration from Existing PBX

Exporting Configuration

If migrating from another FreePBX installation:

    1. Export from Old System:

      • Navigate to Admin → Backup & Restore
      • Create full backup
      • Download backup file

    2. Prepare for Import:

      • Ensure FreePBX versions are compatible
      • Document any custom configurations
      • Export CDR data separately if needed

    3. Import to New System:

      • Upload backup to new FreePBX instance
      • Restore configuration
      • Verify all settings

Porting Phone Numbers

    1. Contact Current Provider:

      • Request Letter of Authorization (LOA)
      • Obtain account and PIN information
      • Note any contractual obligations

    2. Submit Port Request:

      • Work with new SIP trunk provider
      • Submit porting paperwork
      • Expect 7-14 days for completion

    3. Test During Port:

      • Configure both old and new trunks
      • Test call flow before cutover
      • Schedule cutover for low-traffic period

    4. Post-Port Verification:

      • Test all inbound numbers
      • Verify caller ID
      • Update any documentation

Resources and Further Reading

Conclusion

Deploying FreePBX on Klutch.sh provides a powerful, professional-grade PBX system with the ease of managed cloud infrastructure. With automatic HTTPS, persistent storage, reliable database connectivity, and the ability to scale resources as needed, you can focus on managing your communications rather than maintaining servers.

This guide covered everything from initial deployment to advanced configuration, security hardening, backup procedures, and troubleshooting. Whether you’re setting up a small business phone system or deploying an enterprise call center, FreePBX on Klutch.sh offers the flexibility, reliability, and features you need.

Remember to keep your system updated, maintain regular backups, monitor call quality, and follow security best practices. For additional help or questions, refer to the resources above or engage with the FreePBX community.

Happy dialing!