Home → Installation and Upgrade Manual → Upgrading From HelpSpot 4.9.5 To HelpSpot 5.x → Updating to HelpSpot 5 - Linux

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:

  1. Ensure your server environment meets the minimum requirements for HelpSpot 5
  2. Backing up HelpSpot 4 files and database
  3. Removing HelpSpot 4 CRON tasks
  4. Running HelpSpot 5 Update Tasks
  5. Restoring Files and Customizations
  6. Configuring HelpSpot 5 CRON tasks
  7. 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.

  1. This allows you to roll back if needed
  2. 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:

  1. Within /etc/crontab
  2. A file in /etc/cron.d
  3. 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:

  1. Update the HelpSpot files
  2. Configure your web server
  3. 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:

  1. Attachment files, if saved to disk (recommended) rather than the database
  2. Portal files and customizations
  3. 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:

  1. 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.
  2. The configuration for secondary portals (Admin > Customize > Secondary Portals) should be updated with the new File Directory Path setting (to include the public directory)
  3. Saving changes to any Secondary Portal should update the portal's file-based configuration to HelpSpot 5's standards
  4. There is no longer a config.php file needed within portal directories
  5. 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:

  1. Configuration changes
  2. 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.

This page was: Helpful | Not Helpful
Updating to HelpSpot 5 - Windows →