How to Install FreePBX 17 on Debian 12

1. Prerequisites

FreePBX 17 is the latest major release of the popular open-source PBX management interface for Asterisk. This guide walks you through a clean installation on Debian 12 (Bookworm), which is the recommended base OS for production FreePBX deployments.

System Requirements

Required Information

Gather this information before starting:

• ● Your server's public IP address
• ● IPComms SIP trunk credentials (username, password, server)
• ● DID phone numbers for inbound routing
• ● A fully qualified domain name (optional, for HTTPS access)

2. Install Asterisk

FreePBX 17 requires Asterisk 21 or 22 as its telephony engine. You will need to compile Asterisk from source with specific options that FreePBX expects. Below is a condensed version of the key steps. For the full detailed walkthrough, see our complete Asterisk installation guide.

Install Build Dependencies

# Update system packages
sudo apt update && sudo apt upgrade -y
# Install essential build tools and Asterisk dependencies
sudo apt install -y build-essential git wget curl linux-headers-$(uname -r) \
    libncurses5-dev libssl-dev libxml2-dev libsqlite3-dev uuid-dev \
    libjansson-dev libspeex-dev libspeexdsp-dev libogg-dev libvorbis-dev \
    libasound2-dev libcurl4-openssl-dev libical-dev libneon27-dev \
    libsrtp2-dev unixodbc-dev libmyodbc odbc-mariadb libiksemel-dev \
    libnewt-dev libpopt-dev libedit-dev libradcli-dev libpjproject-dev \
    libopus-dev sox mpg123 ffmpeg

Download and Compile Asterisk 22

# Download Asterisk 22 LTS
cd /usr/src
sudo wget https://downloads.asterisk.org/pub/telephony/asterisk/asterisk-22-current.tar.gz
sudo tar -xvzf asterisk-22-current.tar.gz
cd asterisk-22*/
# Install prerequisites and MP3 support
sudo contrib/scripts/install_prereq install
sudo contrib/scripts/get_mp3_source.sh
# Configure, compile, and install
sudo ./configure --with-pjproject-bundled=no
sudo make menuselect.makeopts
sudo menuselect/menuselect --enable format_mp3 menuselect.makeopts
sudo make -j$(nproc)
sudo make install
sudo make samples
sudo make config
sudo make install-logrotate

Create Asterisk User

# Create the asterisk system user
sudo groupadd asterisk
sudo useradd -r -d /var/lib/asterisk -g asterisk asterisk
sudo usermod -aG audio,dialout asterisk
# Set ownership
sudo chown -R asterisk:asterisk /etc/asterisk
sudo chown -R asterisk:asterisk /var/lib/asterisk
sudo chown -R asterisk:asterisk /var/log/asterisk
sudo chown -R asterisk:asterisk /var/spool/asterisk
sudo chown -R asterisk:asterisk /var/run/asterisk
sudo chown -R asterisk:asterisk /usr/lib/asterisk

Configure Asterisk to Run as asterisk User

# Edit /etc/asterisk/asterisk.conf
sudo sed -i 's/^;runuser.*/runuser = asterisk/' /etc/asterisk/asterisk.conf
sudo sed -i 's/^;rungroup.*/rungroup = asterisk/' /etc/asterisk/asterisk.conf

3. Install FreePBX Dependencies

FreePBX requires a web server (Apache), a database (MariaDB), PHP 8.2, Node.js, and several other packages. Install them all before proceeding with the FreePBX installation.

Install Apache Web Server

# Install Apache and enable required modules
sudo apt install -y apache2
sudo a2enmod rewrite headers expires
sudo systemctl enable apache2

Install MariaDB

# Install MariaDB server
sudo apt install -y mariadb-server mariadb-client
sudo systemctl enable mariadb
sudo systemctl start mariadb
# Secure MariaDB installation
sudo mysql_secure_installation

During the security wizard, answer the prompts:

• ● Set a root password (or use unix_socket auth)
• ● Remove anonymous users: Yes
• ● Disallow root login remotely: Yes
• ● Remove test database: Yes
• ● Reload privilege tables: Yes

Install PHP 8.2

# Install PHP 8.2 and required extensions
sudo apt install -y php8.2 php8.2-cli php8.2-common php8.2-curl \
    php8.2-gd php8.2-mbstring php8.2-mysql php8.2-xml php8.2-zip \
    php8.2-bcmath php8.2-intl php8.2-ldap php8.2-soap \
    php8.2-imap php8.2-fpm php-pear libapache2-mod-php8.2

Configure PHP for FreePBX

# Adjust PHP settings for FreePBX
sudo sed -i 's/upload_max_filesize = 2M/upload_max_filesize = 120M/' /etc/php/8.2/apache2/php.ini
sudo sed -i 's/post_max_size = 8M/post_max_size = 120M/' /etc/php/8.2/apache2/php.ini
sudo sed -i 's/memory_limit = 128M/memory_limit = 256M/' /etc/php/8.2/apache2/php.ini

Install Node.js

# Install Node.js 18 LTS (required by FreePBX 17)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo bash -
sudo apt install -y nodejs
# Verify Node.js installation
node --version
npm --version

Install Additional Dependencies

# Additional packages required by FreePBX
sudo apt install -y sudo lsb-release ca-certificates apt-transport-https \
    software-properties-common cron at dbus rsyslog logrotate \
    libicu-dev pkg-config

4. Download & Install FreePBX

With all dependencies in place, download FreePBX 17 and run the installation script. The installer will set up the database, configure Apache, and install the core FreePBX modules.

Download FreePBX 17

# Download FreePBX 17 from the official repository
cd /usr/src
sudo wget https://github.com/FreePBX/framework/archive/refs/heads/release/17.0.zip -O freepbx-17.zip
sudo apt install -y unzip
sudo unzip freepbx-17.zip
cd framework-release-17.0

Start Asterisk Before Installing

# Asterisk must be running for the FreePBX installer
sudo systemctl start asterisk
sudo systemctl status asterisk

Run the FreePBX Installer

# Run the install script
sudo ./install -n

The -n flag runs the installer non-interactively with default settings. If you want to customize the installation (e.g., database name, user), run sudo ./install without the flag.

The installer will:

• ● Create the asterisk and asteriskcdrdb databases
• ● Configure Apache with the FreePBX virtual host
• ● Install core FreePBX modules
• ● Set up the Asterisk Manager Interface (AMI)

Set Permissions

# Set correct ownership for FreePBX web files
sudo chown -R asterisk:asterisk /var/www/html
sudo chown -R asterisk:asterisk /var/lib/asterisk
sudo chown -R asterisk:asterisk /etc/asterisk
# Add Apache user to asterisk group
sudo usermod -aG asterisk www-data

Configure Apache

# Set AllowOverride to All for the FreePBX directory
sudo sed -i 's/AllowOverride None/AllowOverride All/' /etc/apache2/apache2.conf
# Restart Apache to apply changes
sudo systemctl restart apache2

Install All FreePBX Modules

# Install all available FreePBX modules
sudo -u asterisk fwconsole ma installall
sudo -u asterisk fwconsole reload
sudo -u asterisk fwconsole chown

5. Initial Web Setup

With FreePBX installed, access the web interface to complete the initial configuration. Open your browser and navigate to your server's IP address.

Access the FreePBX GUI

Open a web browser and go to:

http://YOUR_SERVER_IP/admin

On first access, FreePBX will prompt you to create an administrator account.

Create Admin Account

• ● Username: Choose a unique admin username (avoid "admin" for security)
• ● Password: Use a strong password with mixed case, numbers, and symbols
• ● Email: Enter a valid email for system notifications

Activate FreePBX

After logging in, FreePBX will prompt you to activate your installation. Activation is free and required for accessing the online module repository:

• 1. Click Activate in the top notification bar
• 2. Create a Sangoma account or sign in with an existing one
• 3. Follow the activation wizard to link your installation

Configure System Settings

Navigate to Settings > Asterisk SIP Settings and configure these essential settings:

• ● External Address: Enter your server's public IP address
• ● Local Networks: Add your internal subnet (e.g., 192.168.1.0/24)
• ● Timezone: Go to Settings > Advanced Settings and set your PHP timezone
• ● Language: Set the default system language under Settings > Advanced Settings

6. Configure IPComms SIP Trunk

Now connect your FreePBX system to IPComms SIP trunking for inbound and outbound calling. This is done entirely through the FreePBX web interface.

Add a New SIP Trunk

In the FreePBX admin panel:

• 1. Navigate to Connectivity > Trunks
• 2. Click Add Trunk
• 3. Select Add SIP (chan_pjsip) Trunk

General Tab Settings

pjsip Settings Tab

Under the pjsip Settings tab, configure the General sub-tab:

Under the Advanced sub-tab, configure these settings:

Codec Configuration

Under the Codecs sub-tab, enable the following codecs in order of preference:

• 1. g722 - Wideband HD audio (recommended)
• 2. ulaw - G.711 mu-law (North America standard)
• 3. alaw - G.711 A-law (International standard)

Click Submit, then click the red Apply Config button at the top of the page.

Get Your IPComms Credentials

Sign up for IPComms SIP trunking to get your trunk credentials, DID numbers, and access to the customer portal with real-time call analytics. Start with a free SIP trunk -- only pay for usage and numbers.

7. Create Extensions

Extensions are the internal phone numbers used by users and devices on your PBX. Each extension can register a softphone, desk phone, or other SIP device.

Add a New Extension

• 1. Navigate to Applications > Extensions
• 2. Click Add Extension
• 3. Select Add New chan_pjsip Extension

Extension Settings

Click Submit and then Apply Config.

Register a Softphone

Configure your softphone (such as Zoiper, Linphone, or MicroSIP) with these settings:

8. Set Up Inbound & Outbound Routes

Routes tell FreePBX how to handle incoming calls from your IPComms trunk and how to send outbound calls through it.

Create an Outbound Route

• 1. Navigate to Connectivity > Outbound Routes
• 2. Click Add Outbound Route
• 3. Set Route Name to "IPComms_Outbound"
• 4. Under Trunk Sequence, select your "IPComms" trunk
• 5. Under Dial Patterns, add these patterns:

Create an Inbound Route

• 1. Navigate to Connectivity > Inbound Routes
• 2. Click Add Inbound Route
• 3. Set DID Number to your IPComms phone number (e.g., 12025551234)
• 4. Set Description to "Main Line"
• 5. Under Set Destination, choose where to send the call (e.g., Extension 1001)

Click Submit and then Apply Config to activate your routes.

9. Troubleshooting

If you encounter issues during or after installation, use these solutions for the most common FreePBX problems.

Apache Not Loading FreePBX

If you see the default Apache page instead of FreePBX:

# Check if the FreePBX config is enabled
sudo ls /etc/apache2/sites-enabled/
# Disable the default site and enable FreePBX
sudo a2dissite 000-default.conf
sudo systemctl restart apache2
# Check Apache error logs
sudo tail -50 /var/log/apache2/error.log

FreePBX GUI Errors

If the GUI shows blank pages or PHP errors:

# Check PHP version and modules
php -v
php -m | grep -i mysql
# Verify PHP is properly configured for Apache
sudo a2enmod php8.2
sudo systemctl restart apache2
# Check FreePBX file permissions
sudo -u asterisk fwconsole chown

Module Install Failures

# Check module status
sudo -u asterisk fwconsole ma list
# Force upgrade all modules
sudo -u asterisk fwconsole ma upgradeall
# Refresh module signatures
sudo -u asterisk fwconsole ma refreshsignatures
# If a specific module fails, reinstall it
sudo -u asterisk fwconsole ma uninstall core
sudo -u asterisk fwconsole ma install core

Trunk Registration Issues

# Check trunk registration from Asterisk CLI
sudo asterisk -rx "pjsip show registrations"
# Enable SIP debug logging
sudo asterisk -rx "pjsip set logger on"
# Check FreePBX system logs
sudo tail -f /var/log/asterisk/full