VM Setup

This section describes how to setup a Virtual Machine to host a Web API Bridge. It assumes that the read has knowledge of virtual machines and is familiar with setting them up. These instructions describe setting up the Web API Bridge using Ubuntu 16.04 LTS, but should be applicable to most other distributions of GNU/Linux.

Creating a Ubuntu 16.04 LTS VM

During installation of Ubuntu select the "LAMP server" option, which will install Apache, MySQL, and PHP. The Web API Bridge itself is currently written in PHP, and runs on top of the Apache web server. As it communicates with MySQL servers, either on the localhost or on other hosts, it needs to use the PHP-MySQL library.

An image of the Ubuntu installation software selection screen.

Setting up your host computer's hosts file

Once Ubuntu is installed you should be able to edit your computers 'hosts' file and associated the IP address of the VM with a domain name such as 'webapibridge.local'.

Navigating to this address in a browser should bring up the default Apache page.

The default Apache webserver screen.

Inital configuration of Apache on the VM

Next the Apache configuration needs to be slightly modified – this is mainly to allow the Web API Bridge to listen as the default web server on port 8080. This is so that it can co-exist peacefully with any other websites you may be running. Additionaly, several modules need to be enabled.

First, edit the 'ports.conf' file, and add another line that sayes 'Listen 8080'.

sudo nano /etc/apache2/ports.conf
Editing the ports.conf configuration file.

Next, run the 'a2enmod' command to enable the following modules:

sudo a2enmod rewrite
sudo a2enmod headers

Downloading and configuring the Web API Bridge

Next navigate to the directory that your want to contain the Web API Bridge software. As it is the default web directory on Ubuntu these instructions will assume installation in a sub-directory of '/var/www/'. Below we set the environment variable 'DOCUMENT_ROOT' to '/var/www/WEB_API_BRIDGE', which allows the instructions to just reference that variable, which you may set to what ever you wish. However, do not that if you want to place the directory outside of the standard directories, such as '/var/www/', you will need to edit the '/etc/apache2/apache2.conf' file.

DOCUMENT_ROOT=/var/www/WEB_API_BRIDGE

Once downloaded, check that the MD5 sum of the package matches the following value:

sudo mkdir $DOCUMENT_ROOT
cd $DOCUMENT_ROOT
sudo wget http://www.webapibridge.org/client/webapibridge/resources/downloads/WebAPIBridge-1.0.5.tar.bz2
md5sum WebAPIBridge-1.0.5.tar.bz2

The 'md5sum' command will return the checksum and the name of the file:

767235ff974a924e1ef7b8bd0bd9030c WebAPIBridge-1.0.5.tar.bz2

Next unpack the archive, and configure the Web API Bridge.

sudo tar jxvf WebAPIBridge-1.0.5.tar.bz2 --no-same-owner
cd WebAPIBridge/1.0.5/webapibridge/configuration
sudo cp configuration.template.php configuration.php
sudo sed -i "s|%DOCUMENT_ROOT%|$DOCUMENT_ROOT|g" configuration.php
sudo cp apache2/WEB_API_BRIDGE.conf /etc/apache2/sites-available/WEB_API_BRIDGE.conf
sudo sed -i "s|%DOCUMENT_ROOT%|$DOCUMENT_ROOT|g" /etc/apache2/sites-available/WEB_API_BRIDGE.conf
sudo ln -sf ../sites-available/WEB_API_BRIDGE.conf /etc/apache2/sites-enabled/WEB_API_BRIDGE.conf

Finally, you need to setup a symbolic link that controls the active version of the software, as well as a link -- using that link -- to the index.php file.

cd $DOCUMENT_ROOT/WebAPIBridge
sudo ln -sf 1.0.5 latest
cd $DOCUMENT_ROOT
sudo ln -sf WebAPIBridge/latest/webapibridge/bin/index.php .

Now restart Apache2.

sudo service apache2 restart

If you navigate to port 8080 using the name you associated with the IP address of the VM, it should show the PHP info page.

Editing the ports.conf configuration file.

You should also be able to view the log for the Web API Bridge using:

tail -f /var/log/apache2/webapibridge.log
[Fri Feb 24 14:30:43.174253 2017] [:error] [pid 2652] [client 192.168.175.1:52139] PHP Warning: mysqli::real_connect(): (HY000/1045): Access denied for user 'public'@'localhost' (using password: YES) in /var/www/WEB_API_BRIDGE/WebAPIBridge/1.0.5/webapibridge/dep/libpagecentric/source/php/replicantdb/ReplicantDB.php on line 472 [Fri Feb 24 14:30:43.174476 2017] [:error] [pid 2652] [client 192.168.175.1:52139] Could not connect to database on localhost (DB_HOSTNAME):

As you can see, it is trying to connect to the local MySQL database and failing because we have not yet configured that yet. Login to mysql and grant the 'public'@'localhost' account the EXECUTE permission on any databases to be used with the Web API Bridge.

mysql -u root -p
Enter password:
mysql> GRANT EXECUTE ON *.* TO 'public'@'localhost' IDENTIFIED BY 'public';

Now the log will say that it can't find a database for your domain.

tail -f /var/log/apache2/webapibridge.log
[Fri Feb 24 14:56:23.801652 2017] [:error] [pid 2650] [client 192.168.175.1:52290] Could not find database for: webapibridge

Continue reading in the next section - 'Using the Web API Bridge' - to learn how to setup a simple database.