Home → Installation and Upgrade Manual → HelpSpot 5 Installation → HelpSpot 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:

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.