1.8. 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
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
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:
- A file in
- 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.
More details and examples can be found in the Linux Server Administrations documentation
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.
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.
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_pagesdirectories, BlackBox or AD authentication files)
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
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
First, we'll cover changes to the primary portal:
custom_templates directory for the primary portal has been moved from the root directory (
/path/to/helpspot/custom_templates) to the public web root
So, if that directory used to be located at
/var/www/helpspot/custom_templates, those customizations should be restored to
For secondary portals, there are several changes:
- Secondary portal directories should be moved from the into the
publicdirectory - for example, from
- The configuration for secondary portals (
Admin > Customize > Secondary Portals) should be updated with the new
File Directory Pathsetting (to include the
- 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.phpfile needed within portal directories
index.phpfile created has been changed. Saving the secondary portals settings will generate a new
There are more details about HelpSpot 5 Portal changes here. These include:
- Configuration changes
- Updates to portal templates
Custom Scripts and Pages
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
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
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
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.