Deploy SupportPal on Docker

Deploy SupportPal using a monolithic image which runs all the necessary services in a single container.

Prerequisites

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.

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.
```
bash <(curl -LsS https://raw.githubusercontent.com/supportpal/helpdesk-install/5.x/templates/docker-monolithic/setup.sh)
```
Browse to the created installation directory, noted in the setup.sh output. For example:
```
cd supportpal_1745496963_5176
```
Review the generated .env file:
- It may be necessary to update the DOMAIN_NAME environment variable. This specifies the domain that appears in mail that is posted on this machine.
- See customisation for additional configuration options such as how to enable HTTPS.
Start the containers:
```
docker compose up -d
```

Install SupportPal:

docker compose exec supportpal bash -c "bash /init/init-helpdesk.sh"

Customisation

Do not edit the default docker-compose.yml file.

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

Enable HTTPS

Free SSL (via LetsEncrypt / ZeroSSL)

HTTPS can be quickly enabled for multiple domain names using free SSL certificates provided by LetsEncrypt / ZeroSSL. The certificates are automatically renewed.

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


version: '3.8'

services:
    supportpal:
        ports:
            - '443:443'
        environment:
            HTTPS_ENABLED: 1
            EMAIL_ADDRESS: "my@email.com"
            DOMAIN_NAMES: "help.domain.com, support.domain.com"

Replace the EMAIL_ADDRESS environment variable with a valid address. It can be used to manage your SSL certificates at the ACME service (LetsEncrypt / ZeroSSL).
Replace the DOMAIN_NAMES environment variable with comma delimited domain names. Each domain must have correctly configured DNS.

Rebuild the container.

docker compose down && docker compose up -d

Using your own certificates

For more complex SSL configurations, such as using your own certificates, you can override the default Caddyfile. If you intend to use the migration script, we recommend to run the migration first before providing your own Caddyfile implementation.

Create a caddy directory within the same path as your docker-compose.yml file.

Create caddy/Caddyfile.
In the example below, we're asking for a free LetsEncrypt / ZeroSSL certificate to be issued for support.brand1.com, help.brand1.com and help.brand2.com are both using purchased wildcard SSL certificates for the respective brands.

Caddyfile Expand Collapse


{
  import /etc/supportpal/caddy/globals.Caddyfile
}

support.brand1.com {
  import /etc/supportpal/caddy/helpdesk.Caddyfile
}

help.brand1.com {
  tls /etc/ssl/star.brand1.com.crt /etc/ssl/star.brand1.com.key
  import /etc/supportpal/caddy/helpdesk.Caddyfile
}

help.brand2.com {
  tls /etc/ssl/star.brand2.com.crt /etc/ssl/star.brand2.com.key
  import /etc/supportpal/caddy/helpdesk.Caddyfile
}

Create an ssl/ directory within the same path as your docker-compose.yml files, and add your certificate files to that directory.

Create or update docker-compose.override.yml using the example below. Change the filenames for the SSL certificates as appropriate.


version: '3.8'

services:
    supportpal:
        ports:
            - '443:443'
        environment:
            CADDY_CONFIG_PATH: /etc/supportpal/Caddyfile
        volumes:
            - ./caddy/Caddyfile:/etc/supportpal/Caddyfile
            - ./ssl/star.brand2.com.crt:/etc/ssl/star.brand2.com.crt
            - ./ssl/star.brand2.com.key:/etc/ssl/star.brand2.com.key

Rebuild the container:

docker compose down && docker compose up -d

Add a private certificate authority

Create an ssl directory within the same path as your docker-compose.yml file, and add your certificate authority file to it.

Create or update docker-compose.override.yml using the example below:


version: '3.8'

services:
    supportpal:
        volumes:
            - ./ssl/foo.crt:/usr/local/share/ca-certificates/foo.crt

Note that all certificates must use the .crt extension.

Rebuild the container:

docker compose down && docker compose up -d

Customising php-fpm pool config

Create php/pool.d/custom.conf in the same directory as your docker-compose.yml file with contents:
```
pm.process_idle_timeout = 30s
```

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


version: '3.8'

services:
    supportpal:
        volumes:
            - ./php/pool.d/:/etc/supportpal/php/pool.d/

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.

Create php/conf.d/99-custom.ini in the same directory as your docker-compose.yml file
Add your PHP configuration to the file. See https://www.php.net/manual/en/configuration.file.php for assistance with PHP directives.
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.

Rebuild the container:

docker compose down && docker compose up -d

Customising MySQL

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

Create mysql/99_custom.cnf in the same directory as your docker-compose.yml file
Add your MySQL configuration to the file. See https://dev.mysql.com/doc/refman/8.4/en/server-options.html for assistance with MySQL server options. For example:
```
        [mysqld]
        max_connections=1000
        
```
Create or update docker-compose.override.yml, for example:
```
version: '3.8'

services:
    supportpal:
        volumes:
            - ./mysql/99_custom.cnf:/etc/mysql/conf.d/99_custom.cnf
```
You can change the 99 in the filename to control the priority that the file is loaded.

Rebuild the container:

docker compose down && docker compose up -d

Extending SupportPal

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

Browse to directory where the docker-compose.yml file is

Add a customization volume mount to docker-compose.override.yml, for example:


version: '3.8'

services:
    supportpal:
        volumes:
            - ./customization:/customization

Create a customization directory for the relevant extension (see table below), for example:

mkdir -p customization/languages

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

Create the extension.
If this requires running a make:* command to automatically generate the extension, it can be achieved as shown below. First the extension is generated, then the files copied from the container to host customization directory, and finally the files removed from the container so that they can be mounted via the customization volume.
```
            docker exec -it supportpal php artisan make:language it
            docker cp supportpal:/var/www/supportpal/addons/Languages/Italian ./customization/languages/Italian
            docker exec supportpal rm -rf /var/www/supportpal/addons/Languages/Italian
        
```

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

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


version: '3.8'

services:
    supportpal:
        environment:
            CRON_ENABLED: 0

Rebuild the container:

docker compose down && docker compose up -d

Using the migration script

In the same directory as your docker-compose.yml file, create a migration_script directory.
Download and unzip the migration script in the migration_script directory.

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


version: '3.8'

services:
    supportpal:
        environment:
            CRON_ENABLED: 0
            MIGRATOR_MODE: 1
        volumes:
            - ./migration_script:/var/www/migrator
        ports:
            - '8081:8081'

Rebuild the container:

docker compose down && docker compose up -d

The migration script can be accessed on port 8081 at the same hostname as the help desk.

Revert all of the above changes once complete to prevent unauthorised access to the migration script.

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