Deploy SupportPal on Docker

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

Contents

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.


  1. Use the setup script to quickly get started with your deployment:

    Linux / MacOS

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

    Windows

    
    winpty bash <(curl -LsS https://raw.githubusercontent.com/supportpal/helpdesk-install/5.x/templates/docker-monolithic/setup.sh)
    
  2. Review the generated .env file:
    • It may be necessary to update the DOMAIN_NAME environment variable. This is 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.
  3. Start the containers:
    docker compose up -d
  4. Install SupportPal:
    docker compose exec supportpal bash -c "bash /init/init-helpdesk.sh"

Customisation

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.

  1. Create or update docker-compose.override.yml, for example:
    
    version: '3.8'
    
    services:
        supportpal:
            ports:
                - '443:443'
            environment:
                HTTPS_ENABLED: 1
                EMAIL_ADDRESS: "[email protected]"
                DOMAIN_NAMES: "help.domain.com, support.domain.com"
    
  2. 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).
  3. Replace the DOMAIN_NAMES environment variable with comma delimited domain names. Each domain must have correctly configured DNS.
  4. 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.

  1. Create a caddy directory within the same path as your docker-compose.yml file.
  2. 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.
    
    {
      email [email protected]
    }
    
    support.brand1.com {
      reverse_proxy 127.0.0.1:8080
    }
    
    help.brand1.com {
      tls /etc/ssl/star.brand1.com.crt /etc/ssl/star.brand1.com.key
      reverse_proxy 127.0.0.1:8080
    }
    
    help.brand2.com {
      tls /etc/ssl/star.brand2.com.crt /etc/ssl/star.brand2.com.key
      reverse_proxy 127.0.0.1:8080
    }
    
    
  3. Create or update docker-compose.override.yml using the example below:
    
    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
    
    
  4. Rebuild the container:
    docker compose down && docker compose up -d

Add a private certificate authority

  1. Create an ssl directory within the same path as your docker-compose.yml file, and add your certificate authority file to it.
  2. 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.
  3. Rebuild the container:
    docker compose down && docker compose up -d

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. Browse to directory where the docker-compose.yml file is
  2. Add a customization volume mount to docker-compose.override.yml, for example:
    
    version: '3.8'
    
    services:
        supportpal:
            volumes:
                - ./customization:/customization
    
  3. 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
  4. 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
            
  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. In the same directory as your docker-compose.yml file, create a migration_script directory.
  2. Download and unzip the migration script in the migration_script directory.
  3. 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'
    
  4. 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.


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