Overview
Running Kayako Classic on your own server gives you full control over your helpdesk, but also means you're responsible for maintaining it and your server as you go along.
In this article, we'll walk you through the steps necessary for installing Kayako Classic on your own server.
Prerequisite
- Before installing Kayako Classic on your server, you'll need to check to make sure your server environment meets all of the requirements.
- If you need to download the installation files and the 'key.php' file, you need access to My.kayako.com which requires the registered billing email address on the license.
- You'll need root-level permissions to set up a new database on your server.
- You'll need full access to your server to install the Kayako files.
Solution
The installation process requires several steps:
- Downloading, unpacking, and uploading the product files
- Creating a MySQL database
- Renaming and editing the 'config.php.new' file
- Download the 'key.php' file and upload it to your root directory
- Setting folder permissions
- Installing the Kayako Classic helpdesk
- Removing the '/setup' directory
Go through each of the steps in detail as outlined below.
A. Downloading, unpacking, and uploading the product files
The first part of the installation process is to download the product files, extract them on your local machine, and upload them from there to your server.
The steps on how to download the installation files can be found in the Downloading the Files Needed for Installing or Upgrading Kayako Classic article.
NOTES:
- The extracted folder contains a sub-folder named 'upload', which contains all the files required to install your helpdesk.
- In the root directory of your web server, create a new folder for your Kayako Classic installation to live in and name it, for example, 'support'.
- Using either the command line or an FTP client of your choice, upload all of the files from the 'upload' folder into your newly created 'support' folder.NOTE: If you're using an FTP client, make sure you're uploading using binary mode.
Now that the product files are up in your web server, it's time to do the setup on the backend.
B. Creating a MySQL database
Your next step is to create a new MySQL database on your server that Kayako Classic can use.
NOTE: You'll need root-level permissions to set up a new database on your server.
- If you're using the command line, you can use the following commands to create the database and user credentials you need.
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 'password_of_your_choice';
NOTE: You'll want to add an actual password in place of 'password_of_your_choice' - If you're using phpMyAdmin or another graphical server configuration tool, you'll need to use their create database function to do the following:
- Create a new database called
kayako_fusion
, set to useutf8_unicode_ci
for its table collation. - Add a new user to the database called
kayako_user
with a password of your choice. - Specify
localhost
when prompted for a hostname - Grant all privileges to that user.
- Create a new database called
C. Renaming and editing the 'config.php.new' file
Before you can press the install button, you'll need to make changes to the 'config.php.new' file you've uploaded to your server.
- Renaming the 'config.php.new' file
To avoid accidental overwriting of 'config.php' which is located in '__swift/config/
' and contains important data, the default name for the file is 'config.php.new'. You'll need to rename it to 'config.php' before continuing. - Editing the 'config.php' file
The 'config.php' file must be manually edited for the configuration of the helpdesk's database connection.- The following variables in this file need to be edited:
$_DB["hostname"]
– Unless you have supplied a different hostname when creating your database, this variable should be set to 'localhost
'.$_DB["username"]
– Unless you have supplied a different user name when creating your database, this variable should be set to 'kayako_user
'.$_DB["password"]
– The variable should be set to the password that you supplied when setting up your database user.$_DB["name"]
- Unless you have supplied a different user name when creating your database, this variable should be set to 'kayako_fusion
'.- Here's an example of what the database details in your 'config.php' file should look like:
- The following variables in this file need to be edited:
/** * DATABASE HOSTNAME */ define('DB_HOSTNAME','localhost'); /** * DATABASE USERNAME */ define('DB_USERNAME','kayako_user'); /** * DATABASE PASSWORD */ define('DB_PASSWORD','support'); /** * DATABASE NAME */ define('DB_NAME','kayako_fusion');
NOTE: The rest of the settings in config.php should be left unchanged unless you are very familiar with the system. Once you're finished editing, save the file.
D. Download the 'key.php' file and upload it to your root directory
In order to activate the product, you'll need to download the key.php file corresponding to your registered domain from my.kayako.com
and upload it to the root folder in which the rest of the helpdesk files have been uploaded.
Please refer to the Downloading the key.php File for Kayako Account article if you haven't downloaded the 'key.php' file yet.
E. Setting folder permissions
Kayako needs write permissions, recursively, for five directories:
__swift/files
__swift/cache
__swift/geoip
__swift/logs
__swift/library
__apps
NOTE: Do not expose the “cache’ folder via the WebServer. Cache files include hashed passwords and might be used for a Rainbow Table attack.
Please choose the section below that corresponds to your operating system if you are unfamiliar with changing permissions on directories.
NOTE: It is usually possible to change directory permissions using an FTP client, but that is out of the scope of this document. Please consult your FTP client's documentation to learn how to change a directory's permissions using that tool.
Unix-based servers
On a Unix-based system, you'll use thechmod
command to set permissions to '777
' on the aforementioned directories:
From within the '__swift
' directory:
chmod-Rf 777 files cache geoip logs library
From within your Kayako Classic root directory (e.g. 'support'):
chmod-Rf 777 __apps
Windows-based servers
You'll need to make two adjustments if you're running Kayako Classic on a Windows-based server:
First, in the 'php.ini' file, you'll need to set the 'upload_tmp_dir
' to 'C:\Windows\TEMP
'.
Open up your 'php.ini' file, search for 'upload_tmp_dir
' and make sure it looks like this:
; Temporary directory for HTTP uploaded files (will use system default if not specified). upload_tmp_dir = C:\Windows\TEMP
Second, you'll need to set some specific folder permissions for Microsoft's IIS. For the user account of the application pool you're using for Kayako Classic, you'll need to grant full permissions to the following folders:
files
cache
geoip
logs
library
__apps
C:\Windows\TEMP
NOTE: It is recommended to keep the Application Pool Identity as the Application Pool itself, and add that identity to the list of authorized user accounts with full control permissions for the above folders. For more information about Application Pool Identities, refer to the IIS Documentation. Otherwise, you would usually need to add the 'IUSR' user account to the said list. For help with this, also refer to the IIS documentation.
F. Installing the Kayako Classic helpdesk
Now that your server is prepped, you're ready to start the installation itself:
- Open up your browser and go to your Kayako Classic directory '
/setup
', e.g.,https://www.yourdomain.com/support/setup
. You should see a page that looks like this: - Click the Setup button to begin the installation process.
- You'll be asked to agree to the license terms, and then the setup utility will check to make sure your server meets all the requirements. When it's done, click Next.
- Your next step is to create credentials for your default administrator account and supply some important details for your helpdesk. The Product URL should be the publicly accessible URL of your helpdesk, e.g., '
https://yourdomain.com/support/
'.- NOTE: You should only use the URL or domain that is registered on your account. Else, you will receive the error 'This domain name does not match the domain name in the license key file.' after the installation.
- When you've filled in the details, click Start Setup to begin the automated setup procedure.
- NOTE: The automated portion of the setup script may take quite some time. Do not interrupt it for any reason or your installation will be corrupt and you'll have to start over!
Once setup has completed, you'll see a success screen, and you'll only have one more step before you're ready to start using Kayako Classic!
G. Removing the '/setup' directory (IMPORTANT!)
Once the setup process has completed successfully, you'll need to remove the 'setup' directory or folder from your server, as a security measure. You will receive warnings if you do not delete it.
And that's it – congratulations on installing Kayako Classic Download!
Testing
Once the entire installation process has been completed, you can start using your Kayako Classic helpdesk. The final installation screen will provide you the URL for your admin panel, staff panel, and Help Center. Click these links and try logging in with your username and password.
Feel free to visit the Guide to Setting up Your Helpdesk article which contains a quick guide designed to help you get familiar with the basics of setting up the Kayako Helpdesk.