Deploy SupportPal on Docker

Deploy SupportPal using a monolithic image which runs all the necessary services in a single container. If you want to install a high availability setup use Deploy On Docker (High Availability).

Prerequisites

• Docker Engine
• Docker Compose

Installation

Our docker compose deployment makes use of an example docker-compose.yml file. The default configuration only enables HTTP. External docker volumes are also used to ensure your data is safe from accidental deletion.

1. Use the setup script to quickly get started with your deployment:
   The script must be run in a bash compatible terminal. If you're on Windows, use Git Bash.

   Linux / MacOS

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

   Windows

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

2. Review the generated docker-compose.override.yml file:
   • It may be necessary to update the server hostname.
   • See customisation for additional configuration options such as how to enable HTTPS.
3. Start the containers:

   docker compose up -d

4. Install SupportPal:

   docker compose exec supportpal /bin/bash /init/init-helpdesk.sh

Customisation

Below several options are described which enable you to customise your installation.

Enable HTTPS

Free SSL for one domain name (via LetsEncrypt)

When both ports 80 and 443 are published SupportPal will automatically create an SSL certificate via LetsEncrypt for your container hostname. Note: this is intended to help you quickly get started and only works with one domain name. For more complex configurations, such as multiple brands, please read the next section.

1. Create or update docker-compose.override.yml, for example:

   
   version: '3.8'
   
   services:
       supportpal:
           hostname: 'supportpal.example.com'
           ports:
               - '443:443'
   

2. Rebuild the container.

   docker compose down && docker compose up -d

More than one domain / your own certificates

If you need SSL certificates for more than one domain, or already have your own certificates we recommend to use docker-compose to setup a reverse proxy. The proxy should forward incoming connections to the supportpal container on port 8080.

Do not publish any ports on the supportpal container. The reverse proxy should publish ports 80 and 443.

Customising php-fpm pool config

1. Create php/pool.d/custom.conf in the same directory as your docker-compose.yml file with contents:

   pm.process_idle_timeout = 30s

2. Create or update docker-compose.override.yml, for example:

   
   version: '3.8'
   
   services:
       supportpal:
           volumes:
               - ./php/pool.d/:/etc/supportpal/php/pool.d/
   

3. Rebuild the container:

   docker compose down && docker compose up -d

Customising PHP

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

1. Create php/conf.d/99-custom.ini in the same directory as your docker-compose.yml file
2. Add your PHP configuration to the file. See https://www.php.net/manual/en/configuration.file.php for assistance with PHP directives.
3. Create or update docker-compose.override.yml, for example:

   
   version: '3.8'
   
   services:
       supportpal:
           volumes:
               - ./php/conf.d/:/etc/supportpal/php/conf.d/
   

   You can change the 99 in the filename to control the priority that the file is loaded.
4. Rebuild the container:

   docker compose down && docker compose up -d

Extending SupportPal

To extend your SupportPal installation (create plugins, report, translations, themes, etc):

1. Create a directory named customization in the same directory as your docker-compose.yml file
2. Create or update docker-compose.override.yml, for example:

   
   version: '3.8'
   
   services:
       supportpal:
           volumes:
               - ./customization:/customization
   

3. Create a subdirectory within the customization directory for the relevant extension (see table below).

   Extension	Path name
   Creating plugins	customization/plugins
   Creating reports	customization/reports
   Creating translations	customization/languages
   Creating themes	customization/templates

4. Add your extensions to the directory
5. Rebuild the container:

   docker compose down && docker compose up -d

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:/var/www/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.

Disable the cron job

1. Update docker-compose.override.yml, for example:

   
   version: '3.8'
   
   services:
       supportpal:
           environment:
               CRON_ENABLED: 0
   

2. Rebuild the container:

   docker compose down && docker compose up -d

Using the migration script

1. Update docker-compose.override.yml, for example:

   
   version: '3.8'
   
   services:
       supportpal:
           environment:
               CRON_ENABLED: 0
               MIGRATOR_MODE: 1
           volumes:
               - ./relative/path/to/migration_script:/var/www/migrator
           ports:
               - '8081:8081'
   

2. Rebuild the container:

   docker compose down && docker compose up -d

The migration script can be accessed via http on port 8081 at the same hostname / IP address as the help desk.

Troubleshooting

Diagnosing potential issues

Read container logs:

docker compose logs supportpal

Enter running container and debug like a normal Linux server:

docker compose exec supportpal bash

Container won't start

If the container won't start due to errors during the entry point script, you can start an interactive console using:

docker commit supportpal debug/supportpal
docker run --rm -it --entrypoint=/bin/bash debug/supportpal

Docker containers exhausts space

Docker's default logging driver is json-file, which performs no log rotation by default. As a result of this lack of rotation, log files stored by the json-file driver can consume a significant amount of disk space for containers that generate a lot of output. This can lead to disk space exhaustion. To address this, use journald as the logging driver. See the docker compose logging directive for more help.