How to deploy Morfik XApps as a native Apache module under Linux

In my last blog we went through commissioning and connecting to a Linux virtual machine on the Amazon cloud. Today we’ll look at running a Morfik XApp as an Apache module on that system.

After commissioning the server we used Putty for Windows to connect to the server and we got to the point where we made a secure connection to the server and logged in as the root user.

Since we are going to deploy the XApps as an Apache module we need to make sure an Apache 2 web server is installed and running on the system.

To install the Apache web server we use the “yum” command. Yum is an automatic updater and package installer/uninstaller for systems using rpm packages.

To see if Apache is already installed on our system we issue the following command at the command prompt :

[root@ip-10-160-83-1 /]# yum list installed *httpd*

As you can see from the screen shot below, in this case the only item installed on this system which includes httpd in its name is “httpd-tools.i386”.

Next we look at what is available in relation to the Apache web server:

[root@ip-10-160-83-1 /]# yum list *httpd*

From this list, for Morfik XApps we need only the Apache web server, httpd.i386 package.

[root@ip-10-160-83-1 /]# yum install httpd.i386

If installation was successful you should see a few httpd processes running using this command:

[root@ip-10-160-83-1 /]# ps –e | grep httpd

Or

[root@ip-10-160-83-1 /]# top | grep httpd

If httpd processes are running then you can go to one of the browsers on your local system and type the IP address of your cloud server. If everything was set up correctly you should see the default test page of Apache on your server.

Before going further I would like to introduce another utility program, WinSCP, which makes life much easier when uploading and downloading from the server to your local windows PC. This utility also provides a simple way to edit text files, which will come in handy when we need to change the Apache configuration file.

After downloading and installing WinSCP, we need to use the same private key which we are using for Putty to connect to the server, as shown below.

We also need to install the Firebird database server. Life would have been much easier if Firebird was in the list of the yum repository for this system, but unfortunately it is not and what I’m going to do is to download the firebird server to my system and use WinSCP to upload it to the server. We also need to install libstdc++ version 5 before installing Firebird, as this is a pre-requisite for Firebird.

Since working with WinSCP is as easy as dragging and dropping files in a GUI style, I won’t go into that and will assume you can upload the files easily to the server.

Now we go back to our Putty and if not connected we make a connection to our server.

First we install the libstdc++ package and then Firebird as follows:

[root@ip-10-160-83-1 /]#rpm -ivh libstdc++5.0-3.3.3-62745cl.i386.rpm

[root@ip-10-160-83-1 /]#rpm -ivh FirebirdSS-2.1.3.18185-0.i686.rpm

We need to upload MFKUDF.dll to the udf folder of Firebird ( /opt/firebird/UDF/ ) and set the permission to:

[root@ip-10-160-83-1 /]#chmod 654 /opt/firebird/UDF/MFKUDF.dll

Another file used by Morfik XApps is libhttpd.so which needs to be uploaded to the /usr/lib folder. We also change the permission for this file:

[root@ip-10-160-83-1 /]#chmod 755 /usr/lib/libhttpd.so

A little explanation about permission settings on Linux might help to decipher the above commands. As far as I know, in Linux there are 3 types of users and there are at least two types of objects in the file system and then there are 3 types of access to each object.

Users Types:  (User\Owner) – (Group) – (Other)
Objects: Files, Directories, etc.
Permission or Access: Read, Write, Execute
“chmod” change object permission
“chown” change owner of an object
6-5-4 : First digit, User (allow read and write) – Second digit, Group (allow read and execute) – Third digit, Other(allow read)
7-5-5 : First digit, User (allow full access) – Second digit, Group (allow read and execute) – Third digit, Other (allow read and execute)

Below is a basic map of Octal numbers and corresponding permission rights:

0              All types of access are denied
1              Execute access is allowed only
2              Write access is allowed only
3              Write and execute access are allowed
4              Read access is allowed only
5              Read and execute access are allowed
6              Read and write access are allowed
7              Everything is allowed

We also should make sure Firebird permissions are set correctly by executing the two commands below:

[root@ip-10-160-83-1 /]#chmod 775 /opt/firebird
[root@ip-10-160-83-1 /]#chown firebird:firebird /opt/firebird

(Note: the second command changes the ownership of the Firebird folder to Firebird user and group.)

We should also change the default password for sysdba to match our project’s (application) database sysdba password.

For the purpose of this exercise we will use “masterkey” as the password for our Firebird sysdba and make sure both our project and the Firebird database we installed on the server use this password.

To change the password for the sysdba of the Firebird on our server we use Putty to connect to the server and do as follows:

To see what is the current password of our Firebird sysdba on the server:

[root@ip-10-160-83-1 /]# cat /opt/firebird/SYSDBA.password

To change the password we need to execute the below script file, enter the current password and then set the new password.

[root@ip-10-160-83-1 /]# ./opt/firebird/bin/changeDBAPassword.sh

It may not be required at this stage, but I will restart the Firebird server to make sure the changes have taken effect. Even if this is not required, we take a look at how to do it anyway.

To stop and start the Firebird server we issue the following command using our Putty.

[root@ip-10-160-83-1 /]# /opt/firebird/bin/fbmgr -shut -user sysdba -pass masterkey
[root@ip-10-160-83-1 /]# /opt/firebird/bin/fbmgr -start  -forever

Now we can go to the Morfik application on our local system and compile the project which we want to deploy on our cloud server as an Apache module.

For this blog I am going to use the BookCollector project, a project that ships with all versions of Morfik software including the demo version.

We now run Morfik IDE and load the BookCollector sample project. The main thing to remember is to check the options for the project to make sure the target platform, the port number and the sysdba password are set correctly.

To check the options for the project click on the “Project” menu tab and click on the “Project Options” short cut on the right hand side of the menu ribbon.

Click on “Server” on the left hand side menu and select the “Apache Plug-in XApp” from “Binary Kind” dropdown box.

Set “HTTP Port” to 80 and “HTTPS Port” to 443 and change the “Password” for sysdba to “masterkey”.

Click on “Compiler” on the left hand side menu and change “Target Platform” to “Linux, Intel x86” then click the OK button to apply the changes and close the dialog box.

From the main menu select the “Home” tab and click on the “Compile” shortcut button on the left hand side of the menu ribbon.

When compilation finishes you should see libBookCollector.so,  in the same folder as your project. As you know Linux is a case sensitive OS so always be mindful of this when working in the Linux environment.

We can use WinSCP to create a folder called BookCollector on the root of our server and then transfer our application files and folders (_BookCollectorResources, libBookCollector.so, BookCollector.Mxr and BookCollector.Mxd ) to this folder on the server (If you want a faster upload you could compress them).

After completing the file transfer we also need to set the permissions for these folder and files as follows:

[root@ip-10-160-83-1 /]# chown root.firebird /BookCollector
[root@ip-10-160-83-1 /]# chmod 764 /BookCollector/BookCollector.Mxd
[root@ip-10-160-83-1 /]# chmod 744 / BookCollector /BookCollector.Mxr
[root@ip-10-160-83-1 /]# chmod 755 / BookCollector /libBookCollector.so

For the system to know where to look for the application resources, we need to create a file “/etc/ApplicationName.ini” with the following content:

[Configuration]
RootDirectory=/ApplicationFolder

So in our case we need to create a file called BookCollector.ini with the following entries, and place it on the /etc folder.

[Configuration]
RootDirectory=/BookCollector

Before we can start running our application on the server we need to change http.conf, the Apache configuration file, so that Apache will load our application module and know its location.

Use WinSCP to edit and change the /etc/httpd/conf/http.conf file. We need to add the line below (without quotation marks) to the bottom of the Add Module section of the Apache configuration file.

“LoadModule bookcollector_module /BookCollector/libBookCollector.so”

We also need to add the following section to the bottom of the config file.

<Location /bookcollector>
Options Indexes FollowSymLinks MultiViews +ExecCGI
SetHandler bookcollector-handler
Order deny,allow
Allow from all
</location>

Important: Please note the use of upper case and lower case letters in the above configuration directives which we added to the Apache config file. If you want your application to work you need to follow exactly the same pattern as far as case sensitivity of letters is concerned.

Now we are ready to start the application on the server. To do that we only need to restart the Apache web server. Although there is a restart command for doing this I prefer to first stop the Apache server and then start it again as follows:

[root@ip-10-160-83-1 /]# service httpd stop
[root@ip-10-160-83-1 /]# service httpd start

If everything went well you should see something like the screen shot below.

If not, the messages during startup should give you a clue as to what could be wrong. If there is a problem and you need further clues you can always use “strace” – a utility which traces problems at the startup of applications.

In this case there was no problem so we can test to see if the application is working as it should. All we need to do now is to start a browser on our local system and try to access our application using an address like this:

http://the.ip.of.the.server/bookcollector

Please note that this feature of Morfik, i.e. creating the XApps as native modules for Apache on the Linux system, is new and is still in pre-release version.

5 Responses to “How to deploy Morfik XApps as a native Apache module under Linux”

October 23rd, 2017
Alan Sawyer says:

If I am not using any Firebird Databases, do I still need to install Firebird on my server?
I am planning on using MySQL.

vic says:

suppose to read
<VirtualHost *:80>
SuexecUserGroup “#504” “#505”
ServerName yourdomain.com
ServerAlias http://www.yourdomain.com
DocumentRoot /home/yourdomain/public_html
ErrorLog /home/yourdomain/logs/error_log
CustomLog /home/yourdomainlogs/access_log combined
<Directory /home/yourdomain/public_html>
Options Indexes FollowSymLinks MultiViews +ExecCGI
SetHandler yourdomain-handler
Order deny,allow
Allow from all
</Directory>
</VirtualHost>

vic says:

Cent 5.4
Slight modification to allow a fully qualified domain to work. You will have to add the log dirs

1. Of course, set up DNS for yourdomain.com to point to your server
2.Follow all instruction above until the /etc/application.ini section.
3. /etc/yourdomain.ini
[Configuration]
RootDirectory=/home/yourdomain/public_html
4. httpd.conf

SuexecUserGroup “#504” “#505” #not sure if this is needed, webmin puts this in
ServerName yourdomain.com
ServerAlias http://www.yourdomain.com
DocumentRoot /home/yourdomain/public_html
ErrorLog /home/yourdomain/logs/error_log
CustomLog /home/yourdomainlogs/access_log combined

Options Indexes FollowSymLinks MultiViews +ExecCGI
SetHandler yourdomain-handler
Order deny,allow
Allow from all

Mainly just slight modification of using the virtualhost directive instead of the location directive so http://www.yourdomain.com will work instead of using ip.of.your.server./yourdomain

olivier says:

Hi,
first thanks for this guide.

I’ve try to follow this guide but I get an eror when restarting Apache :

# 00000844:B78B86F0 XApp Starting…
# 00000844:B78B86F0 Loading Application Resources (MXR)…
# 00000844:B78B86F0 _Exception at $155FB79, EBP = $BF83ADEC;EIB_Error raised with message ‘InterBase Client GDS32.DLL is not installed’
# 00000844:B78B86F0 Unable to connect to the Firebird database server; the XApp will now terminate

Any clue on this error ?

Alex says:

Great! It will be nice to describe how to deploy Morfik XApp on Mac (through native Apache or XAMPP or MAMP)

Thanks

Leave a Reply

Fields marked by an asterisk (*) are required.