papal.ringfree.biz is a complete rewrite of the previous papalmainframe.ringfree.biz 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.
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 papal.ringfree.biz 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.
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
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
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
email@example.com 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.
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 https://github.com/ringfreejohn/papalmainframe.git
This will install Papal into the
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:
CREATE DATABASE papal;
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.
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
* * * * * /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
sudo wget https://www.dropbox.com/s/7t4948s3o440l9h/VSXi_WS_Client.jar
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
firstname.lastname@example.org, change the
/var/www/html/papalmainframe, and insert the following within the
Options Indexes FollowSymLinks MultiViews
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