SupportPal Documentation

New Installation

Contents

Checking Requirements

In order for SupportPal to function correctly, a number of System Requirements need to be met. Before attempting an installation and to avoid potential issues later, please ensure these are in place.

Prerequisites

License

An active license with valid support and updates coverage is required to download and install SupportPal. Our 30 day free trial is the easiest way to try SupportPal. Owned licenses include 6 months from date of purchase and monthly licenses include lifetime support and updates.

Web Server

Depending on the web server you are running, you may need to configure it further to run SupportPal correctly - for example, ensuring all the HTTP request verbs are enabled. Below is a list of common web servers and steps required for them.

Apache

Apache is supported out of the box.

nginx

On nginx, please create a new virtual host for SupportPal. The below is an example virtual host but will need editing for your specific environment (paths may vary):

server {
    listen 80;
    listen [::]:80;

    server_name supportpal.app;

    root /var/www/supportpal;
    index index.php;

    # Remove index.php from GET requests.
    set $user_request 0;
    if ($request_method = GET) {
        set $user_request "GET";
    }
    if ($request_uri ~* "^(.*/)index\.php/?(.*)$") {
        set $user_request "${user_request}-index.php";
    }
    if ($user_request = "GET-index.php") {
        return 301 $1$2;
    }

    # Send all requests to SupportPal.
    location / {
        try_files /notexistent @backend;
    }

    # Allow direct access to asset files, if they don't exist show SupportPal 404 error page.
    location ~* \.(css|gif|ico|je?pg|js|png|swf|txt|eot|ttf|woff|woff2|svg|map)$ {
        try_files $uri $uri/ @backend;
    }

    # Allow direct access to resources/assets files, if they don't exist show SupportPal 404 error page.
    location resources/assets/ {
        try_files $uri $uri/ @backend;
    }

    # All SupportPal requests must be sent through index.php.
    location @backend {
        rewrite ^(.*)$ /index.php last;
    }

    location ~ \.php($|/) {
        include snippets/fastcgi-php.conf;

        # With php-fpm:
        fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;
    }
}

IIS

On IIS, please create a web.config file in the root of your installation directory with the below contents:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <staticContent>
            <remove fileExtension=".woff" />
            <remove fileExtension=".woff2" />
            <remove fileExtension=".json" />
            <mimeMap fileExtension=".woff" mimeType="application/x-font-woff" />
            <mimeMap fileExtension=".woff2" mimeType="application/font-woff2" />
            <mimeMap fileExtension=".json" mimeType="application/json" />
        </staticContent>
        <rewrite>
            <rules>
                <rule name="Add trailing slash to base" stopProcessing="true">
                    <match url="^$" ignoreCase="false" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{URL}" pattern="[^\/]$" />
                    </conditions>
                    <action type="Redirect" url="<supportpal_base_url>/" />
                </rule>
                <rule name="Remove index.php" stopProcessing="true">
                    <match url="^index.php/?(.*)$" ignoreCase="false" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{REQUEST_METHOD}" pattern="GET" />
                        <add input="{URL}" pattern="^.*/index\.php" />
                    </conditions>
                    <action type="Redirect" redirectType="Permanent" url="<supportpal_base_url>/{R:1}" appendQueryString="true" />
                </rule>
                <rule name="Allow assets" stopProcessing="true">
                    <match url="^" ignoreCase="false" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{REQUEST_FILENAME}" matchType="IsFile" ignoreCase="false" />
                        <add input="{URL}" pattern="(resources/assets/|\.(css|gif|ico|je?pg|js|png|swf|txt|eot|ttf|woff|woff2|svg|map)$)" />
                    </conditions>
                    <action type="None" />
                </rule>
                <rule name="Rewrite all else to index.php" stopProcessing="true">
                    <match url="^" ignoreCase="false" />
                    <action type="Rewrite" url="index.php" />
                </rule>
            </rules>
            <outboundRules>
                <rule name="fix content-type" preCondition="PHPRequest">
                    <match serverVariable="RESPONSE_CONTENT_TYPE" pattern="text/html; charset=UTF-8,([^\/]+\/.+$)" ignoreCase="true" />
                    <action type="Rewrite" value="{R:1}" />
                </rule>
                <preConditions>
                    <preCondition name="PHPRequest">
                        <add input="{REQUEST_URI}" pattern=".*\.php" />
                    </preCondition>
                    <preCondition name="ResponseIsHtml1">
                        <add input="{RESPONSE_CONTENT_TYPE}" pattern="^text/html" />
                    </preCondition>
                </preConditions>
            </outboundRules>
        </rewrite>
        <handlers>
            <remove name="WebDAV" />
            <remove name="PHP-php" />
            <remove name="ExtensionlessUrlHandler-Integrated-4.0" />
            <add name="ExtensionlessUrlHandler-Integrated-4.0" path="*." verb="GET,HEAD,POST,DEBUG,PUT,DELETE" type="System.Web.Handlers.TransferRequestHandler" resourceType="Unspecified" requireAccess="Script" preCondition="integratedMode,runtimeVersionv4.0" responseBufferLimit="0" />
            <add name="PHP-php" path="*.php" verb="GET,HEAD,POST,PUT,DELETE" modules="FastCgiModule" scriptProcessor="<absolute_path_to_php_cgi.exe>" resourceType="Either" requireAccess="Script" />
        </handlers>
        <httpErrors errorMode="Detailed" />
        <modules>
            <remove name="WebDAVModule" />
        </modules>
    </system.webServer>
    <system.web>
        <authentication mode="Forms" />
    </system.web>
</configuration>

Installation Steps

The SupportPal installation process is fairly simple, follow the following steps to get started:

1. Download SupportPal

Download the current stable release at our downloads area (client area login required).

2. Upload, Extract and Set File Permissions

Upload the zip file to your web server (If you are using FTP use Binary Mode) to the required location and unzip the contents.

Ensure the relevant directories are writeable by the PHP/Web Server process. Check the System Requirements for more information.

3. Run Installer

SupportPal can be installed through the web installer (user friendly) or the command line installer (advanced).
Web Installer
  1. Start the install process by visiting the URL where you have uploaded SupportPal, e.g. http://yourdomain.com/support.
  2. Verify the right version shows in the installation type and click continue.
  3. Read through our EULA and accept.
  4. The installer will verify if your server passes the system requirements. If anything shows a cross, please correct and retry. It's worth checking over optional requirements in case it covers a feature you'd like to use. Continue when everything required passes.
  5. Enter your database details, the installer will try to create a database with that name if one doesn't already exist.
  6. Click the 'Begin' button, this will start the process of running the database migrations and seeds. This may take several minutes, wait for it to complete and then click 'Continue' once the button shows.
  7. Enter your license key, and it should show a 'License Valid' below. If it doesn't, you may need to re-issue the license at our client area and then enter it again. Also fill in your operator account details and continue.
  8. Enter your company information and change the locale settings as necessary and continue.
  9. The installation is complete, keep a note of the operator panel login URL.
Command Line Installer

  1. In a shell, change the current working directory to where the SupportPal files were uploaded (e.g. cd /var/www/html/support).
  2. The installer can be ran in interactive mode, or non-interactive mode by passing a path to a JSON config file.

    For interactive mode, run:

    php artisan app:install

    A number of options will show that you'll need to fill before the installation can start.

    For non-interactive mode, run:

    php artisan app:install /full/path/to/file.json

    For this, you'll need to create and upload a configuration file to your server. Take our example file below.

    install.json
  3. Assuming everything entered validates correctly, the database migrations and seeds will run and this may take several minutes to complete.
  4. Finally when it shows the installation has completed, you can login by appending /admin to your install location. For example if SupportPal was installed at http://yourdomain.com/support, the operator panel can be accessed by going to http://yourdomain.com/support/admin

4. Set up the Cron Job

The cron job is used to perform background tasks such as sending emails and closing inactive tickets. To setup the cron job please create the below cron entry, replacing <supportpal_base_path> with your own path:

cPanel

Select Cron Jobs from the dashboard, browse down the page to Add New Cron Job. Then, select Once per minute from the Common Settings dropdown, and input the following into the Command box:

php -q /<supportpal_base_path>/cron

Linux

To ensure that the cron job runs as the web server user, please add the following entry to the /etc/crontab file replacing <web_server_user> and <supportpal_base_path> with your servers details:

* * * * * <web_server_user> php -q /<supportpal_base_path>/cron

Windows

The cron should be setup through the Windows Task Scheduler, using a command similar to the below (you may need to change the file paths):

C:\Program Files (x86)\PHP\v7.0\php-cgi.exe -q c:\inetpub\wwwroot\cron

Post Installation Steps

Congratulations, you've successfully installed SupportPal! We recommend carrying out the following as your first steps when getting started.

Login to the Operator Panel

After completing the installation, we recommend to log in to the operator panel and walk through the getting started guide. Further information about the various settings available can be found in the Configuration section.

Please note that the frontend (for your users) and operator panel are separate areas, your login will only work on the operator panel.

Rename the Admin Folder

From a security point of view, it is a good idea to change the default operator panel URL prefix from admin to something that only your staff know. The prefix can be updated in the Settings area in the operator panel.

Enable SSL

If you've installed a SSL certificate on the server, we recommend to enable SSL mode. This will mean the whole help desk will operate over HTTPS at all times. SSL mode can be enabled by going to the Settings area in the operator panel.

Pretty URLs

Apache

SupportPal ships with a .htaccess file that is used to allow URLs without index.php. If the included .htaccess file doesn't work automatically, you may need to set the AllowOverride directive in the Apache configuration to All and ensure that the mod_rewrite module is enabled.

Other

Using and adapting our example configurations for nginx or IIS should mean pretty URLs works already. You may just need to toggle the option in the Settings area in the operator panel if it is not automatically enabled.

Verify the Cron is Running

As the cron job is used to send out emails amongst many other tasks, it is paramount that it is running successfully. You can verify it is running by going to Settings -> General -> Scheduled Tasks, the status bar will be green and all the tasks will have a recent last run time. Otherwise you should check over the configuration of the cron job, this includes ensuring the configuration for PHP CLI (usually different to the web server process) also passes the system requirements.

Common Issues

For common issues please see our Frequently Asked Questions.