Deploy SupportPal on Docker (High Availability)

Deploy SupportPal using a multi-node configuration with Docker Compose on GNU/Linux. Experience with Docker is recommended.

Prerequisites

Ensure your system meets our recommended system requirements. Operating system and software requirements are already satisfied by our Docker containers.

Additional software is required to deploy SupportPal on Docker:

---

Installation & Configuration

Install SupportPal

To start the installation, run the following:

Linux / MacOS

bash <(curl -LsS https://raw.githubusercontent.com/supportpal/helpdesk-install/master/templates/docker-compose/setup.sh)

Windows

winpty bash <(curl -LsS https://raw.githubusercontent.com/supportpal/helpdesk-install/master/templates/docker-compose/setup.sh)

Next Steps

Congratulations, you've successfully installed SupportPal!

You can control the state of the containers via the make command:

make help

We now recommend that you learn how to administer your installation.

---

Customisation

In order to add customizations to the environment, Update the Makefile file, replacing the COMPOSE_FILES variable:

COMPOSE_FILES=-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml

All updates should be done in your docker-compose.custom.yml file, refer to the compose file specifications or instructions later in the setup.

Configuring HTTPS

By default, the software will run on HTTP using port 80, however we recommend using HTTPS for added security. To allow HTTPS, we provide an integration with LetsEncrypt, start the process with the following steps:

1. Change the current working directory to the docker-compose directory, for example:

   
           cd helpdesk-install/templates/docker-compose
           

2. Stop the containers if they are currently running:

   make stop

3. Update the Makefile file, by appending to the following string to COMPOSE_FILES variable, if the variable does not exist, copy its contents from Makefile.dist:

   -f docker-compose.https.yml

4. Add your help desk domain name to the .env.custom file. If you intend to use multiple domains / brands with your helpdesk, only specify one - it does not matter which one you choose.

   DOMAIN_NAME=example.com

You may now either set up a self-signed SSL certificate (if your domain is not available to the public), or a full LetsEncrypt SSL certificate for your domain.

Self-Signed SSL Certificate

Execute the script, replacing the top level domain names with your own. You can list as many domain names as you need:

./../../configs/letsencrypt/create-self-signed.sh -- example.com www.example.com

LetsEncrypt SSL Certificate

Execute the script, replacing the domain names and email address. You can list as many domain names as you need. At least one of the domain names needs to be the DOMAIN_NAME specified in the .env.custom file.

./../../configs/letsencrypt/init-letsencrypt.sh --email user@company.com -- example.com www.example.com

Restart the containers for your changes to take effect:

make restart

Configuring nginx

You can extend our default nginx configuration by making changes to templates/docker-compose/gateway/custom.conf within the helpdesk-install repository. See https://nginx.org/en/docs/ for assistance with nginx config directives.

Restart the containers for your changes to take effect:

make restart

Configuring PHP

You can extend our default PHP configuration by copying files into the containers.

1. Add PHP ini configuration files to the templates/docker-compose/php/ directory. The configuration inside these files will be merged with the default configuration, overriding them on duplication. See https://www.php.net/manual/en/configuration.file.php for assistance with PHP directives.
2. Restart the containers for your changes to take effect:

   make restart

Extending SupportPal

It is easy to extend your SupportPal installation. Simply add your files to the relevant directory in the helpdesk-install repository:

Extension	helpdesk-install Directory
Creating plugins	templates/docker-compose/customization/plugins
Creating reports	templates/docker-compose/customization/reports
Creating translations	templates/docker-compose/customization/languages
Creating themes	templates/docker-compose/customization/templates

The changes should be immediately visible in your SupportPal installation without needing to restart the containers.

---

Updating SupportPal config files

To create SupportPal config files, simply copy files from the host into the container. The example below copies customization/saml.php from the host to a container called supportpal:

docker cp customization/saml.php supportpal:/supportpal/config/production/

For more complex tasks, such as updating or removing configuration files create an interactive shell and administer it like a normal Linux machine:

docker compose exec supportpal bash

File changes in config/production/ will persist restart events as the directory is mounted as an external Docker volume.

Using the migration script

To get started using the migration script follow the below steps:

1. Download and extract migration script
2. Ensure the SupportPal docker containers are already running
3. In the directory where the migration script was extracted run:

   docker compose up -d

4. Access the migration script via http on port 8081 at the same hostname / IP address as the help desk. When finished with the migration script, run docker compose down -v to remove the container.
5. Configure Step 1
   1. Ensure the storage/ directory is writable by the www-data user:

      docker compose exec migrations chown -R 33:33 storage/

   2. Set the database details:
      • Hostname: db
      • Name: supportpal
      • Username: can be found in templates/docker-compose/secrets/db_user.txt
      • Password: can be found in templates/docker-compose/secrets/db_password.txt
   3. Set the application details:
      • Storage Path: /supportpal/storage
      • Application Key: can be found in config/production/app.php within the supportpal container

---

Uninstall

To completely remove your help desk installation, follow the steps below:

1. Change the current working directory to the docker-compose directory, for example:

   
           cd helpdesk-install/templates/docker-compose
           

2. Take a full backup.
3. Run the uninstall command:

   Linux

   sudo make uninstall

   MacOS / Windows

   make uninstall