Setup:Production/Installing on your own server

From Cerb Wiki
Jump to: navigation, search

The official version of this information is available in the Cerb User Guide:
http://cerberusweb.com/book/#installation

Introduction

Important Note

If you don't have direct control over your server configuration, we STRONGLY urge you to consider "software-as-a-service". E-mail management is a major component for any online organization and it can be quite technical. While the service model is based on a monthly fee rather than a one-time licensing cost, you're not really paying for the same software over and over -- you are paying for a partner who will keep the technical obstacles and maintenance out of your way so you can focus on what you're best at.

Otherwise, if you're ready to jump through a couple technical hoops we'll do our best to get Cerberus Helpdesk 5.0 running in your environment. Let's begin!

Additionally, if you are installing on the root of a subdomain (http://cerb5.xyz.com), please take note that you may encounter problems when trying to start the installation process. A fast solution to this is to rename the .htaccess file (to .htaccess.backup) and to start the installation process through (http://xzy.com/cerb5). Once the installation is successful, rename the .htaccess and access your Cerb5 installation via (http://cerb5.xyz.com). If you have setup any cron processes to poll your emails, remember to change the cron process wget url too.

PHP Environment

Cerberus Helpdesk 5.0 requires several specialized PHP extensions to provide a better balance of speed, resource usage and power.

WARNING: Cerberus 5.0 requires PHP 5.2+ and MySQL 5.0+.

These new requirements have drastically improved the focus and performance of the project. However, if you don't have access to modify your current application hosting environment you will likely run into trouble or dead-ends.

  • Rename the extension to .php and save the file in your web-path.
  • Access the proper URL on your server to display the cerb4-servercheck.php page.
  • Make sure APC is disabled or not in use. APC has know issues with Cerberus and many other PHP projects. Xcache works well without the problems APC seems to generate.

Acquiring the Files

Assuming the Server Checker tool above passed all tests, it's time to download the Cerberus Helpdesk files.

Using Git (recommended)

Git is the recommended method for obtaining the project files, since it allows for painless software updates and the preservation of any custom modifications you make. It is highly recommended that you do whatever you have to do to use this delivery method.

Git is usually available from the package manager for major Linux distributions. For Windows Servers the best option is TortoiseGIT.

Git Details:

Example usage:

git clone "git://github.com/wgm/cerb5.git" cerb5

Be sure to checkout or copy the files into the appropriate web-path and domain name.

Using Subversion

Subversion is usually available from the package manager for major Linux distributions. For Windows Servers the best option is TortoiseSVN.

SVN Details:

Example usage:

svn checkout "https://github.com/wgm/cerb5.git/branches/stable" cerb5

Be sure to checkout or copy the files into the appropriate web-path and domain name.

Downloading a ZIP File

A .zip file is provided for situations where Subversion isn't available. This method will make your future software upgrades a bigger hassle than they would be with Subversion.

Preparing the Files

Unix-based Servers

On Unix-based servers (e.g., Linux, BSD, MacOSX, Solaris) you'll need to set the proper ownership and permissions on the files.

From the command-line in the cerb5/ directory you downloaded above (replace apache with your appropriate Apache user and group):

chown -R apache:apache *
chmod -R 0774 storage/

You can check your httpd.conf file for the appropriate 'User' and 'Group' settings.

On Debian systems the Apache user and group is: www-data:www-data

Windows-based Servers

  • Depending on your server configuration you may need to change the owner of the cerb5/ directory (and contents) to your IIS user.
  • Make sure the cerb4/storage directory is writable by the IIS user.

Creating a Database

You need to create a new database and login for your helpdesk data.

MySQL Console

mysql> CREATE DATABASE cerb5 CHARACTER SET utf8 COLLATE utf8_general_ci;
mysql> GRANT ALL PRIVILEGES ON cerb5.* TO user@localhost IDENTIFIED BY 'password'; 

Use your own values for cerb5, user@localhost and password.

Running the Installer

At this point you should be able to run the Cerberus Helpdesk 5.0 Installer by opening your browser to http://www.example.com/cerb5/

The guided installer will walk you through the process of configuring your helpdesk for use.

  • If you get redirected to install.com try using http://helpdesk.example.com/install/index.php instead of http://helpdesk.example.com/.
  • At the end of the installer If you see a message about "finishing the upgrade", go ahead and do so. If you then get a message about an unauthorized IP, inside the cerb5/framework.config.php (literally in your directory) add the reported address next to AUTHORIZED_IPS_DEFAULTS and refresh the browser.

Downloading E-mail

To get your mail into the Helpdesk you have to do two things: add a POP3/IMAP account and configure a cron job to download the mail periodically in the background. The entire process is explained here along with some words of caution regarding IMAP (the mail on the server is deleted).

Downloading real mail into your Helpdesk for the first time

Finishing Touches

Friendly URLS

If you're using Apache you can enable URL rewriting so the URLs created by Cerberus Helpdesk are much more user friendly.

  • Friendly URL: /display/FCX-12345-678
  • Unfriendly URL: /index.php?c=display&id=FCX-12345-678

This difference is entirely cosmetic.

From the cerb5/ directory:

  • Copy the .htaccess-dist file to .htaccess

If you run into any trouble simply delete the copied .htaccess file.

Friendly URLs on nginx

If you are using nginx the .htaccess file will not enable redirects. To have it work correctly, just add the following directives in your server config

       location ~ ^/cerb5/(api|features|libs|storage)/ {
           return 403;
       }
       location / {
           if (!-e $request_filename) { 
               rewrite ^/(.+)$ /index.php/$1 last;
           }
       }
       location ~ ^(.+.php)(.*)$ {
           fastcgi_split_path_info ^(.+.php)(.*)$;
           fastcgi_pass 127.0.0.1:9000;
           fastcgi_index  index.php;
           fastcgi_param  SCRIPT_FILENAME  /var/www$fastcgi_script_name;
           fastcgi_param  PATH_INFO        $fastcgi_path_info;
           include fastcgi_params;
           fastcgi_param  QUERY_STRING     $query_string;
           fastcgi_param  REQUEST_METHOD   $request_method;
           fastcgi_param  CONTENT_TYPE     $content_type;
           fastcgi_param  CONTENT_LENGTH   $content_length;
           fastcgi_intercept_errors        on;
           fastcgi_ignore_client_abort     off;
           fastcgi_connect_timeout 60;
           fastcgi_send_timeout 180;
           fastcgi_read_timeout 180;
           fastcgi_buffer_size 128k;
           fastcgi_buffers 4 256k;
           fastcgi_busy_buffers_size 256k;
           fastcgi_temp_file_write_size 256k;
       }  

These assume that Cerb5 is installed in the root of the server. Otherwise just prepend the path to Cerb5 (for example rewrite ^/support/cerb5/index.php/.*$) /support/cerb5/index.php last;) It would also be a good idea to create a blank .htaccess file so Cerb5 knows to generate Friendly URLs.

Congratulations!

Welcome to the Cerberus Helpdesk community!


To migrate your Cerberus 2.7 or Cerberus 3.6 content to Cerb4 first, visit ImpEx:Cerb3Export.

To walk-through a step-by-step example of use with explanations, visit Quick Start.

To set up a support portal on your website, visit Support Center.