Home → Installation and Upgrade Manual → HelpSpot 5 Installation → Linux Server Administration

1.8. Linux Server Administration

Linux Server Administration

Webroot Configuration

HelpSpot 5 introduces a new directory in its code base that is intended to be used as the web server's public root directory. That directory is named public.

Web servers should update their web root directive as follows:

Nginx: Update the root directive, e.g. root /var/www/helpspot/public;
Apache: Update the DocumentRoot directive, e.g. DocumentRoot /var/www/helpspot/public

In HelpSpot 4 and earlier, web server configuration's pointed the web root (root in Nginx, DocumentRoot in Apache) to HelpSpot's root directory.

For example, if HelpSpot was installed at /var/www/helpspot, then the web server's web root would be located at the same directory, /var/www/helpspot.

HelpSpot 5 uses the public directory as an added security measure. It ensures that HelpSpot's code files are not accessible to the public internet. Security measures were previously in place to prevent this, but this adds an extra layer of security.

Nginx Configuration

Here's an example Nginx configuration, which assumes PHP-FPM for PHP 8.3 is installed.

This configuration assumes an SSL certificate is used.

server {
    # Enforce the use of HTTPS
    listen 80 default_server;
    server_name example.org;
    return 301 https://$host$request_uri;
}

server {
    listen 443 default_server ssl;

    root /var/www/helpspot/public;
    index index.html index.htm index.php;

    access_log /var/log/nginx/helpspot.log helpspot;
    error_log  /var/log/nginx/helpspot-error.log error;

    server_name example.org;

    charset utf-8;

    ssl_certificate           /etc/ssl/helpspot/example.org.crt;
    ssl_certificate_key       /etc/ssl/helpspot/example.org.key;

    # Allow lets encrypt checks
    location ^~ /.well-known/acme-challenge/ {
        allow all;
    }

    # Disallow dot file access
    location ~* (?:^|/)\. {
        deny all;
    }

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location = /favicon.ico { log_not_found off; access_log off; }
    location = /robots.txt  { log_not_found off; access_log off; }

    location ~ \.php$ {
        # This included snippet is on Debian/Ubuntu servers but
        # may not be on RedHat/CentOS/Fedora/AWS Linux servers
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_buffers 36 64k;
        fastcgi_buffer_size 32k;
        fastcgi_read_timeout 120s;
    }
}

We have detailed video examples of configuring Linux servers for use with HelpSpot 5 available here:

HelpSpot in Subdirectory

If HelpSpot is being used in a subdirectory, the following Nginx configuration can help make that work:

server {
    listen 443 default_server ssl;

    # We assume the example.org website is hosted
    # out of the /var/www/html directory
    root /var/www/html;

    index index.html index.htm index.php;

    access_log /var/log/nginx/example.org.log helpspot;
    error_log  /var/log/nginx/example.org.log error;

    server_name example.org;

    charset utf-8;

    ssl_certificate           /etc/ssl/helpspot/example.org.crt;
    ssl_certificate_key       /etc/ssl/helpspot/example.org.key;

    # Allow lets encrypt checks
    location ^~ /.well-known/acme-challenge/ {
        allow all;
    }

    # Disallow dot file access
    location ~* (?:^|/)\. {
        deny all;
    }

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    # If HelpSpot is served from the "/helpdesk" subdirectory
    # then we create a location {} block for it and use
    # an alias to point to the correct web root for HelpSpot
    location /helpdesk {
        alias /var/www/helpspot/public;
        try_files $uri $uri/ @nested;

        location ~ \.php$ {
            include snippets/fastcgi-php.conf;
            fastcgi_param SCRIPT_FILENAME $request_filename;
            fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
            fastcgi_buffers 36 64k;
            fastcgi_buffer_size 32k;
            fastcgi_read_timeout 120s;
        }
    }

    # We also need a rewrite to correctly rewrite the
    # /helpdesk subdirectory, so we don't need index.php
    # in the URI
    location @nested {
        rewrite /helpdesk/(.*)$ /helpdesk/index.php?/$1 last;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_buffers 36 64k;
        fastcgi_buffer_size 32k;
        fastcgi_read_timeout 120s;
    }
}

Note that we installed the HelpSpot code base outside of the web root for the main site.

The web root for example.org is found in /var/www/html while the web root for the HelpSpot installation is found within the HelpSpot code base at /var/www/helpspot. This prevents unauthorized access to HelpSpot code files so we don't, for example, make secrets available within the URL http://example.org/helpspot/.env, which could happen if the HelpSpot code files were installed into directory /var/www/html/helpspot.

Apache Configuration

Here's an example Apache configuration, which assumes the following Apache modules are installed and enabled:

PHP module
Rewrite module

<VirtualHost *:80>
    ServerName support.example.com
    DocumentRoot /var/www/example.org/public

    <Directory /var/www/example.org/public>
        Options -Indexes +FollowSymLinks +MultiViews 
        # Allow .htaccess file usage: 
        AllowOverride All 
        Require all granted
    </Directory>

    # Disallow access to dotfiles
    # such as the .env file
    <FilesMatch "^\.">
        Order allow,deny
        Deny from all
    </FilesMatch>

    ErrorLog ${APACHE_LOG_DIR}/example.org-error.log
    # Possible values include: debug, info, notice, warn, error, crit, 
    # alert, emerg. LogLevel warn
    CustomLog ${APACHE_LOG_DIR}/example.org-access.log combined
</VirtualHost>

HelpSpot in Subdirectory

If HelpSpot is installed into a subdirectory, some extra configuration will be required.

For example, if HelpSpot is accessed in the URL /helpdesk (e.g. https://example.org/helpdesk), the following configuration will work for HelpSpot 5.

This assumes the following Apache modules are installed an enabled:

PHP module
Rewrite module
Alias module

<VirtualHost *:80>
    ServerName example.org
    # We assume the example.org website is hosted
    # out of the /var/www/html directory
    DocumentRoot /var/www/html

    # If HelpSpot is served from the "/helpdesk" subdirectory
    # then we can use an Alias to tell Apache where to find 
    # the HelpSpot site files. In this case, "/var/www/helpspot"
    # (HelpSpot's webroot is the "public" directory within the
    # code base, e.g. "/var/www/helpspot/public").
    Alias "/helpdesk" "/var/www/helpspot/public"
    <Directory /var/www/helpspot/public>
        Options -Indexes +FollowSymLinks +MultiViews 
        # Allow .htaccess file usage: 
        AllowOverride All 
        Require all granted
    </Directory>

    # Disallow access to dotfiles
    # such as the .env file
    <FilesMatch "^\.">
        Order allow,deny
        Deny from all
    </FilesMatch>

    ErrorLog ${APACHE_LOG_DIR}/example.org-error.log
    # Possible values include: debug, info, notice, warn, error, crit, 
    # alert, emerg. LogLevel warn
    CustomLog ${APACHE_LOG_DIR}/example.org-access.log combined
</VirtualHost>

Then we need to update the .htaccess file. Within the public directory is a file named .htaccess, e.g. /var/www/helpspot/public/.htaccess. This file needs to be edited to add the RewriteBase directive to include the subdirectory /helpdesk:

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews
    </IfModule>
    
    RewriteEngine On
    
    # Redirect Trailing Slashes If Not A Folder...
    RewriteBase /helpdesk
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)/$ /$1 [L,R=301]
    
    # Handle Front Controller...
    RewriteBase /helpdesk
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
    
    # Handle Authorization Header
    RewriteBase /helpdesk
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
</IfModule>

Note that we installed the HelpSpot code base outside of the web root for the main site.

CRON Configuration

HelpSpot requires some periodic tasks to be run. On Linux systems, these are powered by CRON.

The HelpSpot 5 code base include an example CRON configuration found in the file 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 for HelpSpot 5:

# Timing    User       Command
* * * * *   www-data   cd /var/www/helpspot && /usr/bin/php hs schedule:run

You may need to adjust the system user that runs the task, as well as the above 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.

The schedule:run command periodically runs other sub-commands which perform various tasks such as checking for new emails, cleaning out error log tables, sending email reports, running automation rules, and more.

Checking Email Mailboxes for new mail occurs every 1 minute by default, but a CRON expression can be used to change that timing by modifying the .env file and adding a MAIL_CRON_INTERVAL option:

# Default, check every one minute
MAIL_CRON_INTERVAL="* * * * *"

For example, to check email every 5 minutes, you can add the following to your .env file:

# Check mail every 5 minutes
MAIL_CRON_INTERVAL="*/5 * * * *"

You can also disable checking emails by editing the .env file and adding the following:

# Disable mail checks
AUTO_COLLECT_MAIL=false

You can then check email mailboxes directly using the following command (either manually or as a new CRON task):

# Check all mailboxes
php hs mail:check

# Check specific mailboxes
php hs mail:check --id=1
php hs mail:check --id=1,2,3

Queue Worker Configuration

HelpSpot uses a queue worker to process incoming and outgoing emails.

The command to process jobs in the queue worker is as follows:

php hs queue:listen database --queue=high,default --sleep=3 --tries=3

This command should be run in a way that restarts on failure and when the server is rebooted. To accomplish that, an "init" system such as Supervisord or Systemd should be used.

Supervisord is recommended as it allows you to run more than one queue worker process easily. We recommend running 2+ worker processes (2 of the above commands).

Systemd is available on most Linux systems without needing to install extra software. A limitation is that a service can only run one process, however as mentioned, we recommend running 2+ worker processes. This can be accomplished with 2 separate Systemd configurations if you choose.

The HelpSpot 5 code base comes with configuration examples for Supervisord and Systemd within the helpers/init directory.

Supervisord

You can install supervisord by running one of the following:

# Debian/Ubuntu
sudo apt-get install -y supervisor

# CentOS/RedHat/Fedora
sudo yum install -y supervisor
sudo systemctl enable supervisor
sudo systemctl start supervisor

If you are using the recommended Supervisord, the helpers/init/helpspot-supervisord.conf file can go into the /etc/supervisor/conf.d directory.

If that directory does not exist, the configuration can be copied into file /etc/supervisor/supervisor.conf or /etc/supervisord.conf (the exact path varies by Linux OS).

Be sure to edit the file if needed to change the user the service runs as, the log file path if required, and the number of worker processes to run (2+).

After placing the file, run:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start helpspot:*

As mentioned, you'll likely want to customize some configurations in the file:

command: The command should be changed to use the correct file paths for the location of your HelpSpot installation
user: The proper user should be configured to run the process, usually the same user that runs the PHP web server
numprocs: The number of worker processes to run. We recommend starting with 2 and adding more if your HelpSpot installation monitors many Email Mailboxes.
stdout_logfile: Adjust the log file path to a path of your choosing

Systemd

If you are using Systemd, the helpers/init/helpspot.service file can be placed in directory /etc/systemd/system/ or /lib/systemd/system/.

Note that we recommend using Supervisord instead of Systemd.

After placing the file, run:

sudo systemctl enable helpspot
sudo systemctl start helpspot

Note that you'll likely want to customize some configuration in the file:

ExecStart: The command may need adjusting, for example if PHP is installed in a different location
WorkingDirectory: The working directory should be adjusted to the path that HelpSpot is installed in
User/Group: The proper user should be configured to run the process, usually the same user that runs the PHP web server

This page was: Helpful | Not Helpful

← Installing HelpSpot 5 On Windows Step by Step .env Config (Self Hosted) →