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
- Run the installer command
- View HelpSpot in the web browser
- Setup CRON tasks
- Setup Queue worker
Your HelpSpot server should be configured to meet the server requirements prior to beginning installation.
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
The HelpSpot files include a
publicdirectory to be used as the public web root. The webroot configured in Nginx/Apache should therefore be configured to point to the
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.
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
truewill show full error stack traces in the web browser if errors occur. Errors will always appear in the log file at
storage/logs/helpspot.logwhether this is set to
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
DB_CONNECTION- one of
mysqlfor 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
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
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
- Admin area at
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
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
More documentation on setting up the queue worker can be found here.