Goal: Install and configure Kayako Fusion v4 on Ubuntu 10.04 LTS

Requirements: Ubuntu 10.04 LTS, PHP 5.2.8+, MySQL 5.0+, ionCube Decoder, Apache, Nano (or other editor), wget

Assumptions: Clean server, latest updates, shell access.

I have recently been tasked with setting up multiple in house installations of Kayako Help Desk, arguably the best web based ticket support system available. I basically worked from the installation notes and have since streamlined the installation process and hopefully made things easier for you to follow along. As you may already know, Kayako employs a certain degree of encryption against its source, even with the purchased version. In this instance, I have gone with the ionCube version.

Prerequisites

Installing Apache

I am assuming that you are beginning with a clean installation, however, if you installed the LAMP stack during the installation of Ubuntu then you can skip to Installing ionCube.

First we need to install the latest version of Apache.

sudo apt-get install apache2

Once installed, check that everything works by pointing your browser to the server in question, you should see the default, “It Works” page appear.

Installing PHP

Next we need to install PHP and the Apache PHP library.

sudo apt-get install php5 libapache2-mod-php5

You may need to reload Apache for it to learn of PHP’s presence.

sudo service apache2 reload

Now lets check if PHP is installed correctly. Create a php file called “test.php” in /var/www/ with the contents:

<?php phpinfo(); ?>

Point your browser to ths file, you should get a long listing of all your PHP settings.

Installing MySQL

Lets install the latest version of MySQL.

sudo apt-get install mysql-server

During installation it may prompt you for the password for the ‘root’ user, if so make sure to remember it. If not, you can do it afterwards using the following commands.

mysql -u root

mysql> SET PASSWORD FOR ‘root’@’localhost’ = PASSWORD(‘yourpassword’)

Installing ionCube

Kayako protects its code by encrypting its source files. For your web browsers to be able to interperet Kayakos files it needs to be able to decode the files on the fly. To do this, we are going to use ionCube Decoder.

If you havent already got wget installed, do so now.

sudo apt-get install wget

I will create a new directory for downloads in /home.

sudo mkdir /home/downloads

cd /home/downloads

Lets download the latest release of ionCube decoder into the current working directory (/home/downloads).

sudo wget http://downloads2.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz

Next we need to extract the tar.

tar -zxvf ioncube_loaders_lin_x86-64.tar.gz

You should be left with a folder called ioncube in the downloads directory.

Luckily for us, ionCube ships with a installation wizard in the form of a PHP file located in the ioncube folder. Lets move this file to the root of our web server.

sudo mv /home/downloads/ioncube/loader-wizard.php /var/www/loader-wizard.php

Open this page in your web browser. It will kick off the installation and configuration of ioncube and highlight any potential issues it has along the way. In my case, I have an error complaining about missing necessary zend_extensions with some helpful instructions below on how to correct this issue. Its asking me to move the files we just downloaded into /usr/lib/php5/20090626 as well as saving a 20ioncube.ini file in /etc/php5/apache2/conf.d. Keep this browser page open.

First, move the contents of the ioncube directory to /usr/lib/php5/20090626

sudo mv /home/downloads/ioncube/* /usr/lib/php5/20090626

Next, create the 20ioncube.ini file in /etc/php5/apache2/conf.d

cd /etc/php5/apache2/conf.d

sudo nano

I will enter the contents on the 20ioncube.ini file from the ioncube loader page.

zend_extension = /usr/lib/php5/20090626/ioncube_loader_lin_5.3.so

Make sure to save this file as “20ioncube.ini”

Lets reload Apache now.

sudo service apache2 reload

Go back to the ioncube loader wizard page and hit the link to reload the wizard. “Click here to test the loader”.

Once you do you should get a message stating:

Finally, we should remove the loader-wizard.php file.

sudo rm -f /var/www/loader-wizard.php

Lets just double check that everything is as it should be. Go back to your test.php file in a browser and do a quick search for ioncube. You should see a search result in the “Additional .ini files parsed” section and at the bottom of that table, some copyright blurb for ioncube.

 

PHP Settings and Modules

PHP Settings

In order for Kayako to work as expected, the following PHP settings need to be set:

These settings are configured in the php.ini file.

sudo nano /etc/php5/apache2/php.ini

Using nano’s “where is” function, edit and save the above settings.

Reload apache2

sudo service apache2 reload

PHP Modules

The following modules are required for Kayako to operate: To check whether you have these already, check the test.php file we made earlier when installing PHP.

Lets reload Apache for peace of mind.

sudo service apache2 reload

Apache Settings

Make sure that mod_security is disabled. To check browse to /etc/apache2/mods-enabled and make sure mod_security is not listed.

MySQL Settings

Make sure sql_mode is set to: not strict. By default no mode is set which is fine.

PHP Cache Accelerator

Kayako also recommended that you install a php cache accelerator to improve performance. However, I didn’t really notice any difference in performance for my installations. However, they recommended you install xcache.

 

Installing Kayako Help Desk

Get the latest release

Download the latest release of Kayako Fusion (ionCube version) along with your Key file from the my.kayako.com orders area. By your preferred method, transfer the installation tar file and key.php to your server. In my case, I have an internal FTP server which I hosted the files on, then used wget to download the files to the server. For the time being, I downloaded the files to my /home/downloads directory.

Extract the contents of the tar.

sudo tar -zxvf fusion_stable_ioncubeopen-4-xx-xxx.tar.gz

You should now have a directory named fusion_stable_ioncubeopen-4-xx-xxx, or something similar. If your working on the trial version then it will likely be ioncubeclosed or something like that. Don’t worry, it makes no difference.

In this directory should be two folders, apps and upload. We need to move the contents of upload to the root of our web server, in my case, /var/www/

sudo mv /home/downloads/fusion-stable-ioncubeopen-4-xx-xxx/upload/* /var/www

Creating the MySQL Database

Lets create the database to be used by Kayako.

mysql -u root -p

Enter the root password you entered earlier.

From the mysql> prompt, 

CREATE DATABASE kayako_fusion;

USE kayako_fusion;

ALTER DATABASE kayako_fusion DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;

GRANT ALL PRIVILEGES ON kayako_fusion.* TO ‘kayako_user’@’localhost’ IDENTIFIED by ‘mypassword’;

Config File Changes

To protect the main configuration file from being overwritten it was named config.php.new. We need to change this to config.php before the installation can continue.

sudo mv /var/www/__swift/config/config.php.new /var/www/__swift/config/config.php

Next, the config.php file needs to be updated with our database information from the previous step.

sudo nano /var/www/__swift/config/config.php

Save this changes. The rest of the settings can be ignored.

Setting File Permissions

Kayako needs full permissions to a subset of folders within its file structure. Namely, “__swift/files”, “__swift/cache” and “__swift/geoip”.

Lets change into the __swift directory before performing the changes.

cd /var/www/__swift

sudo chmod 777 files cache geoip

Key File

Lets move the key.php file that we downloaded to the server earlier into the kayako root directory.

sudo mv /home/downloads/key.php /var/www/key.php

Final Setup

Finally we get to run the Kayako setup wizard. Point your browser to http://servername/setup.

Run through the setup wizard reading and accepting the licence agreement. The next page will check your system requirements, and if you have done everything right so far, everything should be OK.

Fill out your admin details on the next page. The install will run through and warn you about removing the setup directory. Lets do this now.

sudo rm -rf /var/www/setup

Kayako Help Desk Fusion v4 should now be installed and ready to go. Hope this has helped.