Home → Installation and Upgrade Manual → Printer Friendly Version

Installation and Upgrade Manual

How to install and upgrade HelpSpot on your own server. Note: if you are using HelpSpot Cloud this documentation is not needed.

1. HelpSpot 5 Installation
2. Upgrading HelpSpot 5
3. Upgrading Dependancies
- 3.1. Upgrading PHP on Windows
4. Upgrading From HelpSpot 4.9.5 To HelpSpot 5.x
5. Installation Troubleshooting
HelpSpot 4 - Installation & Setup

1. HelpSpot 5 Installation

1.1. HelpSpot 5 Overview

Welcome to the HelpSpot Installation Documentation. Please review the documentation in this book carefully to install a new instance of HelpSpot 5 or upgrade your existing instance.

Existing HelpSpot 4 Installation

Updating to HelpSpot 5

New HelpSpot Instance

Installing HelpSpot 5

1.2. HelpSpot 5 Installation

Installation

HelpSpot 5 server requirements can be found here.

Windows Installation

The Windows Server installation guide can be found here. This guide uses an IIS and Microsoft SQL Server based installation.

Linux Installation

General Linux installation documentation can be found here. We also have specific walk-through examples of installing HelpSpot:

1.3. HelpSpot Linux Installation

The general steps for installing HelpSpot on linux are:

Ensure server is ready to serve a PHP application
Add HelpSpot files to the web server
Configure the .env file
Run the installer command
View HelpSpot in the web browser
Setup CRON tasks
Setup Queue worker

We provide specific setup guides for Red Hat and Ubuntu.

Server Configuration

Your HelpSpot server should be configured to meet the server requirements prior to beginning installation.

HelpSpot Files

You can download HelpSpot files and your license from the HelpSpot Store.

Once the files are on your server, the HelpSpot site files should sit one directory "above" the web root.

For example, if your Apache/Nginx web root is configured to /var/www/helpspot/public, then the HelpSpot site files should be placed in /var/www/helpspot.

The HelpSpot files include a public directory to be used as the public web root. The webroot configured in Nginx/Apache should therefore be configured to point to the public directory e.g. /var/www/helpspot/public.

Create HelpSpot Database

MySQL databases for HelpSpot version 5 should default to the InnoDB storage engine and to a UTF-8mb4 character set and collation.

CREATE DATABASE helpspot_db2
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;

Note that you can change the database name (helpspot_db) as needed for your use case. You may also need to assign a specific user to the database.

Environment Configuration

HelpSpot requires a file named .env with configuration details.

HelpSpot includes a .env.example file. You can copy this file to create a file named .env and change the parameters as needed:

APP_DEBUG=false
APP_URL=https://example.org
APP_KEY=

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=helpspot
DB_USERNAME=some_user
DB_PASSWORD=some_pass

QUEUE_CONNECTION=database

Here are some details on the configuration:

APP_DEBUG - Setting this to true will show full error stack traces in the web browser if errors occur. Errors will always appear in the log file at storage/logs/helpspot.log whether this is set to true or false.
APP_URL - The URL used to access HelpSpot from the web browser. This is important to set correctly so HelpSpot generates links correctly. This should include the "https://" portion and any trailing file paths, such as "https://example.org/helpspot".
APP_KEY - This will be set during installation should be present but left blank (exactly as APP_KEY=).
DB_CONNECTION - one of mysql or sqlsrv. Use mysql for any MySQL variant such as MariaDB or Percona
DB_* - the connection details for the database
QUEUE_CONNECTION - This should stay as database, but it's possible to use other queue connections, such as redis.

Install HelpSpot

This will install HelpSpot, which primarily consists of setting up your database for use.

Be sure a plaintext text file with your HelpSpot license is present on the server in a location that your webserver can read from.

To install HelpSpot, you must run a command in your terminal. The following with prompt you for details, although you can provide this command with the required data to automate this:

# Get the help menu to see available options
php hs install -h

# Run the installer interactively
php hs install

For a list of possible timezones, see here.

The value for the license file (one of the prompts you'll receive) shouild be the full path to the text file containing your license, or a relative file path relative to your current directory (the result of the pwd command).

View in Web Browser

Once that is installed, you should be ready to view HelpSpot in your browser. If your HelpSpot is available at https://example.org, you can view:

Public Portal at https://example.org
Admin area at https://example.org/admin

CRON Task

HelpSpot requires the use of some periodic tasks. On Linux systems, these are powered by CRON.

HelpSpot 5 files include an example CRON task to use in helpers/cron/helpspot. This file can be added to /etc/cron.d or the contents of it can be used to create a cron task using your preferred configuration.

There is just a single CRON task to use:

# Timing    User       Command
* * * * *   www-data   cd /var/www/helpspot && /usr/bin/php hs schedule:run

The above example has a user defined to run the task as. You'll need to adjust the user and file paths as needed for your server. You can omit the user if you're installing this configuration into a user-specific crontab, for example if you're running the command sudo crontab -u www-data -e to run the cron task as user www-data.

Queue Configuration

HelpSpot uses a queue worker to process incoming and outgoing emails.

The command to run in a queue worker is as follows:

php hs queue:listen database --queue=high,default --sleep=3 --tries=3

This assumes you are running the queue worker as a user appropriate (generally the same that runs PHP for web requests, such as www-data) and are running it relative to your HelpSpot directory, such as /var/www/helpspot.

More documentation on setting up the queue worker can be found here.

1.4. Installing HelpSpot 5 On Redhat 8

This video guide walks through the full setup of HelpSpot 5 On Redhat Linux.

HelpSpot 5 Server Setup

On our RedHat 8 server, we'll install and setup the following:

MariaDB - to store HelpSpot data
Nginx - to serve web requests and pass them to PHP
PHP - to serve the HelpSpot application
CRON - to run scheduled tasks
Queue Worker - to read and send email

Install

On RedHat 8:

sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-8.rpm

sudo dnf module list php

sudo dnf module enable -y php:remi-8.3

sudo dnf install unzip vim mysql-server nginx supervisor \
    php-cli php-common php-fpm php-mysqlnd php-imap php-ldap \
    php-pdo php-mcrypt php-gd php-xml php-curl

On Amazon Linux 2:

sudo amazon-linux-extras enable php8.3 nginx1 epel

sudo yum install -y epel-release

sudo yum install -y unzip vim mariadb-server nginx supervisor \
    php-cli php-common php-fpm php-mysqlnd php-imap php-ldap \
    php-pdo php-mcrypt php-gd php-xml php-curl

Configure MySQL

On Redhat:

sudo systemctl enable mysqld
sudo systemctl start mysqld

sudo mysql_secure_installation

mysql -u root -p

create database helpspot charset utf8mb4;
create user helpspot@'localhost' identified by 'secret';
grant all privileges on helpspot.* to helpspot@'localhost';

On Amazon Linux 2:

sudo systemctl enable mariadb
sudo systemctl start mariadb

sudo mysql_secure_installation

mysql -u root -p

create database helpspot charset utf8mb4;
create user helpspot@'localhost' identified by 'secret';
grant all privileges on helpspot.* to helpspot@'localhost';

Configure PHP

File /etc/php.ini:

max_execution_time = 120
max_input_time = 120
memory_limit = 256M
post_max_size = 256M
upload_max_filesize = 100M
date.timezone = UTC

File /etc/php-fpm.d/www.conf:

; Note: User/Group used is "apache"
; Note: Socket file is /run/php-fpm/www.sock
pm.max_requests = 500

sudo systemctl enable php-fpm
sudo systemctl start php-fpm

Configure Nginx

sudo systemctl enable nginx
sudo systemctl start nginx

Test it out in the browser! We can create a PHP file to see that it is setup to run PHP applications already:

Create file /usr/share/nginx/html/index.php with:

<?php
phpinfo();

And we'll see that page load without further configuration.

The only change we'll make then is to set a new root to point to where HelpSpot will be installed to.

Edit file /etc/nginx/nginx.conf and change the root:

root         /var/www/helpspot/public;

location / {
    try_files $uri $uri/ /index.php$is_args$args;
}

Then reload Nginx:

# Test nginx configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

Install HelpSpot

cd ~/
curl -o helpspot.zip https://s3.amazonaws.com/helpspot-downloads/5.4.6/helpspot.zip

sudo mv helpspot.zip /var/www
cd /var/www

sudo unzip -q helpspot.zip
sudo mv helpspot_5.4.6 helpspot

cd helpspot
sudo cp .env.example .env

# Update .env file
sudo vim .env

# Change owner of files
sudo chown -R nginx:nginx /var/www/helpspot
sudo chcon -Rv --user=system_u --role=object_r --type=httpd_sys_content_t /var/www/helpspot
sudo chcon -Rv --type=httpd_sys_content_rw_t /var/www/helpspot/bootstrap
sudo chcon -Rv --type=httpd_sys_content_rw_t /var/www/helpspot/storage


sudo -u nginx php hs install

Configure Cron

Create file /etc/cron.d/helpspot and add the following:

* * * * * nginx php /var/www/helpspot/hs schedule:run

Check that it's being run:

sudo tail -f /var/log/cron

Configure Queue

We'll enable/start the service supervisord:

sudo systemctl enable supervisord
sudo systemctl start supervisord

Create file /etc/supervisord.d/helpspot.ini with contents:

[program:helpspot]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/helpspot/hs queue:listen database --queue=high,default --sleep=3 --tries=3
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=apache
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/helpspot-worker.log

Then run the following to start the workers:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start helpspot:*

Keep an eye on your error log to spot any issues at storage/logs/helpspot.log, e.g. /var/www/helpspot/storage/logs/helpspot.log.

1.5. Installing HelpSpot 5 On Ubuntu

This video walks through the entire process of setting up a new install of HelpSpot on Ubuntu Linux.

On our Ubuntu 20.04 server, we'll install and setup the following:

MySQL - to store HelpSpot data
Nginx - to serve web requests and pass them to PHP
PHP - to serve the HelpSpot application
CRON - to run scheduled tasks
Queue Worker - to read and send email

Install Prerequisites

This command will install the several applications that HelpSpot needs to run. If you are using an external mysql database you can skip installing mysql-server.

sudo apt-get install -y mysql-server nginx supervisor unzip

Install PHP

sudo apt-get update

sudo add-apt-repository -y ppa:ondrej/php

sudo apt-get update

sudo apt-get install -y php8.3-cli php8.3-fpm php8.3-mysql
php8.3-sqlite3 php8.3-curl php8.3-gd php8.3-intl 
php8.3-imap php8.3-ldap php8.3-mbstring php8.3-xml
php8.3-zip php8.3-bz2 php8.3-bcmath php8.3-readline
php8.3-igbinary php-memcached php-redis

Configure MySQL

If you are using an external mysql server you will want to create your database and user on that server.

sudo mysql_secure_installation

sudo mysql
create database helpspot charset utf8mb4;
create user helpspot@'localhost' identified by 'secret';
grant all privileges on helpspot.* to helpspot@'localhost';

Configure PHP

Open the file in an editor /etc/php/8.3/fpm/php.ini and modify these parameters:

max_execution_time = 120 
max_input_time = 120 
memory_limit = 256M 
post_max_size = 256M 
upload_max_filesize = 100M 
date.timezone = UTC

Open the file /etc/php/8.3/fpm/pool.d/www.conf and modify these settings:

pm.max_children = 20
pm.start_servers = 4 
pm.min_spare_servers = 3 
pm.max_spare_servers = 6 
pm.max_requests = 500

Then restart PHP-FPM

sudo service php8.3-fpm restart

Configure Nginx

Edit/create the file /etc/nginx/sites-enabled/helpspot:

server {
    listen 80;

    # Enable if using SSL
    # listen 443 ssl;

    root /var/www/helpspot/public;
    index index.html index.htm index.php;

    access_log /var/log/nginx/helpspot.log helpspot;
    error_log  /var/log/nginx/helpspot-error.log error;

    # Change to your domain
    server_name _;

    charset utf-8;

    # Enable if using SSL certificates
    # ssl_certificate           /path/to/ssl.crt;
    # ssl_certificate_key       /path/to/ssl.key;

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location = /favicon.ico { log_not_found off; access_log off; }
    location = /robots.txt  { log_not_found off; access_log off; }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;

        fastcgi_buffers 36 64k;
        fastcgi_buffer_size 32k;
        fastcgi_read_timeout 120s;
    }
}

Remove the /etc/nginx/sites-enabled/default file as well.

Install HelpSpot

We will need to download the latest release of the HelpSpot application to the the server. In this example we are using 5.4.6. Your version number will vary.

You can find the latest version of helpspot by going to https://helpspot.com/releases

wget https://s3.amazonaws.com/helpspot-downloads/5.4.6/helpspot.zip
unzip -q helpspot.zip

# Move helpspot
mv helpspot_5.4.6 helpspot

Next we need to update the create a .env file from the example file and update the settings to reflect the database connection, app url etc. More information on the .env file can be found here.

cd /var/www/helpspot
cp .env.example .env

Update your .env file with the needed settings in a text editor of your choice.

Next make sure that your helpspot directory is owned by the www-data user.

sudo chown -R www-data:www-data /var/www/helpspot

Make sure that you have downloaded the helpspot license file to an accessible location. You will need this file during the HelpSpot install. Next we'll run the helpspot installer that will guide us throught needed information for installation.

sudo -u www-data php hs install

After installing it, check the browser to ensure everything is working.

Configure Cron

Create file /etc/cron.d/helpspot and add the following:

* * * * * www-data php /var/www/helpspot/hs schedule:run

Configure Queue

Create file /etc/supervisor/conf.d/helpspot.conf with contents:

[program:helpspot]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/helpspot/hs queue:listen database --queue=high,default --sleep=3 --tries=3
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/helpspot-worker.log

Then run the following to start the workers:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start helpspot:*

1.6. HelpSpot 5 Windows Installation Changes

New Installations:

In order to accommodate a more flexible installation and administration process for Windows HelpSpot installs we are now recommending using the process outlined here to install HelpSpot. This process allows easy updates to each system component and allows for more customization based on system architecture requirements. In general the support for PHP on windows has improved greatly since we introduce the windows installer. So, the automated setup through an install tool is no longer needed.

Updates

Updates are also being streamlined into a process very similar to the linux update process. This process will require less downtime and be less prone to errors based on system customization. If you need to update your instance from HelpSpot 4 (which was installed with the windows installer) to HelpSpot 5 we have documented those steps here.

1.7. Installing HelpSpot 5 On Windows Step by Step

Download HelpSpot

Download the latest zip package of HelpSpot from https://store.helpspot.com
Download your HelpSpot license file from https://store.helpspot.com

Install IIS

You can follow Microsoft's provided documentation: https://docs.microsoft.com/en-us/iis/install/installing-iis-85/installing-iis-85-on-windows-server-2012-r2
Make sure to enable the CGI Role under Web Server > Web Server > Application Development

Install PHP

Go to https://windows.php.net/download and download the latest NTS (Non thread safe) build of PHP 8.3 for x64
Extract the downloaded zip to a temporary location
Create a new PHP directory at C:\PHP
Paste the the contents of your downloaded php package into C:\PHP

Configure PHP

Rename C:\PHP\php.ini-production to C:\PHP\php.ini
Edit the php.ini file and add upload_tmp_dir=c:\PHP\tmp to the bottom of the file.
Find the "Dynamic Extensions" area of your php.ini file and enable these extensions: curl, fileinfo, gd, imap, ldap, mbstring, and openssl
Create a directory at c:\PHP\tmp

Install Certificate Store for PHP

Go to https://curl.se/docs/caextract.html and download the latest certificate bundle to C:\PHP\
Edit the php.ini file in C:\PHP\ and add these two lines to the bottom of the file:
curl.cainfo="C:/php/cacert.pem" openssl.cafile="C:/php/cacert.pem"

SQL Server Drivers For PHP

Download the SQL Server drivers for PHP 8.3 from https://github.com/microsoft/msphpsql/releases/latest/ (scroll down on the page to find Windows-8.3.zip)
Extract the Zip to a temporary location
Open the x64 folder in the extracted folder.
Copy php_sqlsrv_83_nts.dll and php_pdo_sqlsrv_83_nts.dll to C:\PHP\ext\
Open the php.ini file in C:\PHP\php.ini in a editor of your choice
Search for Dynamic Extensions
You will find a list of extensions in this section. Add the two new extensions needed:
```
extension=php_pdo_sqlsrv_83_nts
extension=php_sqlsrv_83_nts
```

Add PHP as an IIS FastCGI Module

Open the IIS Manager
Click on your server in the tree view and then select Handler Mappings
Choose add Module Mapping
Request path: *.php
Module: FastCgiModule
Executable: C:\PHP\php-cgi.exe
Name: PHPFastCGI
Click Ok to save the new mapping
Select "Yes" to add a entry to FastCGI Collection

Add IIS Default Document

Click on your server in the tree view
Click Add... in the Actions panel to add a new default document.
Enter index.php as a new default document and click ok.

Set Default Directory to Public

In IIS manager expand Sites in the tree view
Click on the Default Website
In the Actions panel under the Edit Site section, click Basic Settings
Change the physical path to %SystemDrive%\inetpub\wwwroot\public

Setup IIS URL Rewrite Extension

Download the extension from https://www.iis.net/downloads/microsoft/url-rewrite
Install the extension.

Create Your HelpSpot Database and User

Open the SQL Server Management Studio and connect to your SQL Server
Right click on Security and choose New > Login
Enter the desired login name e.g. "helpspot_user"
Choose SQL Server authentication and set a password
Create the user.
Right click on Databases and choose New Database
Enter the desired database name e.g. "helpspot_db"
Set the owner to your previously created user

Setup HelpSpot Files

Copy the contents of your extracted helpspot zip package to C:\inetpub\wwwroot\
Your wwwroot directory should contain an app\ folder, bootstrap\ folder, config\ folder etc.
Edit the properties of the storage directory
In the Security tab give the IIS_IUSRS full control

Environment Configuration

HelpSpot requires a file named .env with configuration details.

HelpSpot includes a .env.example file. You can copy this file to create a file named .env and change the parameters as needed:

APP_DEBUG=false 
APP_URL=http://localhost 
APP_KEY= 
DB_CONNECTION=sqlsrv 
DB_HOST=localhost 
DB_PORT=1433 
DB_DATABASE=helpspot_db
DB_USERNAME=helpspot_user 
DB_PASSWORD=test 
QUEUE_CONNECTION=database

Here are some details on the configuration:

APP_DEBUG - Setting this to true will show full error stack traces in the web browser if errors occur. Errors will always appear in the log file at storage/logs/helpspot.log whether this is set to true or false.
APP_URL - The URL used to access HelpSpot from the web browser. This is important to set correctly so HelpSpot generates links correctly. This should include the "https://" portion and any trailing file paths, such as "https://example.org/helpspot".
APP_KEY - This will be set during installation should be present but left blank (exactly as APP_KEY=).
DB_CONNECTION - one of mysql or sqlsrv. On most windows installs you will be using sqlsrv
DB_* - the connection details for the database
QUEUE_CONNECTION - This should stay as database, but it's possible to use other queue connections, such as redis.

Install HelpSpot

Open the command line and cd to cd C:\inetpub\wwwroot
Run the HelpSpot Installer: c:\PHP\php.exe hs install
Enter the requested information in the install wizard

Setup Your Queue

Navigate to C:\inetpub\wwwroot\helpers\windows
The setup.bat file is preconfigured to use the default paths that are used in these docs. If your php or website are installed at different paths, modify the first two lines to reflect your paths.
Run setup.bat. This will create your supervisor.conf file and install your queue services

1.8. Linux Server Administration

Linux Server Administration

Webroot Configuration

HelpSpot 5 introduces a new directory in its code base that is intended to be used as the web server's public root directory. That directory is named public.

Web servers should update their web root directive as follows:

Nginx: Update the root directive, e.g. root /var/www/helpspot/public;
Apache: Update the DocumentRoot directive, e.g. DocumentRoot /var/www/helpspot/public

In HelpSpot 4 and earlier, web server configuration's pointed the web root (root in Nginx, DocumentRoot in Apache) to HelpSpot's root directory.

For example, if HelpSpot was installed at /var/www/helpspot, then the web server's web root would be located at the same directory, /var/www/helpspot.

HelpSpot 5 uses the public directory as an added security measure. It ensures that HelpSpot's code files are not accessible to the public internet. Security measures were previously in place to prevent this, but this adds an extra layer of security.

Nginx Configuration

Here's an example Nginx configuration, which assumes PHP-FPM for PHP 8.3 is installed.

This configuration assumes an SSL certificate is used.

server {
    # Enforce the use of HTTPS
    listen 80 default_server;
    server_name example.org;
    return 301 https://$host$request_uri;
}

server {
    listen 443 default_server ssl;

    root /var/www/helpspot/public;
    index index.html index.htm index.php;

    access_log /var/log/nginx/helpspot.log helpspot;
    error_log  /var/log/nginx/helpspot-error.log error;

    server_name example.org;

    charset utf-8;

    ssl_certificate           /etc/ssl/helpspot/example.org.crt;
    ssl_certificate_key       /etc/ssl/helpspot/example.org.key;

    # Allow lets encrypt checks
    location ^~ /.well-known/acme-challenge/ {
        allow all;
    }

    # Disallow dot file access
    location ~* (?:^|/)\. {
        deny all;
    }

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location = /favicon.ico { log_not_found off; access_log off; }
    location = /robots.txt  { log_not_found off; access_log off; }

    location ~ \.php$ {
        # This included snippet is on Debian/Ubuntu servers but
        # may not be on RedHat/CentOS/Fedora/AWS Linux servers
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_buffers 36 64k;
        fastcgi_buffer_size 32k;
        fastcgi_read_timeout 120s;
    }
}

We have detailed video examples of configuring Linux servers for use with HelpSpot 5 available here:

HelpSpot in Subdirectory

If HelpSpot is being used in a subdirectory, the following Nginx configuration can help make that work:

server {
    listen 443 default_server ssl;

    # We assume the example.org website is hosted
    # out of the /var/www/html directory
    root /var/www/html;

    index index.html index.htm index.php;

    access_log /var/log/nginx/example.org.log helpspot;
    error_log  /var/log/nginx/example.org.log error;

    server_name example.org;

    charset utf-8;

    ssl_certificate           /etc/ssl/helpspot/example.org.crt;
    ssl_certificate_key       /etc/ssl/helpspot/example.org.key;

    # Allow lets encrypt checks
    location ^~ /.well-known/acme-challenge/ {
        allow all;
    }

    # Disallow dot file access
    location ~* (?:^|/)\. {
        deny all;
    }

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    # If HelpSpot is served from the "/helpdesk" subdirectory
    # then we create a location {} block for it and use
    # an alias to point to the correct web root for HelpSpot
    location /helpdesk {
        alias /var/www/helpspot/public;
        try_files $uri $uri/ @nested;

        location ~ \.php$ {
            include snippets/fastcgi-php.conf;
            fastcgi_param SCRIPT_FILENAME $request_filename;
            fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
            fastcgi_buffers 36 64k;
            fastcgi_buffer_size 32k;
            fastcgi_read_timeout 120s;
        }
    }

    # We also need a rewrite to correctly rewrite the
    # /helpdesk subdirectory, so we don't need index.php
    # in the URI
    location @nested {
        rewrite /helpdesk/(.*)$ /helpdesk/index.php?/$1 last;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_buffers 36 64k;
        fastcgi_buffer_size 32k;
        fastcgi_read_timeout 120s;
    }
}

Note that we installed the HelpSpot code base outside of the web root for the main site.

The web root for example.org is found in /var/www/html while the web root for the HelpSpot installation is found within the HelpSpot code base at /var/www/helpspot. This prevents unauthorized access to HelpSpot code files so we don't, for example, make secrets available within the URL http://example.org/helpspot/.env, which could happen if the HelpSpot code files were installed into directory /var/www/html/helpspot.

Apache Configuration

Here's an example Apache configuration, which assumes the following Apache modules are installed and enabled:

PHP module
Rewrite module

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

    <Directory /var/www/example.org/public>
        Options -Indexes +FollowSymLinks +MultiViews 
        # Allow .htaccess file usage: 
        AllowOverride All 
        Require all granted
    </Directory>

    # Disallow access to dotfiles
    # such as the .env file
    <FilesMatch "^\.">
        Order allow,deny
        Deny from all
    </FilesMatch>

    ErrorLog ${APACHE_LOG_DIR}/example.org-error.log
    # Possible values include: debug, info, notice, warn, error, crit, 
    # alert, emerg. LogLevel warn
    CustomLog ${APACHE_LOG_DIR}/example.org-access.log combined
</VirtualHost>

HelpSpot in Subdirectory

If HelpSpot is installed into a subdirectory, some extra configuration will be required.

For example, if HelpSpot is accessed in the URL /helpdesk (e.g. https://example.org/helpdesk), the following configuration will work for HelpSpot 5.

This assumes the following Apache modules are installed an enabled:

PHP module
Rewrite module
Alias module

<VirtualHost *:80>
    ServerName example.org
    # We assume the example.org website is hosted
    # out of the /var/www/html directory
    DocumentRoot /var/www/html

    # If HelpSpot is served from the "/helpdesk" subdirectory
    # then we can use an Alias to tell Apache where to find 
    # the HelpSpot site files. In this case, "/var/www/helpspot"
    # (HelpSpot's webroot is the "public" directory within the
    # code base, e.g. "/var/www/helpspot/public").
    Alias "/helpdesk" "/var/www/helpspot/public"
    <Directory /var/www/helpspot/public>
        Options -Indexes +FollowSymLinks +MultiViews 
        # Allow .htaccess file usage: 
        AllowOverride All 
        Require all granted
    </Directory>

    # Disallow access to dotfiles
    # such as the .env file
    <FilesMatch "^\.">
        Order allow,deny
        Deny from all
    </FilesMatch>

    ErrorLog ${APACHE_LOG_DIR}/example.org-error.log
    # Possible values include: debug, info, notice, warn, error, crit, 
    # alert, emerg. LogLevel warn
    CustomLog ${APACHE_LOG_DIR}/example.org-access.log combined
</VirtualHost>

Then we need to update the .htaccess file. Within the public directory is a file named .htaccess, e.g. /var/www/helpspot/public/.htaccess. This file needs to be edited to add the RewriteBase directive to include the subdirectory /helpdesk:

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews
    </IfModule>
    
    RewriteEngine On
    
    # Redirect Trailing Slashes If Not A Folder...
    RewriteBase /helpdesk
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)/$ /$1 [L,R=301]
    
    # Handle Front Controller...
    RewriteBase /helpdesk
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
    
    # Handle Authorization Header
    RewriteBase /helpdesk
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
</IfModule>

Note that we installed the HelpSpot code base outside of the web root for the main site.

CRON Configuration

HelpSpot requires some periodic tasks to be run. On Linux systems, these are powered by CRON.

The HelpSpot 5 code base include an example CRON configuration found in the file helpers/cron/helpspot. This file can be added to /etc/cron.d or the contents of it can be used to create a cron task using your preferred configuration.

There is just a single CRON task to use for HelpSpot 5:

# Timing    User       Command
* * * * *   www-data   cd /var/www/helpspot && /usr/bin/php hs schedule:run

You may need to adjust the system user that runs the task, as well as the above file paths as needed for your server. You can omit the user if you're installing this configuration into a user-specific crontab, for example if you're running the command sudo crontab -u www-data -e to run the cron task as user www-data.

The schedule:run command periodically runs other sub-commands which perform various tasks such as checking for new emails, cleaning out error log tables, sending email reports, running automation rules, and more.

Checking Email Mailboxes for new mail occurs every 1 minute by default, but a CRON expression can be used to change that timing by modifying the .env file and adding a MAIL_CRON_INTERVAL option:

# Default, check every one minute
MAIL_CRON_INTERVAL="* * * * *"

For example, to check email every 5 minutes, you can add the following to your .env file:

# Check mail every 5 minutes
MAIL_CRON_INTERVAL="*/5 * * * *"

You can also disable checking emails by editing the .env file and adding the following:

# Disable mail checks
AUTO_COLLECT_MAIL=false

You can then check email mailboxes directly using the following command (either manually or as a new CRON task):

# Check all mailboxes
php hs mail:check

# Check specific mailboxes
php hs mail:check --id=1
php hs mail:check --id=1,2,3

Queue Worker Configuration

HelpSpot uses a queue worker to process incoming and outgoing emails.

The command to process jobs in the queue worker is as follows:

php hs queue:listen database --queue=high,default --sleep=3 --tries=3

This command should be run in a way that restarts on failure and when the server is rebooted. To accomplish that, an "init" system such as Supervisord or Systemd should be used.

Supervisord is recommended as it allows you to run more than one queue worker process easily. We recommend running 2+ worker processes (2 of the above commands).

Systemd is available on most Linux systems without needing to install extra software. A limitation is that a service can only run one process, however as mentioned, we recommend running 2+ worker processes. This can be accomplished with 2 separate Systemd configurations if you choose.

The HelpSpot 5 code base comes with configuration examples for Supervisord and Systemd within the helpers/init directory.

Supervisord

You can install supervisord by running one of the following:

# Debian/Ubuntu
sudo apt-get install -y supervisor

# CentOS/RedHat/Fedora
sudo yum install -y supervisor
sudo systemctl enable supervisor
sudo systemctl start supervisor

If you are using the recommended Supervisord, the helpers/init/helpspot-supervisord.conf file can go into the /etc/supervisor/conf.d directory.

If that directory does not exist, the configuration can be copied into file /etc/supervisor/supervisor.conf or /etc/supervisord.conf (the exact path varies by Linux OS).

Be sure to edit the file if needed to change the user the service runs as, the log file path if required, and the number of worker processes to run (2+).

After placing the file, run:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start helpspot:*

As mentioned, you'll likely want to customize some configurations in the file:

command: The command should be changed to use the correct file paths for the location of your HelpSpot installation
user: The proper user should be configured to run the process, usually the same user that runs the PHP web server
numprocs: The number of worker processes to run. We recommend starting with 2 and adding more if your HelpSpot installation monitors many Email Mailboxes.
stdout_logfile: Adjust the log file path to a path of your choosing

Systemd

If you are using Systemd, the helpers/init/helpspot.service file can be placed in directory /etc/systemd/system/ or /lib/systemd/system/.

Note that we recommend using Supervisord instead of Systemd.

After placing the file, run:

sudo systemctl enable helpspot
sudo systemctl start helpspot

Note that you'll likely want to customize some configuration in the file:

ExecStart: The command may need adjusting, for example if PHP is installed in a different location
WorkingDirectory: The working directory should be adjusted to the path that HelpSpot is installed in
User/Group: The proper user should be configured to run the process, usually the same user that runs the PHP web server

1.9. .env Config (Self Hosted)

HelpSpot Configuration

## Enable debugging output in the web front end
APP_DEBUG=false
## The base url of the HelpSpot application (without a trailing slash)
APP_URL=https://example.org

## Database type mysql or mssql
DB_CONNECTION=mysql
## The DNS name or IP of the database server
DB_HOST=localhost
## The port for the database server
DB_PORT=3306
## The database name for the helpspot database
DB_DATABASE=helpspot
## The database user name
DB_USERNAME=some_user
## The database user password
DB_PASSWORD=some_pass

## The selected queue driver. Database is default.
QUEUE_CONNECTION=database

Any other configuration setting you used to put into config.php can also be added into the .env file.

To convert old settings to new settings, you can use this formula:

Used to be this in config.php:

define('cHD_FOOBAR', 'some-value');

Can now be this within .env:

cHD_FOOBAR="some-value"

Secondary Portals

Secondary portals can optionally use their own .env file as well. If the Portal Path is, for example, /var/www/helpspot/public/some-portal, you can add a .env file to that path: /var/www/helpspot/public/some-portal/.env.

Any items added here will over-ride the settings from the main .env file configuration file.

If .env files are used in secondary portals, it will be important to configure the web server to not serve .env files if requested. Blocking requests for any "dot-file" (files that start with a period) is a common configuration:

Nginx:

## Disable access to all dot files, except for ".well-known",
## which is used for SSL generation
location ~* /\.(?!well-known\/) {
    deny all;
    access_log off;
    log_not_found off;
}

Apache:

## Disable access to all dot files, except for ".well-known",
## which is used for SSL generation
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_URI} "!(^|/)\.well-known/([^./]+./?)+$" [NC]
    RewriteCond %{SCRIPT_FILENAME} -d [OR]
    RewriteCond %{SCRIPT_FILENAME} -f
    RewriteRule "(^|/)\." - [F]
</IfModule>

The New Configuration File

The new configuration file (.env) looks like this:

APP_DEBUG=false
APP_URL=https://example.org

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=helpspot
DB_USERNAME=some_user
DB_PASSWORD=some_pass

QUEUE_CONNECTION=database

Maping old config to new config

The following configurations are no longer defined within a configuration file:

cDBCHARSET
cDBCOLLATION
SEARCH_ENGINE
cSEARCHHOST
cSEARCHPORT
cBASEPATH
cDATADIR

The following configurations map to the new configuration fields:

cDBTYPE => DB_CONNECTION (note that valid values now are mysql or sqlsrv - Value mssql for database type is no longer valid)
cDBHOSTNAME => DB_HOST
DB_PORT => This is a new value. Note that sqlserver value 127.0.0.1,1433 will need to be split into two values (hsotname and port are separate)
cDBUSERNAME => DB_USERNAME
cDBPASSWORD => DB_PASSWORD
cDBNAME => DB_DATABASE
cHOST => APP_URL
cDEBUG => APP_DEBUG

Fresh Installations

New installations can create a new .env file (or copy the .env.example file and replace values as needed).

Updates

We've provided a script to that reads the old config.php file (assuming it's located at C:\Program Files (x86)\helpspot\helpspot\config.php) and generates a .env file:

Working directory: C:\Program Files (x86)\helpspot\helpspot

Command: ..\php\php.exe -c ..\php\php.ini hs config:convert. This command creates (or over-write) file C:\Program Files (x86)\helpspot\helpspot\.env

For testing, you can run ..\php\php.exe -c ..\php\php.ini hs config:convert --dump to see the text output it would otherwise create.

Hidden Settings

Setting MAINTENANCE_MODE=true can be used within the .env file to force maintenance mode.

2. Upgrading HelpSpot 5

2.1. Minor Version Upgrades (v5)

These instruction apply to minor version upgrades. For example: v5.0.45->5.0.58. For major version upgrades (v4 to v5) see the separate upgrade documentation as the process is a bit different.

Backup

It's strongly recommended that you backup your HelpSpot database and files before upgrading. It's especially important to backup files if you have customized your templates or edited the language file.

The installer will make database changes during an upgrade. If something goes wrong the only way to roll back the changes is if you have an up to date backup.

Upgrading Files

Before beginning review the latest system requirements to make sure that the software installed on your server are compatible with the latest version.

If you have a version of HelpSpot 5 already installed you can always upgrade to latest version. There is not a need for intermediary upgrades ever if you have missed some upgrades.

After downloading the newest version of HelpSpot, move the files to your server and unpack the tar.gz or zip file in a temporary location.

Stop your supervisor or systemd queue worker.
Ubuntu/Redhat:
```
sudo supervisorctl stop all
```
Windows:
Navigate to Windows Services and stop the HelpSpotQueue service and the HelpSpotSchedule service.
Move your current helpspot install directory to a backup location (we'll need to restore some files from this backup).
Copy your new helpspot package to that same location where HelpSpot was installed

Copy these directories and files back into your production helpspot folder.

Note, you will want to preserve the permissions of these directories. On Windows robocopy does this for you with the /copyall option on the command line. If you are using Explorer on Windows or the Linux cp command this should handle this for you automatically.

File / Directory	Description
.env	Environment Configuration File
storage/documents	Attachment Storage
storage/app	Application Storage for Jobs
helpspot/custom_pages	Custom Page Code
public/custom_code	Custom Code (AD/LDAP Auth, Live Lookup, etc.)
public/custom_templates	Custom Portal Templates
public/web.config	Copy this file if you have custom IIS settings
helpers/windows	On Windows installations this contains the needed configuration files for the HelpSpot windows services.
helpspot/helpspot/lang/customlanguagepacks	Copy back over any custom language packs you may have in the lang folder. Do not copy the default english-us or core language pack.
Any secondary portal sites or other custom code you have defined

Note: The HelpSpot files are binary and your FTP program will most likely upload them as text unless you tell it to use binary mode. This is why it's recommended to move the compressed file (tar.gz/zip) directly to the server first which will avoid any problems. After uploading if you get a file corrupted or Fatal error in your browser at the installer then the files have been uploaded as text instead of binary.

Reset Permissions

The permissions on the bootstrap/cache and the storage directory need to be writable by the web servers process. In Windows IIS installations this is the done by adding the IUSR with full permissions. On linux you will need to add the user that you webserver is operating under (often www-data).

Upgrade Database

The best way to upgrade the database is by using command line php. From your HelpSpot directory run:

php hs update

You can find more info on the HelpSpot command line here: The HelpSpot Command Line

Restart Queue (v5.0.0+)

After upgrading complete we need to ensure that the queue is using the latest code. We'll need to start the queue worker:

Ubuntu/Redhat:

sudo supervisorctl start all

Windows:

Navigate to Windows Services and start the HelpSpotQueue service and the HelpSpotSchedule service.

2.2. HelpSpot 5.4.1 Language String Additions

If you have a HelpSpot installation with a custom language pack and you are planning to upgrade to HelpSpot 5.4, there are a few additional steps you need to take. In particular, you will need to add language strings and files to ensure that the language pack works as expected in the new version of HelpSpot.

lg.general.php

define('lg_close_softphone', 'Close Softphone');
define('lg_admin_manage_subscription', 'Manage Subscription');

lg.pg.admin.ai.php

define('lg_admin_openai_label_api_language_ex', 'The language used when translating customer requests using the HelpSpot AI request history translate function. Learn more <a href="https://support.helpspot.com/index.php?pg=kb.page&id=675">here</a>.');

lg.pg.admin.php

define('lg_home_admin_licusers', 'Staff/%s Licenses');
define('lg_home_admin_licsupport', 'Subscription Period');
define('lg_home_admin_subscription', 'Subscription');

lg.pg.admin.settings.php

define('lg_admin_settings_call_center', 'Call Center');
define('lg_admin_settings_call_center_label', 'Call Center Softphone');
define('lg_admin_settings_call_center_ex', 'Select a softphone provider to enable the multi-frame call center mode.');
define('lg_admin_settings_call_center_link', 'Go to call center view');

lg.pg.ajax_gateway.php

define('lg_translate_error', 'There was an error translating your note:');

lg.pg.installer.php

define('lg_inst_welcomereq', '
Welcome to HelpSpot!
Don\'t forget to visit our Knowledge Books [1] for documentation and usage tips. Feedback is always welcome, so drop us a line customer.service@userscape.com or submit a request [2].
I would also recommend taking a look through the settings under Admin -> Settings. There are many features there which will allow you to customize HelpSpot. To give one example, if you want to add custom fields to track additional data with requests, you can add them from Admin -> Custom Fields.
For a quick overview on how to get started, try the getting started guide:
[https://support.helpspot.com/index.php?pg=kb.book&id=11](https://support.helpspot.com/index.php?pg=kb.book&id=11). If you have any questions or need help figuring out how to do something in HelpSpot, don’t hesitate to let us know - we’re always here to help!
Sincerely,
Ian Landsman, Founder
[1] - [https://support.helpspot.com/index.php?pg=kb](https://support.helpspot.com/index.php?pg=kb)
[2] - [https://support.helpspot.com/index.php?pg=request](https://support.helpspot.com/index.php?pg=request)');

2.3. HelpSpot 5.4 Language String Additions

lg.general.php

define('lg_refer', 'Referral Program');
define('lg_videos', 'Video Training');
define('lg_ai_shortcut', 'Type ! for autocompletion');
define('lg_jsmenu_noai', 'HelpSpot AI must be enabled by an admin');
define('lg_jsmenu_aiprocessing', 'HelpSpot AI is Processing Your Request');
define('lg_jsmenu_rewriteasakb', 'Rewrite as a KB');
define('lg_jsmenu_summarizerequesthistory', 'Summarize Request History');
define('lg_jsmenu_summarize', 'Summarize');
define('lg_admin_ai_nav', 'HelpSpot AI');
define('lg_admin_ai_prompts', 'AI Prompts');
define('lg_admin_ai_settings', 'AI Settings');
define('lg_not_mailbox_check_error', 'A mailbox has not been checked successfully. Error On Mailbox ID: ');
define('lg_ai_input_too_short', 'The input text is too short. Please enter at least 40 characters.');

lg.pg.admin.ai.php

Completely new file. This should be copied from helpspot/helpspot/lang/english-us/lg.pg.admin.ai.php to your custom language pack.

lg.pg.admin.mailboxes.php

define('lg_admin_mailboxes_last_import_success', 'Last Successful Check');

lg.pg.admin.prompts.php

Completely new file. This should be copied from helpspot/helpspot/lang/english-us/lg.pg.admin.prompts.php to your custom language pack.

lg.pg.admin.settings.php

define('lg_admin_settings_workers_high_length', 'High Queue Length (Email Sending)');
define('lg_admin_settings_workers_high_length_info', 'This queue is used to send out emails from HelpSpot. If you consistently see a large number of items in this queue you may need to check your queue workers or contact HelpSpot Support.');
define('lg_admin_settings_workers_default_length', 'Default Queue Length (Mailbox checks, automations etc.)');
define('lg_admin_settings_workers_default_length_info', 'This is the default queue that handles most jobs in HelpSpot. Seeing some jobs in this queue at any time is normal. If there are thousands of jobs in this queue consistently there may be an issue.');
define('lg_admin_settings_ss_no_dash_redactor', 'Redact Social Security numbers with no dashes (xxxxxxxxx) from message bodies');
define('lg_admin_settings_ss_no_dash_redactor_descr', 'New requests & updates to existing requests are checked to see if they contain Social Security numbers without dashes. Please note that custom fields are not checked as a part of this feature.');

lg.pg.reports.php

define('lg_reports_request_category', 'Request Category');

lg.pg.request.php

define('lg_request_translate_history', 'Translate');
define('lg_request_translation_loading', 'Loading Translation');
define('lg_request_translation_error_title', 'Translation Failed');
define('lg_request_translation_error', 'Your request history item failed to translate');

2.4. HelpSpot 5.3.1 Language String Additions

If you have a HelpSpot installation with a custom language pack and you are planning to upgrade to HelpSpot 5.3.1, there are a few additional steps you need to take. In particular, you will need to add language strings and files to ensure that the language pack works as expected in the new version of HelpSpot.

lg.pg.admin.settings.php

define('lg_admin_settings_cc_redactor', 'Redact credit card numbers from message bodies');
define('lg_admin_settings_cc_redactor_descr', 'New requests & updates to existing requests are checked to see if they contain credit card numbers. Please note that custom fields are not checked as a part of this feature.');
define('lg_admin_settings_ss_redactor', 'Redact Social Security numbers from message bodies');
define('lg_admin_settings_ss_redactor_descr', 'New requests & updates to existing requests are checked to see if they contain Social Security numbers. Please note that custom fields are not checked as a part of this feature.');
define('lg_admin_settings_request_interface', 'Request Interface');
define('lg_admin_settings_file_attachments', 'File Attachments');
define('lg_admin_settings_filters', 'Filters');

lg.pg.installer.php

define('lg_inst_checkmysql4', 'MySQL 5.6 or greater required.');

lg.pg.request.php

define('lg_request_drilldown_value_error', 'no longer has a valid value. This is most likely due to the removal of options by an administrator. Please reset this field to a valid value.');

3. Upgrading Dependancies

3.1. Upgrading PHP on Windows

In order to upgrade your PHP version, you will want to download the latest compatible version of PHP from the Windows PHP distribution site: http://windows.php.net/download/.

Check the system requirements page for the most up to date information on the latest version of PHP supported by HelpSpot: https://helpspot.com/requirements. At the time of this KB edit, the latest version is 8.1 NTS x64 (for IIS) or 8.1 TS x64 (for Apache).

After extracting the download, make a backup of your current PHP folder found in your HelpSpot installation. If you initially installed using the Legacy Installer (.exe) your HelpSpot installation can be found under C:\Program Files (x86)\helpspot and the PHP folder will be at C:\Program Files (x86)\helpspot\php. If you used the modern, step-by-step Windows instructions, your HelpSpot installation will likely be at C:\inetpub\wwwroot, and the PHP folder will be at C:\PHP.

Stop your webserver before beginning any of the steps outlined below.

Major-version Updates vs Minor-version Updates

Performing major-version upgrades (such as PHP 8.0 to 8.1) requires a slightly different approach than minor-version updates (such as PHP 8.0.1 to 8.0.5).

Minor-Version Upgrades

For minor-version upgrades, we don't want to overwrite the entire PHP directory with the updated version, as there are HelpSpot specific files and settings that would be lost. Instead, the easiest approach is to copy all of the files (not folders) from the root directory of the extracted PHP download into the root directory of your existing PHP folder. Then do the same within each of the PHP subfolders. This will preserve the HelpSpot customizations but get you running on the latest binaries.

Major Version Upgrades

For major-version upgrades, you can rename the existing PHP root directory and create a new, empty "PHP" root directory in the same parent folder, then move the newly extracted PHP files into the new PHP directory. You can then copy the below files and folders from the old, renamed PHP directory into the new PHP root:

/PHP/cacert.pem
/PHP/tmp/ (entire directory)

Because major-version upgrades require new SQL drivers, you will also need to download the correct SQL Server drivers for your new PHP version from Microsoft's GitHub repository: https://github.com/microsoft/msphpsql/releases/latest

After you have completed this process, start your webserver again, and you should be running the latest version of PHP. You can confirm this by opening a command prompt in your PHP root directory and entering the command: php -v

Moving PHP From Legacy Configuration to Modern Configuration

If you are moving your PHP installation from the old Program Files (x86)-based install location to the current C:\PHP root directory, there are a few more changes you'll need to make for the system to recognize the new configuration.

IIS will have a Handler Mapping telling the server where the PHP executable is found. You will need to edit the exisitng PHP Fast CGI handler mapping to point to the php-cgi.exe in the new PHP folder path. This is performed within the IIS management console by selecting the server in the left nav tree and double-clicking the Handler Mappings icon in the main pane.

The php.ini file contains some HelpSpot-specific directives pointing to the legacy paths which will need to be updated to their new paths, as shown below.

curl.cainfo="C:\Program Files (x86)\helpspot\php\cacert.pem" becomes curl.cainfo="C:\PHP\cacert.pem"
openssl.cafile="C:\Program Files (x86)\helpspot\php\cacert.pem" becomes openssl.cafile="C:\PHP\cacert.pem"
upload_tmp_dir="C:\Program Files (x86)\helpspot\php\tmp" becomes upload_tmp_dir="C:\PHP\tmp"

The system's Environment Variables will need to be updated to reflect the new PHP location. Right-click on the computer in a File Explorer window and select Properties from the context menu. Click Advanced System Settings in the left nav of the management window and then click the Environment Variables button at the bottom of the Advanced Properties window.

Within the Environment Variable editor window, you should reference the lower pane for System Variables. Within this pane, you will need to first select the PATH variable and edit the PHP entry to reflect the new PHP folder path. You can then locate the PHPRC variable and edit it to point to the new PHP folder path. Note that you will need to close and reopen any CMD windows in order for them to detect the new Environment Variable paths.

4. Upgrading From HelpSpot 4.9.5 To HelpSpot 5.x

4.1. Updating to HelpSpot 5 - Linux

Updating to HelpSpot 5

Note: Updating to HelpSpot 5 requires the latest version 4 be installed first (4.9.5).

The general steps for updating HelpSpot 4 to HelpSpot 5 on linux are:

Ensure your server environment meets the minimum requirements for HelpSpot 5
Backing up HelpSpot 4 files and database
Removing HelpSpot 4 CRON tasks
Running HelpSpot 5 Update Tasks
Restoring Files and Customizations
Configuring HelpSpot 5 CRON tasks
Configuring HelpSpot 5 queue worker

Requirements

General server requirements for HelpSpot 5 can be found here. It should be noted that HelpSpot 5 no longer requires the IonCube loader php module. It also now requires PHP 7.4 which means most installations will need to upgrade their PHP version.

Backing up HelpSpot 4

It's important to backup HelpSpot site files and the database prior to updating.

This allows you to roll back if needed
This allows you to copy file-based customizations made to HelpSpot 4 (such as portal templates) and apply them to HelpSpot 5

If attachments are stored on-disk (recommended!), it's not necessarily needed to backup those attachment files. You may not wish to back those up if you have limited disk space or if the attachments are large and copying them takes too much time. Moving them will be enough!

Backing up the HelpSpot 4 database from MySQL/MariaDB/Percona can be run using a commmand similar to this:

mysqldump -u user -p \
    --max_allowed_packet=1073741824 \
    --single-transaction \
    --default-character-set=utf8mb4 \
    helpspot_db \
    | gzip > /path/to/backup/helpspot_db.sql.zip

Larger databases may receive errors about the max allowed packet size, or "mysql has gone away". These errors are usually prevented by increasing the max-allowed-packet configuration for the server to its maximum value, generally under the [mysqld] section of the my.cnf file.

The above example sets max_allowed_packet on the mysqldump command, but that does not affect the server-side configuration for max_allowed_packet. That setting exists on both the mysql client (mysqldump) and mysql server (mysqld) sidses.

Remove HelpSpot 4 CRON Tasks

You should remove all HelpSpot 4 CRON tasks. HelpSpot 5 has a newer way to run periodic tasks. These still use CRON, but HelpSpot 5 uses a single command rather than multiple CRON tasks.

CRON tasks may be in a few places. The most common locations are:

Within /etc/crontab
A file in /etc/cron.d
A user-specific cron task edited via sudo crontab -u some-user -e

The default HelpSpot 5 CRON tasks (that you should disable/remove) are to run the tasks.php and tasks2.php file, and look similar to this:

* * * * * php /var/www/helpspot/tasks.php
* * * * * php /var/www/helpspot/tasks2.php

Updating to HelpSpot 5

After backing up the HelpSpot 4 files and database, and ensuring HelpSpot is not running (disabling CRON tasks and perhaps putting HelpSpot into maintenance mode), you can update to HelpSpot 5.

The steps to update to HelpSpot 5 are as follows:

Update the HelpSpot files
Configure your web server
Update HelpSpot (this will affect your database)

Update HelpSpot Files

You'll need to replace the HelpSpot 4 files with the HelpSpot 5 files just like with any HelpSpot update. We recommend moving the HelpSpot 4 code base and then replacing that directory with HelpSpot 5's files (rather than copying/overwriting the files directly).

# Let's assume helpspot 4 is installed at /var/www/helpspot
cd /var/www
sudo mv /var/www/helpspot /var/www/helpspot_old

# Let's assume helpspot 5 is located at ~/helpspot_5.0.xx
sudo mv ~/helpspot_5.0.xx /var/www/helpspot

# Finally, keep HelpSpot 4's config.php file:
sudo cp /var/www/helpspot_old/config.php /var/www/helpspot/config.php

# Likely you'll want to ensure all files are owned by the web server user
# such as "www-data" or "apache" or "httpd":
sudo chown -R www-data:www-data /var/www/helpspot

Configure the web server

The web server configuration should be updated to change the web root to HelpSpot's public directory, e.g. /var/www/helpspot/public

More details and examples can be found in the Linux Server Administrations documentation

Update HelpSpot

Updating HelpSpot involves creating a new .env file, and then updating the database. The steps to do so are as follows:

# NOTE: We recommend running all commands
# as the same user that runs the web server, such as
# www-data, apache, or httpd:
# e.g. "sudo -u www-data php hs config:convert"

# !! Ensure your HelpSpot 4 config.php file is present
# in the root of your helpspot installation,
# e.g. /var/www/helpspot/config.php

# This will convert your config.php file to a .env file
php hs config:convert

# Generate a new APP_KEY, used for encryption
php hs install:key

# Update HelpSpot's database
php hs update --yes

The above converts the config.php file used in HelpSpot 4 to a .env file usable for HelpSpot 5. However you can also copy/rename the .env.example file and change settings there as needed instead.

The php hs update --yes command will run tasks against your database and may take some time to make certain changes, depending on your database size. A database with multiple millions of request history rows can take multiple (single digit) hours.

File Permissions

You will also want to be sure all files are owned as the user running the web server. This is typically a user such as "www-data", "apache" or "httpd". On other servers (cPanel, Plesk, Forge), the user will change per your setup. To change file ownership, run the following:

# We assume the web server runs as user www-data
# and helpspot is installed at /var/www/helpspot
sudo chown -R www-data:www-data /var/www/helpspot

Servers using SELinux may have extra steps to ensure the web server can write to HelpSpot's files. See this video for some examples on modifying SELinux permissions.

Restoring Files and Customizations

We'll want to restore certain files to the proper location, notably:

Attachment files, if saved to disk (recommended) rather than the database
Portal files and customizations
Custom code and pages (e.g. Live Lookup, items in the custom_code and custom_pages directories, BlackBox or AD authentication files)

Attachments

Attachments from emails are most likely being saved to the disk drive. In HelpSpot 4, these were saved into the data/documents directory by default. In HelpSpot 5, the default location changed to storage/documents

Attachments from your HelpSpot 4 installation should be moved to the updated location. However, check the configured Attachment Storage Location in HelpSpot's Admin area found in Admin > Settings > System to see where they are being saved.

Since the Attachment Storage Location is configurable, these locations may be different for you.

# Move HelpSpot 4's attachments to the new location
sudo mv /var/www/helpspot_old/data/documents/* /var/www/helpspot/storage/documents/

# Ensure permissions are set to the web server's user, such as 
# www-data, apache, or httpd
sudo chown -R www-data:www-data /var/www/helpspot/storage

Portals

First, we'll cover changes to the primary portal:

The custom_templates directory for the primary portal has been moved from the root directory (/path/to/helpspot/custom_templates) to the public web root /path/to/helspot/public/custom_templates.

So, if that directory used to be located at /var/www/helpspot/custom_templates, those customizations should be restored to /var/www/helpspot/public/custom_templates.

For secondary portals, there are several changes:

Secondary portal directories should be moved from the into the public directory - for example, from /path/to/helpspot/some-portal to /path/to/helpspot/public/some-portal.
The configuration for secondary portals (Admin > Customize > Secondary Portals) should be updated with the new File Directory Path setting (to include the public directory)
Saving changes to any Secondary Portal should update the portal's file-based configuration to HelpSpot 5's standards
There is no longer a config.php file needed within portal directories
The index.php file created has been changed. Saving the secondary portals settings will generate a new index.php file.

There are more details about HelpSpot 5 Portal changes here. These include:

Configuration changes
Updates to portal templates

Custom Scripts and Pages

Custom Code

The custom_code directory has been moved to the public directory as well. If that directory used to live in /var/www/helpspot/custom_code, it should be moved to /var/www/helpspot/public/custom_code.

The custom_code directory usually contains BlackBox and/or Active Directory authentication files as well.

Any other scripts that need to be accessed by HTTP requests (such as live lookup scripts) should also be moved into the public directory.

Custom Pages

The custom_pages directory has been moved from the base HelpSpot directory into the helpspot directory. If it used to be located at /var/www/helpspot/custom_pages, custom pages should be moved into /var/www/helpspot/helpspot/custom_pages.

Configuring HelpSpot 5 CRON tasks

The following CRON task should be set for HelpSpot 5:

# File /etc/cron.d/helpspot
* * * * * www-data /usr/bin/php /path/to/helpspot5/hs schedule:run

Where and how you configure this CRON task can vary and is up to you. The above example shows adding a new file in /etc/cron.d/helpspot, which also allows you to define what system user runs the CRON task.

You'll likely need to adjust the user and file path used for your system. For more details, see the Linux Administration documentation on CRON tasks

Configuring HelpSpot 5 queue worker

HelpSpot 5 uses a built-in queue system that allows certain tasks to be run in the background. This includes sending and receiving emails.

Previously, HelpSpot would send emails immediately upon updating a request. This feature pushes that job into a queue, allowing the email sending to happen in the background, reducing the possibility of issues or timeouts when sending multiple emails.

Setting up the queue worker is required for HelpSpot 5. Please see our Queue Worker Configuration section within the Linux Administration documentation to see how.

4.2. Updating to HelpSpot 5 - Windows

Updating to HelpSpot 5 on Windows

Note: Updating to HelpSpot 5 requires the latest version 4 be installed first (4.9.5).

Updating to HelpSpot 5 on windows involves these basic steps. Note: this update will upgrade your windows server to PHP version 7.4. If you run custom PHP scripts on your HelpSpot server it is advisable to check on compatibility.

Backup your HelpSpot files and database
Download and run the HelpSpot 5 installer / upgrader
Restore any customization that were not in the custom_code, custom_pages or custom_templates folders
Restoring any Secondary Portals

Backing up HelpSpot files and database

The HelpSpot updater will backup the site files, however you may want to create your own backup by copying the HelpSpot site files, typically found at C:\Program Files (x86)\helpspot\helpspot.

Backing up a SqlServer database is best done in Sql Server Management Studio, available as a task on the HelpSpot database.

Backing up a MySQL database can be done using the mysqldump.exe command, available as part of the MySQL installation. If you use the bundled MySQL with HelpSpot, the mysqldump.exe command will likely be available at C:\Program Files (x86)\helpspot\mysql\bin\mysqldump.exe.

An example mysqldump.exe command to use is as follows, best run in cmd.exe instead of PowerShell:

mysqldump.exe -u root -p --max_allowed_packet=1073741824 --default-character-set=utf8mb4 --single-transaction helpspot_db > .\helpspot_db.sql

Restoring Customizations

The HelpSpot installer/updater will restore customizations found in the custom_code, custom_pages, and custom_templates directories.

However, if you have customizations in other locations, you will need to restore those yourself. You can take them from your own backups, or from the "previousVersionBackup" directory created by the installer. That is most likely at C:\Program Files (x86)\helpspot\backup/previousVersionBackup.

Restoring Secondary Portals

Secondary portals can be restored to their original location from the previousVersionBack directory (most likely found at C:\Program Files (x86)\helpspot\backup/previousVersionBackup). Once they are back in their location, a helper command can be used to move them to a new location if needed for HelpSpot 5.

For example, if a secondary portal used to be located at C:\Program Files (x86)\helpspot\helpspot\my-portal, then it can be copied back to that location after updating to HelpSpot 5.

Once Secondary Portals are back in place, you can run the following command, which will move and reconfigure the portal as needed. This can be fun in cmd.exe or PowerShell:

cd C:\Program Files (x86)\helpspot\helpspot
..\php\php.exe -c ..\php\php.ini hs portal:migrate --dry-run
..\php\php.exe -c ..\php\php.ini hs portal:migrate

The --dry-run flag can be used to preview what portals will be moved/updated. If it reports that a portal will not be moved, it means that HelpSpot cannot determine where it should be placed and can be moved/updated manually. You can move the directory to a location of your choosing, and then update file paths in the HelpSpot admin area when editing that Secondary Portal.

4.3. Updating to HelpSpot 5 - Windows Manual Update IIS/MSSQL

Update PHP

Stop IIS
Download the latest NTS build of PHP 8 for x86 - https://windows.php.net/download/
Extract the files to a temporary location
Backup your current PHP directory located C:\Program Files (x86)\helpspot\php
Copy the new PHP 8 installation to C:\Program Files (x86)\helpspot\php
Copy the php.ini file from your php backup folder to your new php folder
Download the latest SQL Server php extensions from https://github.com/microsoft/msphpsql/releases and move the x86 dll files to the C:\Program Files (x86)\helpspot\php\ext directory

Edit your php.ini file as follows
Remove the ioncube loader line:

[Zend]
zend_extension="C:\Program Files (x86)\helpspot\ioncube\ioncube_loader_win_7.2.dll"

Update the sql server extension file names:

extension=php_sqlsrv_72_nts.dll
extension=php_pdo_sqlsrv_72_nts.dll
should become
extension=php_sqlsrv_83_nts.dll
extension=php_pdo_sqlsrv_83_nts.dll

Update HelpSpot Files

Download and unpack the latest helpspot zip package from https://store.helpspot.com
Backup your current helpspot directory in C:\Program Files (x86)\helpspot\helpspot\
Create a new C:\Program Files (x86)\helpspot\helpspot\ directory and place the HelpSpot 5 files in that directory.
Copy the config.php from your HelpSpot 4 backup to C:\Program Files (x86)\helpspot\helpspot\
Copy the \custom_templates directory from your HelpSpot 4 backup to C:\Program Files (x86)\helpspot\helpspot\public\custom_templates
Copy the \custom_code directory from your HelpSpot 4 backup to C:\Program Files (x86)\helpspot\helpspot\public\custom_code
Copy the \custom_pages directory from your HelpSpot 4 backup to C:\Program Files (x86)\helpspot\helpspot\helpspot\custom_pages
Copy the \data\documents directory to C:\Program Files (x86)\helpspot\helpspot\storage\documents

Move IIS Site Directory

Open the IIS Manager
If your HelpSpot site is hosted in a virtual directory click on it and then select "basic settings" from the actions tray
Change the physical path to the public subdirectory in your installation
If you HelpSpot site is hosted at the root of the site change the physical path in the "basic settings" for the site.

Add your handler mapping

In the IIS Manager go the handler mappings for your virtual folder or site.
Add a new Module Mapping Request path: *.php
Module: FastCGIModule
Executable: "C:\Program Files (x86)\helpspot\php\php-cgi.exe"
Name: PHP

Add Default Document

In the IIS Manager go the default Documents for your virtual folder or site.
Add a new default document of index.php

Setup IIS URL Rewrite Extension

Download the extension from https://www.iis.net/downloads/microsoft/url-rewrite
Install the extension.

Modify Storage File Permissions

Modify the file permissions on C:\Program Files (x86)\helpspot\helpspot\storage to allow full access to the user running your application pool. By default this is the IUSR.
Create a php tmp folder in C:\Program Files (x86)\helpspot\php\tmp\ and give full permission to the running your application pool. By default this is the IUSR.

Update HelpSpot

Open the command line and cd to C:\Program Files (x86)\helpspot\helpspot
Convert your config file: ..\php\php.exe hs config:convert
Generate a app key: ..\php\php.exe hs install:key
Update HelpSpot: ..\php\php.exe hs update

Setup Your Queue

Navigate to C:\Program Files (x86)\helpspot\helpspot\helpers\windows
Modify the first two lines to reflect your paths in your installation. By default these will be:
set AppPath=C:\Program Files (x86)\helpspot\helpspot
set PHPPath=C:\Program Files (x86)\helpspot\php
Run setup.bat. This will create your supervisor.conf file and install your queue services

4.4. 508 Portal Template Changes

For HelpSpot v5 we've updated the portal themes to better accommodate section 508 compliance which makes it more accessible to people with disabilities.

The portals didn't need a lot of changes to make the necessary improvements but we wanted to highlight all that was required so you can adjust any portals that you may have customized.

The first main change was the colors in the CSS. The .required and .tag-sep classes need more contrasting colors to go with the backgrounds. For example, in the required class on the default portal, it had a color of red, and now this is changed to #b05050 which gives a better contrast on the white background.

The next change is all tabindex attributes have been removed from form fields, and all fields now have a proper id attribute and matching label.

Finally, in the footer, the search input needed a label.

Those are the primary changes if you'd like to update yours and to help you check your compliance there are a few browser plugins that will automatically check each page and give you a report. One of the most popular is called WAVE.

4.5. HelpSpot 5 Portal Changes

Form CSRF Fields

A number of portal templates need a csrf token added after the form tag <?php echo csrf_field(); ?> for added security. These updates will need to be made to any portal files that have been customized. The addition needed in each file is highlighted and the surrounding code is provided for context.

kb.page.tpl.php

<form action="index.php?pg=vote.helpful" name="votehelpful" method="POST">
<input type="hidden" name="xPage" value="<?php echo $this->page['xPage'] ?>">
<?php echo csrf_field(); ?>
</form>
<form action="index.php?pg=vote.nothelpful" name="votenothelpful" method="POST">
<input type="hidden" name="xPage" value="<?php echo $this->page['xPage'] ?>">
<?php echo csrf_field(); ?>
</form>

login.forgot.tpl.php

<form action="<?php echo route('portal.password.email') ?>" method="post">
<?php echo csrf_field(); ?>
<?php if( session('status') ): ?>

login.reset.tpl.php

<form action="<?php echo cHOST.'/index.php?pg=login.reset' ?>" method="post">
<?php echo csrf_field(); ?>
<?php if( session('status') ): ?>

loginbar.tpl.php

request.check.tpl.php

<?php if (!empty($this->get_id)) : ?>
<form action="index.php?pg=request.check" method="post" enctype="multipart/form-data">
<?php echo csrf_field(); ?>
<input type="hidden" name="accesskey" value="<?php echo $this->get_id ?>" />
...

request.tpl.php

<?php /* Any field names listed in the 'required' hidden field will be checked by HelpSpot to make sure they're not empty */ ?>
<input type="hidden" name="required" value="sEmail,fullname" />

Request Check Page

The request check page has a new login / password reset flow. If you have customized this page you will need to make these additional edits.

request.check.tpl.php

Find this area:

    <form action="index.php?pg=login" method="post">
        <p><b><?php echo lg_portal_req_login ?>:</b></p>
        
        <p><label for="login_email" class="datalabel"><?php echo ($this->hd_requestCheckAuthType == "internal" ? lg_portal_req_loginemail : lg_portal_req_loginusername) ?></label><br />
            <?php echo $this->helper->showError('login_email','<br />') ?>
            <input type="text" name="login_email" id="login_email" size="40" maxlength="100" tabindex="102" value="<?php echo $this->get_login_email ?>" autocomplete="off" /><br />
            <?php if($this->hd_requestCheckAuthType == "internal"): ?>
            <?php //only show this password retrieval link if we're using internal authentication on the portal ?>
                <span id="retrievePortalPasswordLink">(<a href="#" onclick="RetrievePortalLoginPassword();return false;"><?php echo lg_portal_req_emailpassword ?></a>)</span>
            <?php endif; ?>
        </p>        

        <p><label for="login_password" class="datalabel"><?php echo lg_portal_req_loginpassword ?></label><br />
            <input type="password" name="login_password" id="login_password" size="40" maxlength="100" tabindex="103" value="" autocomplete="off" />
        </p>
        
        <p>
            <input type="submit" name="submit" value="<?php echo lg_portal_req_loginbutton ?>" tabindex="104" />
        </p>
    </form>

Replace it with this

    <form action="index.php?pg=login" method="post">
        <?php echo csrf_field(); ?>
        <p><b><?php echo lg('lg_portal_req_login') ?>:</b></p>

        <p><label for="login_email" class="datalabel"><?php echo $this->hd_requestCheckAuthType == 'internal' ? lg('lg_portal_req_loginemail') : lg('lg_portal_req_loginusername') ?></label><br />
            <?php echo $this->helper->showError('login_email', '<br />') ?>
            <input type="text" name="login_email" id="login_email" size="40" maxlength="100" value="<?php echo $this->get_login_email ?>" autocomplete="off" /><br />
        </p>

        <p><label for="login_password" class="datalabel"><?php echo lg('lg_portal_req_loginpassword') ?></label><br />
            <input type="password" name="login_password" id="login_password" size="40" maxlength="100" value="" autocomplete="off" />
        </p>

        <p>
            <input type="submit" name="submit" value="<?php echo lg('lg_portal_req_loginbutton') ?>" />
            <?php if ($this->hd_requestCheckAuthType == 'internal') : ?>
                <span style="padding: 14px 0px; display: inline-block;"><a href="index.php?pg=login.forgot"><?php echo lg('lg_portal_req_emailpassword') ?>?</a></span>
            <?php endif; ?>
        </p>
    </form>
    <div style="text-align: center;">
        <hr width="80%">
        <div style="margin: 0 auto; padding: 10px;">
            <?php if ($this->hd_requestCheckAuthType == 'internal') : ?>
                <?php //only show this password retrieval link if we're using internal authentication on the portal
                        ?>
                <a href="index.php?pg=login.create"><?php echo lg('lg_portal_req_logincreate') ?></a>
            <?php endif; ?>
        </div>
    </div>

CSS Changes

If you have customized your portal css (css.blue.tpl.php, css.grey.tpl.php etc) you will need to make these CSS changes in those customized files.

Calendar CSS changes to all portal template CSS files:

Remove:

@import "<?php echo $this->cf_primaryurl ?>/static/js/jscal2/css/jscal2.css";

Add:

/* Import styles for calendar used in date/datetime custom fields */
@import "cf_primaryurl ?>/static/js/datetimepicker/css/mobiscroll.jquery.min.css";
@import "cf_primaryurl ?>/static/js/popup/css/mobiscroll.jquery.min.css";

Add the following styles for file attachment display in requests.

.file-extension {
    display: inline-block;
    margin: 5px 0;
}
.file-name {
    display: inline-block;
    padding: 0 10px;
    margin-bottom: 5px;
}

JS Changes

If you have made JS customizations to js.tpl.php you will need to change this line:

document.write('<script type="text/javascript" src="<?php echo $this->cf_primaryurl.elixir('js/helpspot.portal.js') ?>"></script>');

to this:

document.write('<script type="text/javascript" src="<?php echo $this->cf_primaryurl.mix('static/js/helpspot.portal.js') ?>"></script>');

4.6. HelpSpot 5 Admin Theme Changes

Helpspot 5 introduces a new admin / workspace interface. With this change comes changes to how admin area themes are handled. In the past, you would create a new admin theme and customize the js and css in order to apply your customization. Those admin themes now need to be migrated to the custom JS and CSS boxes found in Admin > Customize > Customize Admin.

CSS customization

The css customization setting will override default styles. So for example if you wanted to make the new request button green, you can target that element with a normal css class.

a.btn.newrequest {background-color: #65ac5d;}

JS customization

Javascript can be added for making programmatic changes to the HelpSpot admin area. JQuery is available under the $jq alias.

4.7. HelpSpot 5 Attachment Storage Location Change

Default attachment storage directory data/documents (e.g. /var/www/helpspot/data/documents has been moved to storage/documents (e.g. /var/www/helpspot/storage/documents.

For upgrades, you should:

Move directories/files from data/documents into storage/documents
Update HelpSpot's configuration to set the Admin > Settings > System > Attachment File System Directory to the storage/documents location, e.g. /var/www/helpspot/storage/documents

The data directory can be deleted in HelpSpot 5+.

4.8. Language File Changes

HelpSpot 5 has updates and changes to the language files for the default language english-us.

The HelpSpot 5 code will have the latest language strings in the files located within the helpspot/helpspot/lang/english-us directory.

New Language Files

The following language files are new to HelpSpot 5:

lg.pg.admin.customize.php
lg.pg.admin.tools.jobsmgmt.php
lg.pg.tips.php

Removed Language Files

The following language files were removed in HelpSpot 5:

lg.pg.emailstaff.php
lg.pg.forums.php
lg.pg.getstarted.php

Updated Language Files

The following outlines language string changes, additions, and removals for each affected file. You can find all changes documented here.

5. Installation Troubleshooting

5.1. APP_URL is invalid

Error Description:

APP_URL is invalid.

Causes:

.env File is not configured correctly

The .env file needs to have an APP_URL defined. The APP_URL is the url that resolves to the public folder of your helpspot installation. It should be in standard http URL format.

Examples:

Secure Subdomain DNS

APP_URL=https://helpspot.company.com

URL with port

APP_URL=http://myinternalapp:8080

IP address

APP_URL=http://192.168.0.1

DNS or Webserver Configured Incorrectly

Proper DNS configuration and web server configuration is required in addition to an accurate APP_URL setting. The APP_URL only controls how HelpSpot builds URLs. If your DNS is not pointing to the server or if you web server is not configured to receive connections and direct the browser to the public folder the APP_URL will not work properly.

Invalid or misconfigured SSL certificate

If your server has an invalid or misconfigured SSL certificate you may receive this error along with details on the nature of the issue.

5.2. APP_KEY Missing during installation

Error Description:

APP_KEY is not defined.

Causes:

.env File is not configured correctly

The .env file needs to have an APP_KEY defined. APP_KEY is used for encryption inside of HelpSpot. To generate your app key run this command using the HelpSpot command like tool.

php hs install:key

5.3. Database Connection Error During Installation

Error Description:

HelpSpot can not connect to the database. Please check your database settings in the .env file.

Causes:

.env File is not configured correctly

This error could be caused by having improper information in your .env configuration file. The follow variables need the correct values before the installer can continue:

DB_CONNECTION - one of mysql or sqlsrv.
DB_HOST - The hostname or ip of your database server
DB_PORT - For SQL Server the default for this is 1433. For mysql the default port is 3306.
DB_DATABASE - This is the name of your HelpSpot database. This database needs to be created prior to starting the HelpSpot installation.
DB_USERNAME - The username to use when connecting to the database. This user needs to be configured with full rights to the DB_DATABASE defined.
DB_PASSWORD - The password for the DB_USERNAME defined.

Firewall Configuration

Configured firewalls may block connections to your database server if you are using an external database server. A good way to test connectivity is to telnet to the DB_HOST and DB_PORT you have defined.

telnet my.db.server.com 3306

5.4. Incorrect PHP Version

Error Description:

If you receive an error that your php version is incorrect during installation there are a couple of possible issues.

Causes:

Wrong PHP Version Installed

First, it could be that your have an incompatible version of PHP installed and you need to switch the version of PHP installed. The directions for your OS will include instructions on how to install the appropriate version.

Wrong Command Line PHP version being used

You can have a different version of command line PHP running (which the installer uses) that what is linked to your web server. HelpSpot uses command line PHP for the install process and well as for background processes after installation. You will need to make sure that your command line version of PHP is compatiable.

5.5. HelpSpot's 'storage' dir is not writable

Error Description:

If you receive an error that your HelpSpot's 'storage' directory is not writable there are a couple of possible issues.

Causes:

File Permissions and Ownership

File permissions and ownership need to allow reading, writing and modifying of files in the storage directory of HelpSpot.

Windows with IIS

On windows with IIS the iUSR user should be granted full control of the storage directory and all subdirectories.

Ubuntu

On Ubuntu the web server will by default be running under the user www-data. So running sudo chown -R www-data:www-data storage/ on the storage directory should solve most permissions issues.

CentOS / Redhat

On CentOS / Redhat the web server will by default be running under the user apache. So running sudo chown -R apache:apache storage/ on the storage directory should solve most permissions issues.

HelpSpot 4 - Installation & Setup

1. Minor Version Upgrades (v4)

These instruction apply to minor version upgrades. For example: v4.5.1->v4.8.1 or v5.0.45->5.0.58. For major version upgrades (v4 to v5) see the separate upgrade documentation as the process is a bit different.

The update process for windows installations and and Linux installations are separate on HelpSpot 4 and greater.

Windows

Before running the windows update executable ensure that you have backed up your database and HelpSpot files. You can then download and run the windows updater executable. This updater will perform all of the upgrade steps for you via the graphical wizard.

Linux

The installer will make database changes during an upgrade. If something goes wrong the only way to roll back the changes is if you have an up to date backup.

Upgrading Files

Before beginning review the latest system requirements to make sure that the software installed on your server are compatible with the latest version.

After downloading the new version of HelpSpot, move the files to your server and unpack the tar.gz or zip file in a temporary location.

Move your current helpspot install directory to a backup location (we'll need to restore some files from this backup).
Copy your new helpspot package to that same location where HelpSpot was installed

Copy these directories and files back into your production helpspot folder:

File / Directory	Description
config.php	HelpSpot Config File
data/documents	Attachment Storage (may be a different customized folder depending on configuration in Admin > Settings)
custom_code	Custom Code
custom_templates	Custom Portal Templates
custom_pages	Custom Page Code
Any secondary portal sites or other custom code you have defined

Upgrade Database

The best way to upgrade the database is by using command line php. From your HelpSpot directory run:

php hs update

You can find more info on the HelpSpot command line here: The HelpSpot Command Line

2. HelpSpot 4 Overview

Quick Links

From a server administration point of view, HelpSpot 4 has some new important features:

CLI commands available for installing, updating and some specifically for upgrading from version 3 to 4
Support for UTF-8 (no longer just the latin alphabet)
New "data" directory that contains logs and generated files such as email attachment
New variables for the config.php file

Windows

Installing HelpSpot 4 and Updating to HelpSpot 4 requires the provided windows installer file, which installs all dependencies and HelpSpot.

Note that you must update to HelpSpot 4 from version 3.2.12. This may mean updating to that version before updating to HelpSpot 4. Current and past versions of HelpSpot are available for download in the HelpSpot Store.

If you have installed HelpSpot on windows "manually" (without using the provided Windows installer), please contact customer support for help and available update options.

Windows Requirements

Windows users must use the provided HelpSpot installer, which installs all required software, and required PHP modules.

Windows users have the following system requirements as of HelpSpot version 4: Requirements

Linux

Installation

Installing HelpSpot 4 from scratch can now be handled by our installers scripts for linux. Details instructions are provided at https://install.helpspot.com.

Updating

To update from to HelpSpot 4 from previous versions, please see our documentation on Updating to HelpSpot 4.

Note that you must update to HelpSpot 4 from version 3.2.12. This may mean updating to that version before updating to HelpSpot 4. A download of version 3.2.12 will be made available to all customers.

Linux Requirements

Linux server requirement can be found here: Requirements

3. Updating to HelpSpot 4 from Version 3

HelpSpot version 4 improves support for multiple languages and search. Both of these improvements require extra steps from the usual HelpSpot update process when updating to version 4.

Windows Users

As of version 4, Windows users must use the provided Windows installer to update to version 4.

You should fully backup your HelpSpot files before updating to HelpSpot 4.

The following are new requirements for Windows users:

If you have not already, you must update to HelpSpot version 3.2.12 before updating to version 4+
For SqlServer installs, SqlServer 2008+ (SqlServer Version 2005 is no longer supported)
Windows Server 2008+ (Windows Server Version 2003 is no longer supported)
The update may take a bit longer than usual due to the conversion process of the content to the UTF8 character set into a new database. This would present itself in the last steps of installation and may appear as if the installer is stalled.

If you have installed HelpSpot on windows "manually" (without using the provided Windows installer), please contact customer support for help and available update options.

Portal requests: reCAPTCHA

If you use the reCAPTCHA spam catcher on the Portals, you will need to generate a new reCAPTCHA site key. HelpSpot 4 uses Googles reCAPTCHA. You can login and get a reCAPTCHA site key and secret key here.

You can find your current portal spam filter settings and update them within Admin > Settings > Portal. If you have "Captcha Type" set to "reCaptcha", you'll have the ability to update your site/secret keys within the "reCaptcha Service" section of that page.

Linux Users

The basic steps to upgrading from version 3 to 4 include:

If you have not already, you must update to version 3.2.12 before updating to version 4+
Downloading the latest version
Making the new "data" directory writable by the web server
Updating config.php
Creating a new database
Running a migration from old to new database
Installing Sphinx Search (Optional)

Some of the following steps requires the use of the command-line. If you do not have access to the command-line to run the following commands, please contact us to discuss some available options on updating to Version 4!

The following steps and further documentation are the steps to update to HelpSpot 4:

Server Setup - If you need to update your server to a newer PHP
- Linux users can follow the steps provided for configuring Debian/Ubuntu servers or RedHat/CentOS servers.
Download HelpSpot and overwrite current files:
- Run the convert:base command
- Run the convert:requests command
- Run the update command
- Be sure to backup Version 3 and restore any customizations
Install and configure SphinxSearch (optional for advanced users)
- Linux users can follow the steps provided for installing and configuring Sphinx Search on Debian/Ubuntu servers or RedHat/CentOS servers.

Prerequisites

Note that you must update to HelpSpot 4 from version 3.2.12 This may mean updating to that version before updating to HelpSpot 4. Previous versions of HelpSpot are available to all customers.

The base version of PHP required has been changed from PHP 5.3 to PHP 5.6.

This may also mean updating your IonCube loader to be compatible with a newer version of PHP. The process of installing/updating IonCube is outlined in our Server Guide for Debian/Ubuntu and RedHat/CentOS servers.

Note that there is a bug in IonCube version 4. Please update to IonCube version 5 for use with HelpSpot.

Portal requests: reCAPTCHA

Latest HelpSpot Files

HelpSpot files are available for download in the HelpSpot Store.

You should backup your entire HelpSpot installation prior to updating.

You will likely need/want to restore any customizations made to HelpSpot, typically found in the following locations:

All files of any Secondary Portal configured
All files within the custom_templates directory
All files within the custom_pages directory (minus the included "example.php" file)
All files within the custom_code directory (except any example code that comes with HelpSpot, "-base.php" files)
Any customizations to the themes directories and files found within

These have not changed between HelpSpot versions 3 and 4, and should continue to operate normally.

New Data Directory

The new HelpSpot comes with a "data" directory found in the root of the HelpSpot files. This directly will contain logs and generated files such as Sphinx Search configuration, cache files and serve as a place for attachments to be saved.

This directory needs to be writable by HelpSpot. Windows users will have this setup for them automatically by using the Windows installer. Linux users can follow the HelpSpot 4 Server Security documentation to securely allow this directory to be writable.

Update Config.php

The config.php file has new variables which are required for HelpSpot 4. The included "config-empty.php" contains the full set that are expected, and can be used to compare your existing config.php in order to add the new ones.

New variables introduced in HelpSpot 4 include:

cDBCHARSET
cDBCOLLATION
cSEARCHHOST
cSEARCHPORT
cDATADIR
cDEBUG
SEARCH_ENGINE (HS v4.6.7 and greater)

Each of these are set in the following format:

define('VARIABLE_NAME', 'VARIABLE_VALUE');

So, for example, to turn on debugging (show full PHP errors, a new feature of HelpSpot 4), you can set cDEBUG to "true":

define('cDEBUG', true);

Turning on debugging is recommended only for debugging purposes, if you are encountering an error. A typical use case for this might be if you receive a white screen with no output within HelpSpot. Note that php.ini error reporting values may affect whether the HelpSpot debugger can show errors.

Here is the new config.php file and all variables:

/**
 * How To Use This File:
 * 1. Copy and Rename this file to "config.php"
 * 2. Fill out/change necessary database credentials and base URL (cHOST).
 */

/**
 * Database Credentials
 */
define('cDBTYPE',      'mysql');               // 'mysql', 'mssql' or 'postgres_helpspot'
define('cDBHOSTNAME',  '127.0.0.1');           // e.g. '127.0.0.1', 'localhost' or 'db.example.com'
define('cDBUSERNAME',  'helpspot_user');
define('cDBPASSWORD',  'something-random');
define('cDBNAME',      'helpspot_db');

define('cDBCHARSET',   'utf8');                // Use "utf8mb4" for MySQL 5.5.3+
define('cDBCOLLATION', 'utf8_unicode_ci');     // Use "utf8mb4_unicode_ci" for MySQL 5.5.3+
/**
*Define search engine
*/
define('SEARCH_ENGINE', 'database'); //Defaults to database search.
/**
 * SphinxSearch Search Engine
 */
define('cSEARCHHOST', '127.0.0.1');
define('cSEARCHPORT', '9306');

/**
 * General
 */
define('cHOST','http://example.com/helpspot'); // Base URL used within HelpSpot, WITHOUT tailing slash "/"

define('cBASEPATH',   dirname(__FILE__));      // Base file path to HelpSpot
define('cDATADIR',    cBASEPATH.'/data');      // Path to server-writable `data` directory
define('cDEBUG',      false);                  // Setting to true will output errors to the browser and log file

New Database

The HelpSpot version 3 database is encoded in a way that doesn't support all the characters in non-latin alphabets. In order to update to HelpSpot version 4 and support multiple languages and alphabets, follow these steps:

This update will not change your current database, but will copy and convert its data to a new database. Even so, we suggest backing up the current HelpSpot database before proceeding.

There are two main steps to upgrading the database:

1. Creating a new database supporting UTF-8
2. Copying the old database to the new, which also converts existing data to UTF-8

Note that while this process will convert old data to UTF-8, any special characters (non-latin characters) may already be "lost" - characters that appear as "?" in HelpSpot requests, for example, may remain that way. New data, however, will fully support HelpSpot

1. Create a new, empty database which supports UTF-8

HelpSpot requires a database which supports UTF-8. For instructions on creating a database supporting UTF-8, see our documentation on Creating a UTF-8 Database.

Most hosting will give you the ability to define the database parameters needed to make your database support UTF-8. You can usually adjust your database after it's created as well.

Once the database is created, edit the config.php file to add in your NEW database information:

# Example for MySQL database configuration
define('cDBTYPE','mysql')
define('cDBHOSTNAME','localhost');
define('cDBUSERNAME','new_user_name');
define('cDBPASSWORD','new_password');
define('cDBNAME','new_database_name');

2. Convert the old database to UTF-8

This step will take data from the old database, convert it to UTF-8, and put it into the new database. It runs in two steps:

1. First it takes "supporting" data, such as users, knowledge books, forums and more, and converts it.
2. Then it runs through each Request, starting from the newest, and converts each request and related data (request and history, attachments, reminders, reporting data, etc). This step can take a while, so it can be run to first convert the last 90 days (or so) of data, and then convert the remaining in the background to finish the remaining data, while still being able to use the site.

These documents cover Linux installation. The Windows installer will automate this process for you. However, should you need to, you can run these commands on Windows as well.

By default, HelpSpot used to default to the latin1 character set (ISO-8859-1). Some customers have changed these character sets within the helpspot/lang/english-us/lg.charset.php file (or similar file within their language). Any customers that have changed this should add the --from-encoding flag in the following two commands. Otherwise do not include the --from-encoding flag.

The following are common character sets used. Please use the format highlighted in bold when using the "--from-encoding" flag, for example "--from-encoding=latin2":

latin1 - ISO-8859-1. This is the default and does not need defining
latin2 - ISO-8859-2 - Central European
latin5 - ISO-8859-9 - Turkish
latin7 - ISO-8859-13 - Baltic
greek - ISO-8859-7 - Greek

If you are unsure or have not changed the default HelpSpot character set in the passed, the --from-encoding flag can be unused! If you have used an alternative character set not listed above, you can try that character set (use a value from this table's "charset" column) or contact us for assistance!

From your HelpSpot installation, on your server, first run the initial conversion command:

cd /path/to/helpspot
php hs convert:base

# Of if HelpSpot character set was modified:
php hs convert:base --from-encoding=latin2

This conversion may take 10 minutes and upward, depending on the database size. A database of about 2 GB took us about 10 on a single-core virtual machine with 1GB of ram allocated.

This will take you through steps and information needed to begin conversion the old database to the new one.

Note that your config.php database credentials should point to the new database. Database access credentials asked within the convert:base command will be for the old database.

When that is complete, you can run the next command, which will convert requests and related data, going back the amount of days you specify:

# Convert the last 90 days of requests
php hs convert:requests --days-back=90

# Of if HelpSpot character set was modified:
php hs convert:requests --days-back=90 --from-encoding=latin2

These commands interactively ask for input, but all input can be defined as flags in the command to help with automation! See the documentation on the command line tools for more information.

Converting the first 90 days of requests should only take about a minute or less. However more time could be used if there are many/large requests with many responses within the time period selected.

4. Update HelpSpot

HelpSpot will have some futher updates to make from this point on. You can run these updates using the following comand:

php hs update

That will upgrade HelpSpot to the latest version 4.

Once this is complete, you can start using HelpSpot.

At this point, you can continue to use HelpSpot, and run the conversion of older requests in the background or at a time of your choosing.

# Convert the remaining requests
php hs convert:requests --days-back=all

HelpSpot will keep track of the last Request converted so as not to convert a request and its data more than once.

When you next visit HelpSpot, it may ask you to turn off Maintenance mode. Additionally, it may ask you to update from version 4.0.0 to 4.0.0. This is currently normal behavior.

Speed Tips

Because this upgrade converts all database data from a previous encoding to UTF-8, the more data that's in your database, the longer the conversion will take.

Some tables which may include data you can truncate from your database before the conversion include:

Tables that can be safely truncated

HS_Errors - A log of all errors trapped. The older the errors are, the less relevant they may be. This table can get large during periods where HelpSpot has issues connecting to email systems and similar short-lived events. Truncating older entries in this table can help the conversion process.
HS_Filter_Performance - This table tracks the performance of filters in terms of how long a query to the database for the filter takes. This table often has old information in it which can also be truncated.
HS_Search_Queries - This table tracks search queries made. Entries in this table may also not be of interest and old data can safely be truncated

These tables can have hundreds of thousands of rows of data in HelpSpot installs that have been in use for years, and can slow the conversion process down.

Truncating a table is best done directly using a SQL query. For most database types, you can truncate these tables like so:

TRUNCATE TABLE HS_Errors;

# Optionally also explicitly state which database
# In this case, database "helpspot_db"
TRUNCATE TABLE helpspot_db.HS_Errors

In PostgreSQL, table names must be quoted, as they contain capital letters

TRUNCATE TABLE "HS_Errors";

Attachments

One last speed tip is to also move attachments out of the HelpSpot database. This will move attachments to the server file system, and therefore take the attachments out of the database conversion process. The preceding link provides a script you can run. This must be run BEFORE the update to version 4, as updates includes changes the database schema for attachments.

If you wish to move files to the file system after the update to HelpSpot 4, you can use the new attachments:tofile command.

While documents are not converted or modified in anyway, they are copied to the new database during the conversion process. Removing them from the database before the update and saving them as files will ensure that the script does not need to handle them.

Sphinx Search

After the conversion, HelpSpot 4 will be installed and updated. It will now be useable!

HelpSpot does not require SphinxSearch, but the search capabilities can be enhanced in certain circumstances.

Linux users can find guides for installing SphinxSearch on Debian/Ubuntu servers here, and on RedHat/CentOS servers here.

4. Installing a New HelpSpot 4

HelpSpot 4 is no longer the current version. Please Refer to HelpSpot 5 Install Documentation.

Quick Start

Use our installers to get up and running quickly without worrying about the details. Care about the details? Read the full details section farther down on the page.

Windows

You must use the provided windows installer file, which installs all dependencies and HelpSpot itself. Easy!

Linux/Unix/OSX

Use the installation bash script which handles installation of everything other than MySQL and PHP.

Full Details: Installing From Scratch

The HelpSpot 4 Overview page shows a general overview for both installing a new HelpSpot version 4 and updating an older HelpSpot to version 4.

Here, we'll dig into the steps to install HelpSpot 4 from scratch. Here are the steps to install HelpSpot 4 from scratch:

Windows

Windows Requirements

Windows users must use the provided HelpSpot installer, which installs all required software and required PHP modules.

Windows users have the following system requirements as of HelpSpot version 4: Requirements

Linux

Linux Requirements

Linux

Linux servers requirements can be found here: Requirements

1. Server Setup

Linux users can start by setting up their server. We have the steps provided to do so in our guides to configuring:

In general, any "LAMP stack" (Linux Apache MySQL PHP) will do for HelpSpot. However the server must have IonCube Loader installed, and you should have the ability to install extra software, such as the SphinxSearch engine.

2. Download HelpSpot and Install:

You can download and install HelpSpot from our HelpSpot store in the Downloads section of your account.

Once the server setup portion is complete (see above), you can download the files in the appropriate section of your web server.

Once the files are installed onto the web server, Linux users can create HelpSpot's "config.php" file by copying the "config-empty.php" file and filling in the necessary information (database credentials, etc) into the new "config.php" file.

Once that's created and edited, you can run HelpSpot's installer, which will install and configure HelpSpot's database. This can be run in two ways:

To install HelpSpot via Web:

Run the "installer.php" web installer in your browser (e.g. http://my-helpspot-site.com/installler.php)

To install HelpSpot via the new "install" cli command.

3. Automated Tasks

HelpSpot has 2 scripts which should be run once per minute.

tasks.php - Checks for new messages in each configured Email Mailbox
tasks2.php - Checks any configured Automation Rule and runs applicable rules

Windows users will find these already setup via Windows Task scheduler.

Linux users can create 2 new crontasks:

* * * * * /usr/bin/php /path/to/helpspot/tasks.php


* * * * * /usr/bin/php /path/to/helpspot/tasks2.php

Note: Here are links for more detailed information about tasks and tasks2, including how to setup multiple cronjobs for the primary task, in order to check specific Email Mailboxes - useful for high-volume installations!

5. HelpSpot Server Setup: RedHat/CentOS

RedHat (RHEL) and CentOS have additional security and configuration that you may not find on Debian/Ubuntu servers. This guide will help you setup a Server on RedHat/CentOS servers that may be missing some PHP modules HelpSpot requires, along with some setup for ensuring HelpSpot will work in environments where SELinux is enabled.

We'll cover setting up an RedHat/CentOS server for use with HelpSpot.

This will install PHP, Apache and MariaDB (a MySQL drop-in replacement). PostgreSQL can alternatively be used.

As of CentOS 7/RedHat 7, MariaDB is the default "MySQL" database available. HelpSpot will work fine with MariaDB and it's replacement of the InnoDB storage engine, ExtraDB.

If you with to use MySQL over MariaDB, however, you can find the appropriate RPMs available for MySQL 5.6 here.

Install Apache & PHP

First we'll install Apache and PHP.

As of CentOS/RedHat 6, a required PHP package "php-imap" (and other optional ones) are not available with the standard repositories. We suggest getting the Fedora EPEL package repository if you are able to. This can be done with one command:

sudo rpm -Uvh \
    http://dl.fedoraproject.org/pub/epel/7/x86_64/e/epel-release-7-5.noarch.rpm

Note: If you are using the Amazon AWS RHEL7 image, you may need to enable the Extras and Optional repositories.
To do so, run the following:
# ONLY IF USING AMAZON AWS'S RHEL7 IMAGE
sudo yum-config-manager --enable rhui-REGION-rhel-server-extras rhui-REGION-rhel-server-optional

Once that's done, we can install all of the needed Apache and PHP packages:

# Install Apache + PHP
sudo yum install httpd php php-pdo php-mysql php-gd php-mcrypt php-curl php-imap php-xml

# Set Apache to start on boot:
sudo systemctl enable httpd.service

# Start Apache:
sudo service httpd start

Users of SELinux can also ensure that Apache has permission to use the network to connect to MySQL/MariaDB (essentially connect over 127.0.0.1 rather than via hostname "localhost"):

sudo setsebool -P httpd_can_network_connect_db on
sudo service httpd restart

Next we need to 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 /etc/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 httpd restart

Lastly we'll create an Apache VirtualHost for use with HelpSpot. You can skip this and add HelpSpot into the default /var/www/html directory, but this is more useful to add some extra security.

We'll make a few assumptions:

The site is hosted at url http://support.example.com
The site files will be on the server in directory /var/www/support.example.com

Create or edit file /etc/httpd/conf.d/vhosts.conf. The following VirtualHost is recommended 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 /var/log/httpd/support.example.com-error.log
    # Possible values include: debug, info, notice, warn, error, crit, 
    # alert, emerg. LogLevel warn
    CustomLog /var/log/httpd/support.example.com-access.log combined
</VirtualHost>

This configuration will be read automatically by Apache. Once that's saved, you can ensure your configuration is OK:

sudo service httpd configtest

If everything checks out, reload Apache to load in the new config:

sudo service httpd reload

Install MariaDB

We'll next install MariaDB, the drop-in replace for MySQL which CentOS7/RedHat7 now come with.

sudo yum install mariadb-server
sudo systemctl enable mariadb.service
sudo service mariadb start
sudo mysql_secure_installation

Once that's installed and you've run through the steps to secure the installation (remove test databases and anything but local root access), you can optionally setup MariaDB to be listen on the localhost network 127.0.0.1. (Otherwise you will only be able to connect to it with hostname "localhost"). Use this in conjunction with the SELinux setsebool above, if you are using SELinux.

Edit the /etc/my.cnf.d/server.cnf and append the following under [mysqld]:

[mysqld]
bind-address = 127.0.0.1

Then restart MariaDB:

sudo service mariadb restart

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

# This will prompt you for the root password:
mysql -u root -p

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

We recommend using the IonCube loader to read HelpSpot code files. In future HelpSpot versions, we may do away with Zend Loader support do to issues in building HelpSpot with the Zend Loader.

IonCube loader can be downloaded from here. You'll likely need the Linux 64bit version. Downloading the Uploader file of the appropriate version 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:

Downloading the files to your server, using curl or wget (e.g. "wget http://downloads3.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.zip")
Unzipping the file (e.g. "unzip ioncube_loaders_lin_x86-64.zip")
Moving the files to your /var/www/support.example.com site and heading to the included .html file in the wizard directory from your browser.

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

A list of command which should work for the latest CentOS/IonCube (assuming they install php version 5.4):

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.4, assuming that is what's installed
sudo cp ioncube_loader_lin_5.4.so /usr/lib64/php/modules/ioncube_loader_lin_5.4.so

# If you are using SELinux, give this file the proper owner and SELinux contenx:
sudo chown root:root /usr/lib64/php/modules/ioncube_loader_lin_5.4.so
sudo chcon -v --user=system_u --role=object_r --type=lib_t \
     /usr/lib64/php/modules/ioncube_loader_lin_5.4.so

# Edit/create the php module to load IonCube:
sudo vi /etc/php.d/00-ioncube.ini

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

; Enable ioncube extension module
zend_extension=/usr/lib64/php/modules/ioncube_loader_lin_5.4.so

Then restart Apache:

sudo service httpd restart

HelpSpot Files & SELinux

If you are using SELinux, and assuming your HelpSpot installation is found at /var/www/support.example.com, make sure that your HelpSpot has the proper SELinux settings. We'll also ensure the "data" can be written to, as needed by HelpSpot.

# Set file ownership for HelpSpot files
sudo chown -R apache:apache /var/www/support.example.com

# Check current SELinux settings for HelpSpot files:
cd /var/www/support.example.com
ls -Z

# Set SELinux context for Apache files:
sudo chcon -Rv --user=system_u --role=object_r --type=httpd_sys_content_t \
    /var/www/support.example.com

# Set write ability to "data" directory:
sudo chmod -R gu+rw /var/www/support.example.com/data

# Ensure SELinux allows Apache has permission to write to the data directory:
sudo chcon -Rv --type=httpd_sys_content_rw_t /var/www/support.example.com/data

Wrapping Up

Once these steps are done, you can include your HelpSpot files in the /var/www/support.example.com directory, copy the config-empty.php file to 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/httpd/support.example.com-error.log.

You may also wish to edit the /etc/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 httpd 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.

6. 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:

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:

The site is hosted at url http://support.example.com
The site files will be on the server in directory /var/www/support.example.com

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:

sudo mysql

Then use the following to create a new database:

CREATE DATABASE helpspot_db
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;

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:

Downloading the files to your server, using curl or wget (e.g. "wget http://downloads3.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.zip")
Unzipping the file (e.g. "unzip ioncube_loaders_lin_x86-64.zip")
Moving the files to your /var/www/support.example.com site and heading to the included .html file in the wizard directory from your browser.

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

7. Creating a UTF-8 Database

MySQL

MySQL databases for HelpSpot version 4 should default to the InnoDB storage engine and to a UTF-8mb4 character set and collation.

For MySQL 5.5.3+, we can use the character set utf8mb4, which is a more complete implementation of UTF-8.

CREATE DATABASE helpspot_db2
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;

Note that you should change the database name (helpspot_db) as needed for your use case. You may also need to assign a specific user to the database.

SqlServer

SqlServer uses UTF16 by default and likely needs no further instructions on using a UTF-8 friendly database when creating a new database for use with HelpSpot. Users of the Windows Installer will find the new database is created for you, and so most users will not need to worry about creating a new database.

The conversion process will be required to convert existing database data, which may not be saved in UTF-8 encoding.

8. HelpSpot 4 Server Security

Linux Apache

Make Data Directory Writable

The data directory must be writable by the web server (and PHP). This can be done by assign group ownership/permissions of the directory as appropriate for your system.

RedHat/CentOS:

sudo chgrp -R httpd /path/to/helpspot/data
sudo chmod -R g+rw /path/to/helpspot/data

Debian/Ubuntu:

sudo chgrp -R www-data /path/to/helpspot/data
sudo chmod -R g+rw /path/to/helpspot/data

Protect Data Directory

The data directory should not be served to publicly to your audience.

We've included an .htaccess file in the data directory which denies public web-based access to that directory:

File /path/to/helpspot/data/.htaccess:

Deny from all

If your Apache installation does not allow the use of .htaccess files, you can enable them in the VirtualHost configuration for HelpSpot:

<VirtualHost *:80>
    # Other directives omitted

    <Directory /path/to/helpspot>
        AllowOverride All  # this allows .htaccess file usage

        # Other directives omitted
    </Directory>
</VirtualHost>

Alternatively, you can keep disallowing .htaccess file usage and set the permissions within the VirtualHost configuration:

<VirtualHost *:80>
    # Items omitted

    <Directory /path/to/helpspot>
        AllowOverride None

        # Other items omitted
    </Directory>

    <Directory /path/to/helpspot/data>
        Deny from all
    </Directory>
</VirtualHost>

Windows

Make Data directory writable

This is configured for you if you install HelpSpot using the Windows Installer.

Apache

This is configured for you if you install HelpSpot using the Windows Installer.

Apache installed on Windows can accomplish the same. Near the bottom of the C:\Program Files (x32)\helpspot\apache\conf\httpd.conf file, you can append a Directory configuration to the bottom:

<Directory "C:\Program Files (x32)\helpspot\helpspot\data">
    Deny from all
</Directory>

IIS

This is configured for you if you install HelpSpot using the Windows Installer.

The web.config XML file found in C:\Program Files (x32)\helpspot\helpspot\web.config file requires the addition of some security configuration.

Add the following as appropriate:

<configuration>
   <system.webServer>
       <security>
          <requestFiltering>
               <hiddenSegments>
                   <add segment="data" />
               </hiddenSegments>
           </requestFiltering>
       </security>
   </system.webServer>
</configuration>

File Permissions

IIS needs to be able to write to HelpSpot's "data" directory. This usually means user IUSR needs permission to modify/write this directory. The Windows installer will handle this for you. However, users who install HelpSpot in non-default locations will need to set security settings on the "data" directory so IUSR can modify/write to that directory.

Nginx

HelpSpot can also work with the Nginx web server.

You can restrict access to the data directory in Nginx with the following "location" block:

server {
    # Other directives omitted

    location /data {
        deny all;
    }
}

MySQL SSL

HelpSpot version 4.0.17+ can connect to MySQL over an SSL connection.

To use an SSL configuration, add the following two items to HelpSpot's config.php file:

define('cMYSQL_CLIENT_SSL', true);
define('cMYSQL_INI_PATH', '/etc/mysql/my.cnf');

Note that the path to the my.cnf file may be different on your system.

Within the my.cnf file referenced, we need to tell MySQL that clients should connect using the SSL certificate. To do so, append the relevant lines of the following under the [client] section of the MySQL my.cnf file. The certificate file paths and names will be different for you:

ssl-ca=/path/to/your/ca-cert.pem
ssl-cert=/path/to/your/client-cert.pem
ssl-key=/path/to/your/client-key.pem
ssl-verify-server-cert=1

Note: The MySQL configuration for supporting SSL connections is out of scope of HelpSpot, but generally involves:

Creating an SSL certificate (key, certificate and possibly certificate authority files)
Setting the my.cnf file to use the certificate files under the [mysqld] heading

9. Installing A New License File

Your license file needs to be updated when you change the number of agent licenses on your account or renew your subscription. For HelpSpot Cloud customers, this process happens automatically. Self-hosted customers will receive an email with a new license file and will also be able to download the new license by logging into https://store.helpspot.com. After downloading the license file the license can be updated through the HelpSpot admin screen.

Login to your HelpSpot instance.
Select Admin from the top menu.
Select Choose File in the Upload a New License box.
Upload select your downloaded license file from the file picker.

The license will be updated to reflect the latest subscription information.

10. Database Based Full Text Search

AS OF HELPSPOT 5.0.X SPHINX SEARCH HAS BEEN COMPLETELY REMOVED

As of version 4.6.7 HelpSpot allows the use of either built in database full-text search of the use of the external Sphinx search indexer. New installations will default to the database search search option. To switch an existing sphinx based installation to database search you simply need to add the define('SEARCH_ENGINE', 'database'); variable to your config.php file.

Opting For Sphinx Search:
Most installations will be well served by the default, database Full Text search option. However, if there is a need for advanced full text search parameters or a need to reduce the database load query load, Sphinx search can be setup. On linux bases installs, the sphinx setup requires additional steps that are documented here: for Ubuntu/Debian and RedHat/CentOS. New windows installations will default to database search but can be converted to sphinx search by changing the config.php
variable for the search engine to define('SEARCH_ENGINE', 'sphinx');.

11. HelpSpot Commands

HelpSpot 4.0.0 now comes with a command-line tool, which has some tools to help you automate a few things. The functionality of this is limited for now, but will likely expand with added features.

General

Linux:

The hs command installed with HelpSpot is the command line utility. On Linux servers, you can run it using PHP:

# List the available commands and options:
$ php hs

Windows:

On Windows, you need to run the hs command using the PHP that comes with HelpSpot using Cmd or PowerShell, and let it know which configuration file to use:

> C:\'Program Files (x86)'\helpspot\php\php.exe -c C:\'Program Files (x86)'\helpspot\php\php.ini C:\'Program Files (x86)'\helpspot\helpspot\hs

It might be easier to first "change directory" into the HelpSpot directory so these file paths are shorter:

> cd C:\'Program Files (x86)'\helpspot\helpspot
> ..\php\php.exe -c ..\php\php.ini .\hs

For both Linux and Windows, running hs without any parameters will simply list out the available commands.

Here are the commands available for HelpSpot:

install - A command to install/configure HelpSpot
update - A command to run updates for HelpSpot from 4.0.0+
attachments:tofile - A command to convert attachments from the database to the filesystem
convert:base - A command to start the update HelpSpot from version 3 to 4
convert:request - A command to complete the update from HelpSpot version 3 to 4
recover:requests - If the conversion of requests fail silently and there are missing requests, this command can be used to recover them
db:exists - Check if a HelpSpot database exists
search:config - Generate a Sphinx Search configuration file
request:delete - Delete a single request by ID
request:delete-spam - Delete all requests marked as spam ithout training the spam filter.
report:logs - Export a CSV file of your Helpspot request event logs to your data/documents/ directory.
spam:clean - optimize the Bayesian filter database to improve spam filtering performance.

Install

HelpSpot can be installed via the command line instead of using the web interface. This might be useful for automating the install of HelpSpot.

The simplest way to use this command is to download the HelpSpot files, and then run the "install" command. This will ask you for the information it needs to complete the installation.

php hs install

This asks you all the information needed to install HelpSpot. You can also pass the command all the needed information directly, allowing the install to be automated. The following are the flags/options you can set:

Note that you can run `php hs install -h`, which will show you the available flags/options to use for the install command.

--agree=yes - "Yes" to say you agree to the terms and conditions
--name='Your Full Name' - The administrator user's full name (first and last)
--admin-email=admin@email.com - The administrator user's email address
--password=your_password - The administrator user's passwor
--company='Your Company' - The company as displayed publicly
--timezone='America/New_York' - The timezone to use within HelpSpot
--customer-id=123456 - Your customer ID
--license-file=/path/to/license-file.txt - The path to the license file, which should be saved to the server before running the server
--notification-email=notification@email.com - The email used for sending notifications
--ask-smtp=yes - Add in your outgoing email settings, using the following "smtp" options. Use "no" to configure this later, the smtp configuration is optional
--smtp-host=somehostname - (Conditional on "--ask-smtp") The outgoing email server
--smtp-port=1234 - (Conditional on "--ask-smtp") The outgoing email port
--smtp-user=some@user.com - (Conditional on "--ask-smtp") The outgoing email user name
--smtp-password=some_password - (Conditional on "--ask-smtp") The outgoing email password
--smtp-protocol=none - (Conditional on "--ask-smtp") The connection protocol. One of "none" (no security), "ssl" or "tls"

Update

You can use this tool to update HelpSpot as well. This will be useful when versions greater than 4.0.0 is released. For example, you can run this command when updating from version 4.0.0 to 4.0.1.

Once you update the HelpSpot files on your server, you can run the update command:

php hs update

This will gather the old version and new version of HelpSpot and run any scripted or database updates needed. This will not install the latest HelpSpot file - that step must still be done outside of this command line tool.

--language=english.us - Defaults to the "english.us" language

This command is much simpler than the install command, as it will determine the needed information from available system information.

Attachments

This command will allow you to save your file attachments from the database (the default location prior to HelpSpot version 4) to your server file system. This command can only be used after you convert your database from version 3 to version 4, due to differences in the database structure.

This command will delete file attachment data from your database. We highly suggest backing up your database before running this command.

To begin saving database attachments to the filesystem, run the following command.

php hs attachments:tofile

This will ask you the file path to save your attachments. The default value is the data/documents directory, which HelpSpot 4 comes with for this purpose.

Note that you can run `php hs attachments:tofile -h`, which will show you the available flags/options to use for the install command.

--path=data/documents - The path (relative to the "hs" command location or absolute) where the files should be saved to. This location must be writable by the user running the command.

This command may take a considerable amount of time, depending on the size of your database. The command can safely be run multiple times, including if it stops on failure or timeout.

Convert

The convert commands are used specifically to update HelpSpot from Version 3 to Version 4. HelpSpot requires a conversion of the current data from its current character set to UTF-8 (in order to support multiple language alphabets and characters properly). This process can take a relatively long time and should be run via the command-line, which has no time limit like an update from within the browser may have.

Before updating from Version 3 to Version 4, you must create a new, empty database that is setup for UTF-8 character sets. The new database credentials should be added into the config.php file. However, keep a note of the old credentials, as the conversion process requires access to both databases.

There are two commands for conversion:

convert:base - Creates the database tables in the new database, and converts the "base" (not Request-related) data into the new database from the old database.
convert:requests - Converts Requests and all related data from the old database to the new database. This can go back in time a specific amount of days, or do all requests. This command can be run more than once without fear of duplicating data.

Because the conversion requires two databases, it's useful to set the terms used:

source database - the old database from which data will be converted and copied into the new, UTF8-Capable database
destination database - the new, UTF8-Capable database which data will be converted and copied into.

The destination database credentials must be set in the config.php file, while the source database credentials will be asked for in while using the convert commands.

convert:base

The convert:base command should be run first. This command will do two things:

Create the needed database schema for HelpSpot version 4 in the new database
Copy all database data, except for that related to Requests, into the new database

Running this command will ask you for the necessary input.

php hs convert:base

You can also provide it the needed information head of time:

--db-type=mysql - The source database type you are using. Note that this is the old database, not the new UTF-8 capable database. The default is "mysql". Valid types are: mysql, mssql, or postgres_helpspot
--db-host=localhost - The hostname to use to access the source database. The default is "localhost".
--db-user=some_username - The username used to access the source database
--db-pass=some_password - The password used to access the source database
--db-name=some_db_name - The name of the source database
--from-encoding=iso-8859-1 - Optional parameter, the character encoding used to convert data from. Character set encoders need to know what character set they are encoding from in order to properly encode to other character sets such as UTF-8. The default for HelpSpot prior to version 4 was "iso-8859-1", which is also commonly referred to as "latin1"
- This script will guess the character set if it's not explicitly set via the --from-encoding parameter. It gets the character set from the cHD_CHARSET variable in the HS_Settings table in the source database.
--schema-only=yes - Set the database schema only, don't copy and data
--data-only=yes - Copy data only, assuming the schema is already in place (via --schema-only=yes complete previously)

This script takes about 10 minutes to run on a 2GB database. See the "Speed Tips" section within the Overview chapter for more information.

Custom Database Schema

Some HelpSpot customers add new tables or adjust the schema of the standard HelpSpot database. For those customers, the convert:base command needs to be handled in a way that allows you to add custom tables, columns or schema adjustments before database data is copied to the new database.

To accomplish this, the convert:base command can be run in two parts via the --schema-only and --data-only options. The workflow will look like this:

Run convert:base --schema-only, which will update the new database with the new schema, but won't copy and data
Add any new tables, columns, or schema adjustments as needed
Run convert:base --data-only, which will copy data from the old database to the new database. This should copy custom columns and handle data from adjusted existing columns. However, it will not copy new tables that are not part of HelpSpot standard database installation. Copying of any additional custom tables created will need to be done by the system administrator.

convert:requests

The convert:requests command is used to convert Requests and all related data. Requests have a lot of related data, so each request is converted and copied one by one from the source database to the destination database.

php hs convert:requests

This command will save requests starting with the newest first. This let's you quickly get up and running by converting the latest requests (for example, the last 90 days worth of requests). Then, if HelpSpot support is critical enough, your staff can continue working within HelpSpot while the command is run again to complete the remaining requests in the system.

Since many systems have been up and running for years, some systems will have hundreds of thousands of database rows of requests and request history. The use case above (copying the last 90 days of requests and then the remaining in the background while the system is in active use) is for such cases.

On a database of about 2GB of size with about 30,000 requests and 285,000 items of request history, the conversion process took about 20-30 minutes.

The options for this command are similar to the convert:base:

--db-type=mysql - The source database type you are using. Note that this is the old database, not the new UTF-8 capable database. The default is "mysql". Valid types are: mysql, mssql, or postgres_helpspot
--db-host=localhost - The hostname to use to access the source database. The default is "localhost".
--db-user=some_username - The username used to access the source database
--db-pass=some_password - The password used to access the source database
--db-name=some_db_name - The name of the source database
--from-encoding=iso-8859-1 - Optional parameter, the character encoding used to convert data from. Character set encoders need to know what character set they are encoding from in order to properly encode to other character sets such as UTF-8. The default for HelpSpot prior to version 4 was "iso-8859-1", which is also commonly referred to as "latin1"
- This script will guess the character set if it's not explicitly set via the --from-encoding parameter. It gets the character set from the cHD_CHARSET variable in the HS_Settings table in the source database.
--days-back=90 - The number of days of requests to go back in time. The default is 90 days. Use "all" to copy all requests. Note that HelpSpot will not be usable until this command completes running at least once, upon which it updates HelpSpot's internal setting to the correct version, making HelpSpot able to reach the admin login page.

This command tracks requests that have been successfully copied to the new database. This means you can run the command multiple times safely. Note that the --days-back option is relative to "now", the time when you run the command. If you run the command "now", going back 90 days, it will copy the last 90 days of requests. Running the identical request immediately a second time will result in no requests being copied, as the last 90 days worth of requests have already been copied. To go back further than 90 days, increase the number of days set, or use "all": --days-back=all

php hs convert:requests --days-back=all

Recover Requests

The recover:requests command is only used on a v3 to v4 upgrade when the database is being converted. If the conversion of requests fail silently and there are missing requests, this command can be used to recover them. This command is limited to 2100 requests on SQLServer because of SQLServer's bind limit.

Database Exists

The db:exist command determines if a populated HelpSpot database already exists based on the credentials used in the config.php file. This is a utility function, used by the Windows installer primarily, but available to all customers. This command may be useful to those automating an install or update of HelpSpot.

php hs db:exists

Search Configuration

The search:config command will generate a configuration file for SphinxSearch to use. It takes the database credentials and information such as custom fields from the database (using the database credentials set in config.php) and generates the configuration file. This configuration file contains the needed information to index Customer data, Requests, Knowledge Books and Forums into the Sphinx Search engine index.

This command will save the sphinx.conf file to the server-writable "data" directory found within the HelpSpot installation.

php hs search:config

There is a single option for this command that allows you to specify the location where the sphinx index files reside.

--data-path — The path where the sphinx index files will be generated.

For details on how to use this generated sphinx.conf file, see our extended documentation on installing Sphinx Search on Debian/Ubuntu servers or installing Sphinx Search on RedHat/CentOS servers.

Request: Delete

The request:delete command deletes a request by ID. You pass it the --id= option with your request ID.

php hs request:delete --id=12400

Request: Delete Spam

The request:delete-spam command deletes all requests in HelpSpot's spam queue. It will not train the spam filter. By default it asks for confirmation, you can bypass this with the --force flag.

php hs request:delete-spam

Report: Logs

The report:logs command will export a CSV file of your helpspot request event logs to your data/documents/ directory.

php hs report:logs

Spam: Clean

The spam:clean command optimize the Bayesian filter database to improve spam filtering performance. Running this every 7 days is recommended for larger installations.

php hs spam:clean

hs config:convert

Converts the config.php file to a .env file. The default action will overwrite any existing .env. --dump Displays the result of processing the config.php file instead of overwriting the .env.

php hs config:convert

12. Tasks.php Explained

AS OF HELPSPOT 5.0 TASKS.PHP IS NO LONGER USED

See documentation here on the new cron jobs and and queuing system

What does tasks.php do?

The tasks.php script has 3 main functions in HelpSpot:

Check email accounts and convert emails into requests
Send out reminders
Delete requests marked as trash

Running tasks.php on a regular basis is critical to using HelpSpot. Major functionality will not work properly without this script running.

Where is it located?

The tasks.php file is in the root HelpSpot folder. The same one which contains admin.php and index.php.

How often should tasks.php run?

Every 1-5 minutes, however every 1-2 is recommended.

How do I run the script?

On Linux/Unix the script should be run via Cron. On Windows Scheduled Tasks should be used. Windows users note that if you've installed using our Windows Installer a scheduled task has already been setup for you.

Configuration for Windows:
If you've used the HelpSpot Windows Installer this has already been done for you.

Configuration for Linux/Unix/OSX:
tasks.php can be called directly through PHP on the command line or via an HTTP call. Several examples are below, but be sure to replace the generic paths with the ones for your installation:

Direct command line method for every minute (preferred):

* * * * * /usr/bin/php /path/to/helpspot/tasks.php

Using HTTP with curl:

* * * * * curl http://www.domain.com/tasks.php

Tips and Tricks

Direct access
You can manually run the tasks.php file in your browser to force it to pull in email (and it's other actions). This is often useful for testing purposes. Just visit the script in your browser at http://www.domain.com/tasks.php. Note that it is normal for the output to be a blank white screen.

Tasks.php debugging
If you're having problems with an email account it can be useful to turn on tasks.php debugging in Admin->Settings->Email Integration. Once this is on if you visit the tasks.php file in your browser (as described above) you'll see debugging output. It's often useful to do "view source" in your browser to see the output in a nicer format.

Additional security
If you want to prevent people from outside being able to access tasks.php via HTTP you can set the IP's that are allowed to call it in Admin->Settings->System.

Check just one mailbox
Normally each time tasks.php is run it checks all mailboxes you've configured in Admin->Mailboxes. If you'd like to run mailboxes on their own checking schedules though it's possible to have HelpSpot only check one mailbox when tasks.php is run. To do so you need to pass in the ID of the mailbox which you can find in Admin->Mailboxes.

If you were using the HTTP method you would change the URL to:

http://www.domain.com/tasks.php?id=4

If you were using the command line method you would do this:

* * * * * /usr/bin/php /path/to/helpspot/tasks.php --id=4

New in HelpSpot version 4: Check multiple mailboxes

Customers with many Email Mailboxes (or a few which usually contain large attachments) may want to divide mailboxes out to separate scheduled tasks. This allows you to stagger when they are called, or to separate email mailbox checking to multiple PHP calls. This reduces the change of hitting an error due to meeting memory limits while checking for new email.

For example, if you have 6 Email Mailboxes (of id 1, 2, 3, 4, 5, and 6) configured and want to check 3 at a time, you can create two tasks.

If you were using the HTTP method you would make 2 separate calls like so:

http://www.domain.com/tasks.php?id[]=1&id[]=2&id[]=3
http://www.domain.com/tasks.php?id[]=4&id[]=5&id[]=6

If you were using the command line method you make 2 separate crontasks like so:

* * * * * /usr/bin/php /path/to/helpspot/tasks.php --id=1,2,3
* * * * * /usr/bin/php /path/to/helpspot/tasks.php --id=4,5,6

13. Version 4 Language File Changes

The following outlines changes (additions, modifications and deletions) from the HelpSpot language files between version 3 and 4.

Note that some values are truncated for brevity. Please check the files on your HelpSpot installation to find their current values. For example: define('lg_ajax_valid_wysiwyg_values’,’…’);

helpspot/lang/english-us/lg.charset.php

This files is significantly shorter, the only content is:

// SECURITY: Don't allow direct calls to this file outside the context of HelpSpot
if (!defined('cBASEPATH')) die();

//Set the language/region time is formatted in. More details here: http://www.php.net/setlocale
setlocale(LC_ALL, 'en-us','english');

helpspot/lang/english-us/lg.general.php

Removed:

define('lg_mobilehs','Mobile Login');
define('lg_share','Share');
define('lg_placeholderspopup_mobilereqpage','Mobile Request URL');

Added/Modified:

define('lg_documentation','Help');
define('lg_forums','Join us on the forums!');
define('lg_academy','Training');
define('lg_social','Social');
define('lg_lookup_mobile','HelpSpot Mobile App');
define('lg_lookup_filter_lastupdateby','Latest Update By');
define('lg_noresults_with_fulltext','Note: Request history is not searched from the sidebar when Sphinx Search is not enabled.');
define('lg_noresults_alt11','These pretzels are making me thirsty.');
define('lg_noresults_alt12','You\'re a lean, mean, inbox clearing machine.');
define('lg_noresults_alt16','https://www.youtube.com/embed/zpN00-UTrY0');
define('lg_noresults_alt_lunch','Lunch is for wimps.');
define('lg_noresults_alt_latenight',"I'll sleep when I'm dead.");
define('lg_search_history','Search History');

helpspot/lang/english-us/lg.pg.admin.rules.php

Added/Modified:

define('lg_admin_rules_note','Rules apply only to new request emails; any follow-ups to existing requests will not be impacted.');

helpspot/lang/english-us/lg.pg.admin.settings.php

Removed:

define('lg_admin_settings_spellchecking','Spellchecking');
define('lg_admin_settings_spellchecking_note','<strong>Note:</strong> Using an in browser spellchecker in many cases will be most effective and provide the best experience. FireFox and Safari have spellcheckers built in. IE users can download free spellcheckers here: <a href="http://www.ie7pro.com/" target="_blank">IE7</a> or <a href="http://www.iespell.com/" target="_blank">IE6</a>');
define('lg_admin_settings_sppath','Spellchecking - Path to Aspell');
define('lg_admin_settings_sppathnote','The full path to the Aspell binary on your server. Leave blank to disable spellchecking.');
define('lg_admin_settings_spchar','Spellchecking - Character Encoding');
define('lg_admin_settings_spcharnote','In the format of: iso8859-1');
define('lg_admin_settings_splang','Spellchecking - Language Dictionary');
define('lg_admin_settings_spgecko','Allow FireFox Native Spellchecking in WYSIWYG Editor');
define('lg_admin_settings_spgeckoex','Enabling this may interfere with staff using the Microsoft Internet Explorer browser');

Added/Modified:

define('lg_admin_settings_captcharedesc','reCAPTCHA is a free service of Google. It is an image/audio captcha which is more secure than the standard text captcha. To use it you need to <a href="https://www.google.com/recaptcha" target="_blank">sign up for a free API KEY</a>.');
define('lg_admin_settings_captcharepublic','Site Key');
define('lg_admin_settings_captchareprivate','Secret Key');
define('lg_admin_settings_reply_as_public','Replies to notification emails are public');
define('lg_admin_settings_reply_as_publicex','When staff reply to an email notification about a request the reply will be forwarded through HelpSpot as a public note to the customer.');

helpspot/lang/english-us/lg.pg.admin.users.php

Removed:

define('lg_admin_users_mobsig','Mobile Version');

Added/Modified:

define('lg_admin_users_sidebarsearch','Search History by Default in Sidebar');
define('lg_admin_users_sidebarsearchtitle','Sidebar Search');

helpspot/lang/english-us/lg.pg.ajax_gateway.php

Added/Modified:

define('lg_ajax_valid_wysiwyg_values’,’…’);
define('lg_ajax_valid_wysiwyg_values’,’…’);
define('lg_ajax_valid_wysiwyg_values’,’…’);

helpspot/lang/english-us/lg.pg.conditional.ui.php

Added/Modified:

define('lg_conditional_ftwarning','Full text searches in a filter should be used with caution; they have the potential to be database intensive. If you are using Sphinx Search (now standard with HelpSpot), this is less likely to be an issue.');
define('lg_conditional_at_webhook','POST a webhook to this URL:');
define('lg_conditional_tr_webhook','POST a webhook to this URL:');

helpspot/lang/english-us/lg.pg.installer.php

Removed:

define('lg_inst_cat_def','Default Category');
define('lg_inst_cat_reptags','Computer,Printer,Software,User Account,Access Request,Password'); //leave comma's

Added/Modified:

define('lg_inst_must_agree','You must accept the license terms to continue');
define('lg_inst_checkphp','PHP version 5.4 or higher');
define('lg_inst_checknotphp','HelpSpot requires PHP version 5.4.0 or higher to run');
define('lg_inst_permwarning','Your HelpSpot source files (some or all) have permissions which make them w
ritable by the web server (777). HelpSpot does not write to its source files in anyway. Please change your file permissions to be less open.');
define('lg_inst_datadir', 'Data Directory Permissions');
define('lg_inst_datadirnowrite', 'The "data" directory or subdirectories are not writable');
define('lg_inst_licensefile_cli','Path To Your License File');
// Default Categories
define('lg_inst_cat_number_cats', 6); // Number of default categories to install
// Default setup for internal facing support
define('lg_inst_cat_def','Software');
define('lg_inst_cat_reptags','Operating System, Mac, Windows, Linux, MS Office, Browser'); //leave commas
define('lg_inst_cat2_def','Hardware');
define('lg_inst_cat2_reptags','Desktop, Laptop, Monitor, Peripheral, Projector, TV, Phone'); //leave commas
define('lg_inst_cat3_def','Server');
define('lg_inst_cat3_reptags','Offline, Performance, Linux, Windows, RAM, Storage, Networking'); //leave commas
define('lg_inst_cat4_def','Human Resources');
define('lg_inst_cat4_reptags','New Hire, Benefits, Policy, Time Off'); //leave commas
define('lg_inst_cat5_def','Maintenance');
define('lg_inst_cat5_reptags','Grounds, Buildings, Electric, Plumbing, Furniture'); //leave commas
define('lg_inst_cat6_def','Other');
define('lg_inst_cat6_reptags','Wrong Email, Notification'); //leave commas
// Default setup for external facing support
define('lg_inst_cat_def_external','Account Question');
define('lg_inst_cat_reptags_external','Status, Renewal, Rewards, Cancel'); //leave commas
define('lg_inst_cat2_def_external','Technical Issue');
define('lg_inst_cat2_reptags_external','Installation, On-boarding, Browser, Feature, Bug'); //leave commas
define('lg_inst_cat3_def_external','Development');
define('lg_inst_cat3_reptags_external','Software Bug, Feature Request'); //leave commas
define('lg_inst_cat4_def_external','Sales');
define('lg_inst_cat4_reptags_external','Pricing, Demo, Discount, Upgrade, Downgrade, Pre-Sales'); //leave commas
define('lg_inst_cat5_def_external','How To');
define('lg_inst_cat5_reptags_external','User Management, Features, Configuration, Optimization'); //leave commas
define('lg_inst_cat6_def_external','Other');
define('lg_inst_cat6_reptags_external','Wrong Email, Notification');
define('lg_inst_status2','Escalated');
define('lg_inst_status3','Waiting for Reply');
define('lg_inst_status5','Customer Unreachable');
define('lg_inst_settings_smtpprotocol','SMTP Protocol (none, ssl, tls)');
define('lg_inst_et_external', '...');
define('lg_inst_et_portal_reqcreated_html','...');
define('lg_inst_et_external_html','...');
define('lg_inst_et_staff_html','...');
define('lg_inst_et_ccstaff_html','...');
define('lg_inst_et_public_html','...');
define('lg_inst_et_reminder_html','...');

helpspot/lang/english-us/lg.pg.mobile.php

File Deleted

helpspot/lang/english-us/lg.pg.reports.php

Added/Modified:

define('lg_reports_grouping_customerid','Customer ID');
define('lg_reports_grouping_customer_email','Customer Email');

helpspot/lang/english-us/lg.pg.request.php

Removed:

define('lg_request_er_resumeedit','Please resume editing in the spellchecker before submitting');

Added/Modified:

define('lg_request_timehrmin','hh:mm:ss');
define('lg_request_create_close','Create and Close');
define('lg_request_sidebar','Customer Search');

helpspot/lang/english-us/lg.pg.search.php

Added/Modified:

// Added for SphinxSearch
define('lg_search_sphinx_tip1','Use * as a wildcard: print*');
define('lg_search_sphinx_tip2','Use - or ! for must not contain: -printer, -password, !printer, !password');
define('lg_search_sphinx_tip3','Use = for must exact form: lost all =passwords (ensures passwords is plural)');
define('lg_search_sphinx_tip4','Use @ to search specific fields: @sEmail ian@userscape.com, @(sEmail,sTitle) *userscape');
define('lg_search_sphinx_tip5','Valid fields: sFirstName, sLastName, fOpenedVia, sEmail, sPhone, sUserId (for Customer ID), tNote, Custom# (e.g. Custom5)');
define('lg_search_sphinx_tip6','More search modifiers for <a href="http://sphinxsearch.com/docs/current.html#extended-syntax" target="_blank">SphinxSearch are explained here</a>.');

helpspot/lang/english-us/lg.portal.php

Added/Modified:

define('lg_portal_er_validrecaptcha','Please check off that you are not a robot');

14. HelpSpot 4.8.0 Language File Changes

lg.general.php

//additions
define('lg_lookup_filter_thermostat_score','Thermostat NPS Score');
define('lg_admin_customer_tools','Customer Tools');

lg.pg.admin.integrations.php

//additions
define('lg_admin_thermostat_header','Send NPS surveys to your customers with ');
define('lg_admin_thermostat_connect','Save Thermostat API Token');
define('lg_admin_thermostat_learn_about','Learn About Thermostat');
define('lg_admin_thermostat_get_token', 'Get an API Token');
define('lg_admin_thermostat_label_api_token', 'Thermostat API Token');
define('lg_admin_thermostat_token_value', 'placeholder="<token hidden> Enter a new (or empty) token to update (or remove) the Thermostat API token."');

lg.pg.admin.settings.php

//additions
define('lg_admin_settings_terms_enable','Ask customer to accept privacy policy and terms');
define('lg_admin_settings_portalterms','URL of terms of service');
define('lg_admin_settings_portalprivacy','URL of privacy policy');
define('lg_admin_settings_portalterms_info','If you enter a URL, then the users must accept before submitting a request');

lg.pg.admin.tools.customer.php (new file)

<?php

// SECURITY: Don't allow direct calls to this file outside the context of HelpSpot
if (!defined('cBASEPATH')) die();

/* EDITING NOTES
1. Some strings contain %s symbols, these must be maintained
2. Any single quotes must be preceded by a slash like this:  \'  ex: there\'s
3. If you modify this file, be sure to back it up in case you overwrite it during an upgrade by accident
*/

define('lg_admin_tools_customer_title','Customer Tools');
define('lg_admin_tools_customer_manage_data','Manage Customer Data');
define('lg_admin_tools_customer_export_data','Export Customer Data');
define('lg_admin_tools_customer_export_email','Export by Email');
define('lg_admin_tools_customer_email','Email');
define('lg_admin_tools_customer_email_address','Email Address');
define('lg_admin_tools_customer_export','Export');
define('lg_admin_tools_customer_delete_data','Delete Customer Data');
define('lg_admin_tools_customer_delete_request','Delete a request');
define('lg_admin_tools_customer_delete_request_note','Delete a request note');
define('lg_admin_tools_customer_delete_request_note_id','Note ID');
define('lg_admin_tools_customer_delete_request_note_info','This will permanently delete a single request history item along with any associated attachments.');
define('lg_admin_tools_customer_delete','Delete');
define('lg_admin_tools_customer_request_id','Request ID');
define('lg_admin_tools_customer_request_id_note','This will permanently delete a single request');
define('lg_admin_tools_customer_delete_by_email','Delete by Email');
define('lg_admin_tools_customer_delete_by_email_note','This will permanently delete anything in the database related to an email address.');
define('lg_admin_tools_customer_delete_by_id','Delete by Customer ID');
define('lg_admin_tools_customer_delete_by_id_note','This will permanently delete anything in the database related to a customer ID.');
define('lg_admin_tools_customer_sure','Are you sure you want to delete this?');
define('lg_admin_tools_customer_agree','You must type "I AGREE" to confirm.');
define('lg_admin_tools_customer_mutli_found','We found %s requests for %s. Are you sure you want to delete these?');
define('lg_admin_tools_customer_one_found','Are you sure you want to delete this?');
define('lg_admin_tools_customer_warning','<b>WARNING:</b> This operation is immediate and will <b>permanently delete</b>. Type "I AGREE" below to delete.');
define('lg_admin_tools_customer_confirm','Confirm');
define('lg_admin_tools_customer_finished','The request(s) have been deleted.');
?>

lg.pg.admin.tools.portals.php

//additions
define('lg_admin_portals_terms_enable','Ask customer to accept privacy policy and terms');
define('lg_admin_portals_portalterms','URL of terms of service');
define('lg_admin_portals_portalprivacy','URL of privacy policy');
define('lg_admin_portals_portalterms_info','If you enter a URL, then the users must accept before submitting a request');

lg.pg.admin.tools.templates.php

//additions
define('lg_admin_portaltemplates_temp_terms','HTML Elements for agreeing to the terms and privacy policy.');

lg.pg.conditional.ui.php

//additions
define('lg_conditional_at_thermostat_send','Send a Thermostat Survey');
define('lg_conditional_at_thermostat_add_email','Add Email to Survey Campaign');
define('lg_conditional_at_thermostat_score', 'Thermostat NPS Score');
define('lg_conditional_at_thermostat_promoter', 'promoter');
define('lg_conditional_at_thermostat_passive', 'passive');
define('lg_conditional_at_thermostat_detractor', 'detractor');
define('lg_conditional_at_ogintegrations','Integrations');

lg.pg.filter.requests.php

//additions
define('lg_filter_requests_ointegrations','Integrations');

lg.portal.php

//additions
define('lg_portal_agree_terms_privacy', 'I agree to the <a href="%s" target="_blank">Terms of Service</a> and <a href="%s" target="_blank">Privacy Policy</a>');
define('lg_portal_agree_terms', 'I agree to the <a href="%s" target="_blank">Terms of Service</a>');
define('lg_portal_agree_privacy', 'I agree to the <a href="%s" target="_blank">Privacy Policy</a>');
define('lg_portal_req_terms', 'You must agree to the terms');

15. HelpSpot 4 Portal Template Changes

Portal Template Changes

HelpSpot 4 contains only very minor template changes from Version 3.

As of HelpSpot 4.7.2+

request.tpl.php

These two code blocks can be included to allow CC and Subject line fields to appear.

To update your request.tpl.php file, add these lines below the sEmail field:

<?php if ($this->hd_allowCc): ?>
<p><label for="sCC" class="datalabel"><?php echo lg_portal_req_cc_email ?></label><br />
	<?php echo $this->helper->showError('sCC','<br />') ?>
	<input type="text" name="sCC" size="40" maxlength="250" value="<?php echo $this->request_sCC ?>" />
</p>
<?php endif; ?>

To update your request.tpl.php file to add the Subject Line field add these lines below this div.

Find:

<div class="forumoption"><?php echo lg_portal_req_detailsheader ?></div>

Below add

<?php if ($this->hd_allowSubject): ?>
        <p><label for="sCC" class="datalabel"><?php echo lg_portal_req_subject ?></label><br />
            <?php echo $this->helper->showError('sTitle','<br />') ?>
            <input type="text" name="sTitle" size="40" maxlength="250" value="<?php echo $this->request_sTitle ?>" />
        </p>
<?php endif; ?>

js.tpl.php

Find this line:

var password_confirm = $F('new_password_confirm');

Add this below:

var _token = $F('_token');

Find this line:

 parameters: {password: password_new},

Replace that line with this:

parameters: {password: password_new, _token: _token},

loginbar.tpl.php

Find this line:

<form onsubmit="return false;">

Below add:

<input type="hidden" name="_token" value="<?php echo $_SESSION['token']; ?>" id="_token">

As of HelpSpot 4.6+

js.tpl.php

Javascript is no longer loaded from a versioned directory.

To update your js.tpl.php file, find the following:

document.write('<script type="text/javascript" src="<?php echo $this->cf_primaryurl ?>/static_<?php echo $this->cf_version ?>/js/hs-js-combined-portal.php"></script>');

and update to

document.write('<script type="text/javascript" src="<?php echo $this->cf_primaryurl.elixir('js/helpspot.portal.js') ?>"></script>');

css.tpl.php

CSS is no longer loaded from a versioned directory.

To update your css.tpl.php file, find the following:

@import "<?php echo $this->cf_primaryurl ?>/static_<?php echo $this->cf_version ?>/js/jscal2/css/jscal2.css";

And update it to the following:

@import "<?php echo $this->cf_primaryurl ?>/static/js/jscal2/css/jscal2.css";

css.grey.tpl.php

CSS is no longer loaded from a versioned directory.

To update your css.grey.tpl.php file, find the following:

@import "<?php echo $this->cf_primaryurl ?>/static_<?php echo $this->cf_version ?>/js/jscal2/css/jscal2.css";

And update it to the following:

@import "<?php echo $this->cf_primaryurl ?>/static/js/jscal2/css/jscal2.css";

css.blue.tpl.php

CSS is no longer loaded from a versioned directory.

To update your css.blue.tpl.php file, find the following:

@import "<?php echo $this->cf_primaryurl ?>/static_<?php echo $this->cf_version ?>/js/jscal2/css/jscal2.css";

And update it to the following:

@import "<?php echo $this->cf_primaryurl ?>/static/js/jscal2/css/jscal2.css";

As of HelpSpot 4+

captcha.tpl.php

The largest change is that is uses a newer reCAPTCHA, which results in some changes to the helpspot/templates/captcha.tpl.php file.

The new captcha.tpl.php file is as follows:

<?php if($this->hd_useCaptcha == 1): ?>



	<p><label for="captcha" class="datalabel required"><?php echo lg_portal_captcha ?> - </label><b class="captcha_label"><?php echo $this->helper->encodeText($_SESSION['portal_captcha']) ?></b><br />

		<?php echo $this->helper->showError('captcha','<br />') ?>

		<input type="text" name="captcha" size="15" maxlength="250" value="" />

	</p>

	

<?php elseif($this->hd_useCaptcha == 2): ?>

	<?php echo $this->helper->reCaptcha( $this->hd_reCAPTCHALang ); ?>

	<?php /* <p><label for="recaptcha_response_field" class="datalabel required"><?php echo lg_portal_recaptcha ?></label> - <a href="javascript:Recaptcha.reload();"><?php echo lg_portal_recaptcha_changewords ?></a><br />

		<?php echo $this->helper->showError('recaptcha','<br />') ?>

		<?php echo $this->helper->reCaptcha(); ?>

	</p> */?>

<?php endif; ?>

forums.feed.tpl.php

One other minor change is that the Forums XML feed now assumes the UTF-8 character set (as does all of HelpSpot as of version 4).

To update your forums.feed.tpl.php file, find the following:

<?php echo '<?xml version="1.0" encoding="UTF-8"?>

And update it to the following:

<?php echo '<?xml version="1.0" encoding="UTF-8"?>' ?>

16. Troubleshooting

"Whoops, looks like something went wrong." error page.

This error message may be seen when attempting to install or during normal usage of HelpSpot. The error message on this page is rather generic, as the "data" directory not being writable is largely the most popular issue in HelpSpot 4.

As it suggests, it's important to ensure the "data" directory, and it's sub-directories, are writable by the web server.

Making the Data Directory Writable

HelpSpot comes with a directory called "data". This is written to by various processes in HelpSpot. Notably:

The data/cache directory, which has some cached items used by underlying code
The data/documents directory is the default path for email attachments saved to the file system
The data/logs directory contains a log file in which you can find system event and error information, included information that can be sent to HelpSpot support to help debug issues
The data/meta directory is similar to the cache directory, but used by particular set of underlying code
The data/views directory is a cache of view files used during the installation/update process

The data directory and subdirectories must be writable by the web server.

In Debian/Ubuntu, PHP is likely running as user "www-data". We can ensure these files are owned and writable by that user.

sudo chown -R www-data:www-data /path/to/helpspot/data
sudo chmod -R ug+rw /path/to/helpspot/data

In RedHat/CentOS, php is likely run as user "apache":

sudo chown -R apache:apache /path/to/helpspot/data
sudo chmod -R ug+rw /path/to/helpspot/data

If you run SELinux, then Apache needs to know that it can write to the data directory via the "httpd_sys_content_rw_t" type.

sudo chcon -Rv --type=httpd_sys_content_rw_t /path/to/helpspot/data

Server setup is outlined further for Debian/Ubuntu and RedHat/CentOS, including more possible configuration for SELinux.

Windows

The Windows installer will ensure the data directory is writable by the web server.

CLI Commands and Log File

When you update to HelpSpot 4, you might run commands before the data/logs/helpspot.log file exists. This file may get created as the user you run the command as, for example user "root" or another administrative user. If the data/logs/helpspot.log file is not writable, check to make sure it is owned by user "www-data" or "apache" as needed by your server type and setup.

My Data Directory is Writable, But I still See the Error Screen

If you still receive the blue error screen despite ensuring the data directory is writable, there is a way to get a better error message.

Edit the config.php file and change the "cDEBUG" variable from "false" to "true"

define('cDEBUG',      true);

If you re-run HelpSpot, you may see a error screen with more available information about the error in the browser. Furthermore, the bottom of the data/logs/helpspot.log file should contain the error and stack trace of the error, which can give clues to the error or be given to us to help you with the issue.

Tables Copied/Converted

The following tables are copied via the convert:base command:

HS_Settings
HS_Address_Book
HS_Automation_Rules
HS_Bayesian_Corpus
HS_Bayesian_MsgCounts
HS_Category
HS_Category_ReportingTags
HS_CustomFields
HS_Errors
HS_Filter_People
HS_Filter_Performance
HS_Filters
HS_Forums
HS_Forums_KnownUsers
HS_Forums_Posts
HS_Forums_Topics
HS_KB_Books
HS_KB_Chapters
HS_KB_Documents
HS_KB_Pages
HS_KB_RelatedPages
HS_Login_Attempts
HS_Mail_Rules
HS_Mailboxes
HS_Mailboxes_StuckEmails
HS_Multi_Portal
HS_Permission_Groups
HS_Person
HS_Person_Photos
HS_Person_Status
HS_Portal_Bayesian_Corpus
HS_Portal_Bayesian_MsgCounts
HS_Portal_Login
HS_Reset_Password
HS_Response_People
HS_Responses
HS_Saved_Reports
HS_Search_Queries
HS_Sessions2
HS_Tags
HS_Tags_Map
HS_Triggers
HS_luSMS
HS_luStatus

These tables are copied during the convert:request command:

HS_Assignment_Chain
HS_Documents
HS_Reminder
HS_Reminder_Person
HS_Request
HS_Request_History
HS_Request_Merged
HS_Request_Note_Drafts
HS_Request_Pushed
HS_Request_ReportingTags
HS_Stats_Responses
HS_Subscriptions
HS_Time_Tracker

Windows Installer Debugging

If you encounter and issue with the windows installer process you can obtain a detailed log of the issue during runtime.

Run the upgrade till the point of the error and then leave it on that screen.
Go to C:\Users\Administrator\AppData\Local\Temp\2 (replace Administrator with the user you are running the installer with)
In that directory there should be a bitrock_installer.txt file that will have logging information.