Platform and Deployment for is a complete rewrite of the previous PBX management interface. The current instance is deployed on a DigitalOcean virtual private server running Ubuntu 16.04. In this article I’m going to go over the existing Papal platform and then follow with deployment instructions.

Papal Platform

As mentioned, Papal is on a DigitalOcean VPS running Ubuntu 16.04. This is a “long term support” release with security updates guaranteed through at least April of 2021. The server is running Apache 2.4.18, PHP 7.0.4 and MariaDB 10.0.24.

Papal was built to target PHP version 7 so while it may run on some recent versions of PHP 5, it will not optimally do so. It should work with any reasonably recent version of MariaDB, MySQL, or Percona Server. For the sake of guaranteeing maximum compatibility across multiple data centers, please deploy additional instances using MariaDB 10.0 unless directed otherwise.

SSL for is provided by Let’s Encrypt with automatic renewal checking enabled once weekly. Papal requires SSL in order to function normally. While configuring the Let’s Encrypt client on new Papal instances, please select the “Secure” option to push all traffic through SSL.


Install Packages

On a fresh server, begin by installing Apache, PHP7, MariaDB, and a few other necessary packages to complete the LAMP configuration as we’ll need it. In Ubuntu 16.04, please run the following:

sudo apt install apache2 libapache2-mod-php7.0 php7.0 mariadb-server php7.0-xml php7.0-curl php7.0-zip php7.0-mcrypt php7.0-mysql git openjdk-8-jre-headless

Anything additional packages we need should be pulled in automatically as dependencies.

Configure the Apache User Environment

Various Linux distributions use different usernames for the Apache user. Red Hat and derivative distributions use the username apache whereas Debian and derivative distributions use the username www-data. Regardless of which, we’ll need to configure a few things for everything to work normally.

Begin by giving ownership of the user home directory to the user. In the case of Ubuntu 16.04, this is /var/www.

sudo chown -R www-data:www-data /var/www

Next, set up a log file for the Papal instance and give ownership of it to Apache:

sudo touch /var/log/papal.log && sudo chown www-data:www-data /var/log/papal.log

We’ll also be running a few commands as the Apache user. I find that it’s easiest to allow the Apache user to login rather than running each command with sudo, but your mileage may vary. To allow the Apache user to login, edit the file /etc/passwd as root and change the Apache user’s shell from /usr/sbin/nologin or /sbin/nologin to /bin/bash.

Setup Let’s Encrypt

DigitalOcean has a nice write up on setting up Let’s Encrypt on an Ubuntu server. You can find that write up here. Follow the steps exactly. When prompted, use the email address and select the Secure option to route all traffic through SSL. The configuration process should generate a file for an appropriate Apache VirtualHost. We’ll edit it later.

Retrieve Papal

As the Apache user (use either sudo -u www-data -i to login, or prefix your commands with sudo -u www-data) navigate to the /var/www/html directory and run the following command to pull down the source code:

git clone

This will install Papal into the /var/www/html/papalmainframe directory.

Set up the Database

MariaDB in most Linux distributions will prompt you to create a password for the root user during installation. This is not the case in Ubuntu 16.04. To set up a root password, please follow the instructions outlined in this article, beginning with the line:

Important Note: In Ubuntu 16.04/15.10/15.04, MariaDB won’t ask you to set root user password during installation.

Once your root password has been set, you’ll need to determine if this instance will use a remote database, a replicated database, or a new database. For a remote or replicated database, please consult with Kendall to set this up. For a new database, login as the root user and create a database and user specifically for our Papal instance:

GRANT ALL ON papal.* TO papal@localhost IDENTIFIED BY '<password>';

Note: Please replace <password> with a randomly generated password.

The Papal source code includes a base.sql file that will generate all the necessary tables and insert some preliminary data. You may import this file to the new database or get a database dump from another Papal instance to populate the new instance.

Configure Cron

Papal manages sessions and IP blocking from within the database and uses a Cron job for garbage collection rather than handling it internally. As the Apache user, add the following with crontab -e:

* * * * * /usr/bin/php -f /var/www/html/papalmainframe/cron.php &> /dev/null

Copy Files and Delete the Install Directory

Within Papal’s install directory located at /var/www/html/papalmainframe/install there are a few XML files necessary for proper communication with the Sansay SBCs. Copy these files to a system directory somewhere. No specific location is explicitly required for these files, however Papal will look for them in /etc/ringfree by default:

sudo mkdir /etc/ringfree
sudo cp /var/www/html/papalmainframe/install/*.xml /etc/ringfree/

A copy of the Sansay SOAP client will also need to be copied somewhere, preferably to the same directory, and made executable. The SOAP client is not included with the Papal source, however it can be retrieved with wget:

cd /etc/ringfree
sudo wget
sudo chmod +x VSXi_WS_Client.jar

Once done, please delete the /var/www/html/papalmainframe/install directory as leaving it would expose the SQL and XML files on the public internet. While there’s practically no chance that they would be identified and downloaded, much less used as an attack vector, the information there is proprietary to Ringfree and we don’t want it exposed.

Configure the Apache VirtualHost

Let’s Encrypt will generate and enable a new site file during setup. If originally using the default site on Ubuntu 16.04, the new file will be at /etc/apache2/sites-available/000-default-le-ssl.conf. Open the file as root, change the ServerAdmin to, change the DocumentRoot to /var/www/html/papalmainframe, and insert the following within the VirtualHost tags:

 <Directory />
     Options FollowSymLinks
     AllowOverride All

 <Directory /var/www/html/papalmainframe>
     Options Indexes FollowSymLinks MultiViews
     AllowOverride All
     Order allow,deny
     allow from all

Functionally this will allow .htaccess rewrites to work, which is necessary for Papal to work properly.

Adjust the Settings and Start Papal

As the Apache user, edit the Papal settings file at /var/www/html/papalmainframe/settings.php and adjust any necessary fields per your above configuration. This would include the database username, password, name, and host, the location of the log file, The location of the SBC SOAP client and template files, etc. The settings.php file is well commented so you shouldn’t have any issues identifying fields that require attention.

Unless I’ve missed something (and let me know if I have), Papal should now be ready to go. Ensure that mod_rewrite is enabled and restart Apache:

sudo a2enmod rewrite
sudo service apache2 restart