HomeInstallation and Upgrade ManualHelpSpot 5 InstallationHelpSpot Linux Installation

1.3. HelpSpot Linux Installation

The general steps for installing HelpSpot on linux are:

  1. Ensure server is ready to serve a PHP application
  2. Add HelpSpot files to the web server
  3. Configure the .env file
  4. Run the installer command
  5. View HelpSpot in the web browser
  6. Setup CRON tasks
  7. 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:




Here are some details on the configuration:

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:


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.

This page was: Helpful | Not Helpful