Setup:Production/Installing on a Slicehost virtual server

From Cerb Wiki
Jump to: navigation, search

This article assumes that:

  • You're installing on an Ubuntu 8.10 virtual dedicated server from Slicehost.
  • You are able to set up a DNS record to point to this new server instance.
  • You have an existing mail server for outgoing (SMTP) and incoming (POP3/IMAP) mail. If not, you can use Gmail.

Conventions:

  • When you see helpdesk.example.com, replace it with your own domain name.
  • Commands you type into the console will be prefixed with shell>


Introduction

At WebGroup Media we run a mix of physical and virtual servers from a variety of providers. We manage physical hardware for our Cerb4 On-Demand service and it's cost effective because of volume (spreading the cost over many customers sharing resources).

Occasionally we have customers whose requirements put them in a space between our On-Demand service (fully managed by us) and a dedicated server (fully managed by them). They're looking for something where they don't need to hassle with or invest in hardware, but still have enough access to a server to log in through the console, modify code, save and copy backups, connect to the database, and install tools. SliceHost fills this space perfectly by providing inexpensive virtual servers.

The advantage of a cheap virtual server is you can run an application with special installation requirements (such as PHP5/MySQL5) that are different than your existing infrastructure. It's also useful to allow a single application to live outside an intranet firewall. Each app can have its preferred environment and be self-contained.

The reasons SliceHost is great for Cerb4 hosting:

  • Inexpensive for low resource requirements
  • Full admin control of server
  • Web-based control panel
  • Choice of Linux-based distros
  • Near-instant setup
  • Dedicated IP and reverse-DNS
  • Automated backups
  • No hardware headaches
  • Easily upgrade server resources without moving

At the time of writing, the most cost-effective SliceHost plans are:

  • $20/mo: 256MB RAM, 10GB storage, 100GB bandwidth
  • $38/mo: 512MB RAM, 20GB storage, 200GB bandwidth
  • $70/mo: 1GB RAM, 40GB storage, 400GB bandwidth

After the $70/mo point, we feel you'll get more resources for your money using a different solution like Amazon EC2 or a dedicated server.

If you decide to sign up at SliceHost you can use this link and the Cerb4 project will get a couple bucks of account credit.

Setting up the new server

  • Create a new slice using Ubuntu 8.10
    Setting up a new slice
    Note: You should use a different machine name for your slice than the domain name you plan to use for your helpdesk, otherwise Apache will have trouble with the virtual host. You *can* use the same name but you'll need to edit Apache's /etc/apache2/apache2.conf file and set ServerName 127.0.0.1
  • You'll be given a new root password.
    Your new root password
  • Once your instance is created (usually about 1-2 minutes), log in as root using SSH and the new password given.
    Logging in through SSH

Update the package manager's cache: <geshi lang="text"> shell> apt-get update </geshi> Install Apache2, PHP5, MySQL5, and a few other tools: <geshi lang="text"> shell> apt-get install apache2 php5 php5-dev php5-imap php5-mysql php5-gd \

  php5-curl php-pear mysql-server subversion make

</geshi>

(you'll be prompted for a MySQL root password. Choose something you'll remember)

DNS

You'll need to create an "A" record in your DNS to point your preferred domain name to the IP of your slice. Instructions for this vary depending on your environment, and if you aren't your system administrator your best bet is to ask them for help with this step.

Getting the Cerb4 files

Create a directory that will store the Cerb4 project files: <geshi lang="text"> shell> mkdir -p /home/vhosts/helpdesk.example.com/httpdocs </geshi> Enter the new directory: <geshi lang="text"> shell> cd /home/vhosts/helpdesk.example.com/httpdocs </geshi> Checkout the latest stable Cerb4 branch as the 'admin' directory using Subversion: <geshi lang="text"> shell> svn co "http://svn.webgroupmedia.com/cerb4/branches/stable" admin </geshi> Set permissions: <geshi lang="text"> shell> chown -R www-data:www-data * </geshi> Make sure all directories are visible: <geshi lang="text"> shell> find * -type d -exec chmod 755 {} \; </geshi>

Enabling friendly URLs

Let's enable Apache2's mod_rewrite for friendlier URLs (/tickets/search vs. /index.php/tickets/search).

Change into the directory with Cerb4's project files: <geshi lang="text"> shell> cd /home/vhosts/helpdesk.example.com/httpdocs/admin </geshi> Enable mod_rewrite in Apache2: <geshi lang="text"> shell> a2enmod rewrite </geshi> Copy the .htaccess-dist template to .htaccess to enable it: <geshi lang="text"> shell> cp .htaccess-dist .htaccess </geshi>

Enabling 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.

Building MailParse

Cerb4 uses the MailParse PHP extension to parse e-mail efficiently. We'll need to build it since it's not part of the default PHP installation or in Ubuntu's package repository.

Install the mailparse extension using PHP's PECL tool: <geshi lang="text"> shell> pecl install mailparse </geshi> Create the mailparse.ini configuration file for PHP5: <geshi lang="text"> shell> vi /etc/php5/apache2/conf.d/mailparse.ini </geshi>

mailparse.ini: <geshi lang="ini" >

  1. configuration for php mailparse module

extension=mailparse.so </geshi>

Creating the virtual host in Apache

Note: Remember to replace helpdesk.example.com with your own domain name.

Create the virtual host in Apache2: <geshi lang="text"> shell> vi /etc/apache2/sites-available/helpdesk.example.com </geshi>

helpdesk.example.com: <geshi lang="apache" > <VirtualHost *:80>

ServerAdmin you@example.com
ServerName helpdesk.example.com
DocumentRoot /home/vhosts/helpdesk.example.com/httpdocs
<Directory /home/vhosts/helpdesk.example.com/httpdocs>
 Options -Indexes FollowSymLinks MultiViews
 AllowOverride All
 Order allow,deny
 allow from all
</Directory>
ErrorLog /var/log/apache2/error.log
# Possible values include: debug, info, notice, warn, error, crit,
# alert, emerg.
LogLevel warn
CustomLog /var/log/apache2/access.log combined

</VirtualHost> </geshi>

Configuring PHP

We need a little more memory than PHP gives us by default. We also want to explicitly define our temporary directory for file uploads.

<geshi lang="text"> shell> vi /etc/php5/apache2/php.ini </geshi>

Find the following lines and update their values.

php.ini: <geshi lang="ini" > memory_limit = 32M upload_tmp_dir = /tmp </geshi>

Activate the new website

<geshi lang="text"> shell> a2ensite helpdesk.example.com </geshi> <geshi lang="text"> shell> /etc/init.d/apache2 restart </geshi>

Create the MySQL database

<geshi lang="bash"> shell> mysql -u root -p </geshi>

<geshi lang="sql"> mysql> CREATE DATABASE cerb4 CHARACTER SET utf8 COLLATE utf8_general_ci; mysql> GRANT ALL PRIVILEGES ON cerb4.* to cerb4@localhost IDENTIFIED BY 's3cr3t'; mysql> QUIT; </geshi>

Installing Cerb4

Now we're going to run the Cerb4 installer. If you don't have an existing SMTP/POP3 server, you can configure Gmail to work with Cerb4.

  • Open http://helpdesk.example.com/admin in your browser.
  • Verify everything is green in the Server Environment Tester.
  • If successful, click the "Next Step" button.
  • Read and accept the license.
The Cerb4 Installer

Database Setup

(enter the same information you used when creating the database)

  • Driver: MySQL 3.23/4.x/5.x
  • Host: localhost
  • Database Name: cerb4
  • Username: cerb4
  • Password: s3cr3t

Click the Continue button.

Settings

  • Choose Mail addresses

Outgoing Mail

  • SMTP Server: (enter your details)

Your Account

  • Enter your personal e-mail address (not the helpdesk's!) and choose a password.

Registration

  • Fill out the quick survey for a free 3 worker license.

Cleaning up

Enter the Cerb4 project directory: <geshi lang="text"> shell> cd /home/vhosts/helpdesk.example.com/httpdocs/admin </geshi> Remove the installation directory for security purposes: <geshi lang="text"> shell> rm -Rf install/ </geshi>

Setting up your scheduled tasks timer

  • Test at the console first:

<geshi lang="text"> shell> curl --interface lo "http://helpdesk.example.com/admin/cron?ignore_wait=1&loglevel=6" </geshi>

If that works, then continue:

<geshi lang="text"> shell> adduser cerb4 </geshi> (pick a hard to guess password)

<geshi lang="text"> shell> crontab -e -u cerb4 </geshi>

crontab: <geshi lang="text" >

</geshi>

Performance Tuning

Out of the box Cerb4 is pretty fast, but we can make it even faster. For more information on Memcached and APC, read the article on Performance.

Memcached

Memcached provides a shared memory cache where arbitrary information can be read frequently without incurring the overhead of a database.

Install the memcached daemon and the PHP5 client library: <geshi lang="text"> shell> apt-get install memcached php5-memcache </geshi> Edit the configuration file: <geshi lang="text"> shell> vi /etc/memcached.conf </geshi>

memcached.conf:

Find the "-m" line and reduce the shared memory to 2MB. That should be plenty for the cache of a single helpdesk on our virtual server. <geshi lang="text" > -m 2 </geshi>

Start the Memcached daemon: <geshi lang="text"> shell> /etc/init.d/memcached start </geshi> Edit Cerb4's framework.config.php file to take advantage of Memcached: <geshi lang="text"> shell> vi /home/vhosts/helpdesk.example.com/httpdocs/admin/framework.config.php </geshi>

framework.config.php:

Uncomment (remove the leading "//") the following options and set their value.

  • DEVBLOCKS_CACHE_PREFIX can be anything as long as it's unique. This helps prevent someone from guessing your cache keys.
  • DEVBLOCKS_MEMCACHED_SERVERS can be left as its defaults.

<geshi lang="php" > define('DEVBLOCKS_CACHE_PREFIX','_something_unique_'); // ONLY A-Z, a-z, 0-9 and underscore define('DEVBLOCKS_MEMCACHED_SERVERS','127.0.0.1:11211'); </geshi>


Log in for the first time

Installing the Support Center

The Support Center allows your community to use their web browser to:

  • Open new tickets and review their history
  • Browser your knowledgebase
  • Update their contact information

Creating a Support Center in Cerb4

  • Log in to your helpdesk as an administrator
  • Click "helpdesk setup" in the top right
  • Click the "Features & Plugins" tab and make sure the following plugins are enabled:
    • Cerberus Helpdesk: Community Tools
  • Click the "Community Tools" tab
  • Under "Add Community":
    • Community Name: Website
    • Add New Community Tool: Support Center
  • Click "Save Changes"
    Creating a new Support Center community tool
  • Click the new "Support Center" link in the left column
    Configuring your new Support Center

You can customize your new Support Center to your heart's desire later. For now, let's add an example contact situation.

  • Scroll down to the "Add a Contact Situation" box under the "Open Ticket" heading.
  • Enter the following text:
    Add a contact situation to make ticket creation easier for your visitors
  • Click "Save Changes"

Deploying the Support Center

  • From the Support Center you just created above, scroll to the bottom until you see the "Installation" section
    Wiki slicehost sc deploy.png

For demonstration purposes we're going to deploy your new Support Center on the same domain as your helpdesk, but you could deploy it on *any* domain on *any* server that supports PHP4 or PHP5.

  • Copy the index.php content from the first textbox and paste it into the file /home/vhosts/helpdesk.example.com/httpdocs/index.php
  • Copy the .htaccess content from the second textbox and paste it into the file /home/vhosts/helpdesk.example.com/httpdocs/.htaccess

You're open for business!

  • Open your browser to: http://helpdesk.example.com/
    Your new Support Center!