HomeAdmin ManualHelpSpot 4 - Installation & SetupHelpSpot Server Setup: Debian/Ubuntu

5. HelpSpot Server Setup: Debian/Ubuntu

We'll cover setting up an Debian/Ubuntu server for use with HelpSpot.

This will install PHP, Apache and MySQL.

Note that this guide will assume you're using Ubuntu 18.04 LTS. Steps should be similar for other recent Debian/Ubuntu versions.

Apache & PHP

We'll begin by installing Apache and PHP.

sudo apt-get install -y apache2 libapache2-mod-php php php-cli \
php-mysql php-curl php-gd php-memcached php-intl php-imap \
php-tidy php-ldap php-xml

Once that's complete, Apache will be running with PHP support, including the basic and recommended modules needed by HelpSpot to function.

Let's edit the PHP.ini configuration file for one needed adjustment: Setting the timezone. Newer PHP often throws off errors if the timezone isn't set, which can cause issues with HelpSpot's error reporter.

Edit edit php.ini in /etc/php/7.2/apache2/php.ini and set the "date.timezone" setting to any valid timezone, such as UTC. HelpSpot will use the correct timezone within the application despite this setting, but this will prevent PHP from throwing "warning" and "notice" type errors about the timezone not being set.

Timezone:

Change this from:

;date.timezone =

to:

date.timezone = UTC

(Note that it is no longer commented out with the preceding ";" character)

Memory Limits:

We also suggest setting PHP memory limits up from the stock settings. What you need depends on your use case, typically if there are larger files being sent in as attachments. We recommend 128M or 256M as a memory limit.

memory_limit = 256M

Once this is done, restart Apache for the change to take affect:

sudo service apache2 restart

Next you should create an Apache VirtualHost for the HelpSpot site. We'll make a few assumptions:

Here is a VirtualHost file suitable for HelpSpot

<VirtualHost *:80>
    ServerName support.example.com
    DocumentRoot /var/www/support.example.com

    <Directory /var/www/support.example.com>
        Options -Indexes +FollowSymLinks +MultiViews 
        # Disallow .htaccess file usage: 
        AllowOverride None 
        Require all granted
    </Directory>

    <Directory /var/www/support.example.com/data>
        # Disallow web access to "data" directory:
        Deny from all
    </Directory>
    
    ErrorLog ${APACHE_LOG_DIR}/support.example.com-error.log
    # Possible values include: debug, info, notice, warn, error, crit, 
    # alert, emerg. LogLevel warn
    CustomLog ${APACHE_LOG_DIR}/support.example.com-access.log combined
</VirtualHost>

Note that if you're using HelpSpot with an SSL certificate, you'll need to add a <VirtualHost *:443> configuration block and add the necessary SSL certificate directives.

Create the virtualhost in the /etc/apache2/sites-available directory, in any file name. I typically name files similar to the hostname, such as "support.example.com.conf".

Once the VirtualHost file is created (I'll assuming at /etc/apache2/sites-available/support.example.com.conf" for this example), you can enable it with the following commands:

sudo a2ensite support.example.com
sudo service apache2 reload

The first command creates a symlink for the support.example.com.conf file between the /etc/apache2/sites-available and /etc/apache2/sites-enabled directories. The second command tells Apache to reload it's configuration so it will see the new VirtualHost now found in the sites-enabled directory thanks to the symlink created in the first command.

MySQL

Next we'll install and create the MySQL database.

sudo apt-get install mysql-server-5.7

That will likely ask you to create a password for your root user during installation. Optionally after the installation, run the script to clean up and secure some portions of MySQL:

sudo mysql_secure_installation

Run through the options it gives you, choosing "yes" to remove remote connections and test databases.

Once that's done, we can create a new database for HelpSpot. Run the following SQL after logging into the mysql command:

Log in:

sudo mysql

Then use the following to create a new database:

CREATE DATABASE helpspot_db
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;

This will create a database. The last step is to create a user that can connect to the HelpSpot database locally. We'll use "localhost" For the host that the user can connect from. You should create additional users with other hosts or IP addresses defined if connecting to a remote MySQL server.

Still within the MySQL command prompt, run the following two commands. Note I'm assuming you created a database named "helpspot_db" and want a user named "helpspot_user". Also use a more secure password than the example here:

CREATE USER 'helpspot_user'@'localhost' IDENTIFIED BY 'some_secure_password';
GRANT ALL PRIVILEGES on helpspot_db.* TO 'helpspot_user'@'localhost';

Once that's done, edit your HelpSpot's config.php file to use the database and password you created above.

IonCube Loader

HelpSpot requires the use of IonCube loader to read HelpSpot code files.

IonCube loader can be downloaded from here. You'll most likely use the Linux 64bit version, but will vary depending on the server in which HelpSpot will be hosted.

To install IonCube using their wizard, download the "Uploader" file of the appropriate version. This will download the Loader files and an HTML wizard which will inform you of how to install the IonCube loader. Downloading these files and running the wizard can be done by:

An example video of this process of installing IonCube loader via the wizard can be seen here.

A list of command which should work for the latest Debian/Ubuntu (assuming they install php version 7.2):

curl -o ioncube_loaders_lin_x86-64.tar.gz \
     http://downloads3.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz

# Uncompress .tar.gz file
tar -xvf ioncube_loaders_lin_x86-64.tar.gz

# Change into the new ioncube files
cd ioncube

# Add the ioncube loader for php 5.6, assuming that is what's installed
# NOTE that this file path will change depending on the PHP version installed sudo cp ioncube_loader_lin_7.2.so /usr/lib/php/20170718/ioncube_loader_lin_7.2.so # Edit/create the php module to load IonCube: sudo vim /etc/php5/mods-available/ioncube.ini

Make the 00-ioncube.ini file look like this:

; Enable IonCube
;priority=00
zend_extension=/usr/lib/php/20170718/ioncube_loader_lin_7.2.so 

Then enable that for all PHP SAPI's (CLI, Apache and/or FPM):

sudo phpenmod -s ALL ioncube

Then restart Apache:

sudo service apache2 restart

Note the phpenmod ALL command will enable ioncube for all SAPIs. You can double check this by confirming that the configuration file for IonCube exists in /etc/php/7.2/mods-available/ and is symlinked in /etc/php/7.2/cli/conf.d and /etc/php/7.2/apache/conf.d or /etc/php/7.2/fpm/conf.d.

HelpSpot Files

At this point you are ready download and transfer the HelpSpot install directory to your previously defined web directory.

sudo mv ~/helpspot_4.8.18/* /var/www/support.example.com/    

HelpSpot needs to be able to write to the "data" directory included. Let's make sure the HelpSpot files have the correct ownership, and then set the the data directory to be writable.

# Set ownership to default web user "www-data":
sudo chown -R www-data:www-data /var/www/support.example.com

# Ensure user/group "www-data" can write to the data directory:
sudo chmod -R gu+rw /var/www/support.example.com/data

Wrapping Up

Copy the /var/www/support.example.com/config-empty.php file to /var/www/support.example.com/config.php, edit that config.php file as needed (database configuration + cHOST variables) and then run the installer.php file from your web browser e.g. http://support.example.com/installer.php.

If you experience errors, check for PHP errors at the configured Apache error log. In this example, that log location is /var/log/apache2/support.example.com-error.log.

You may also wish to edit the /etc/php/72/apache2/php.ini file to change PHP configuration. For example, you may wish to enable display_errors and set the error_reporting to the example "development" setting to see more errors and debug potential issues during HelpSpot installation.

If you edit the php.ini file, be sure to restart Apache after configuration changes:

sudo service apache2 restart

Assuming everything else is setup, you are now ready to run HelpSpot's installer. This is usually done in the web browser, using "installer.php" (e.g. http://your-helpspot-site.com/installer.php), but you can also run the installer using HelpSpot's new "install" CLI command as well.

This page was: Helpful | Not Helpful