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.
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)
-
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
.
-
It may be necessary to update the
-
Start the containers:
docker compose up -d
-
Install SupportPal:
docker compose exec supportpal bash -c "bash /init/init-helpdesk.sh"
Customisation
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: "[email protected]" 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 yourdocker-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.{ 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 }
-
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
-
Rebuild the container:
docker compose down && docker compose up -d
Add a private certificate authority
-
Create an
ssl
directory within the same path as yourdocker-compose.yml
file, and add your certificate authority file to it. -
Create or update
docker-compose.override.yml
using the example below:
Note that all certificates must use theversion: '3.8' services: supportpal: volumes: - ./ssl/foo.crt:/usr/local/share/ca-certificates/foo.crt
.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 yourdocker-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 yourdocker-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:
You can change theversion: '3.8' services: supportpal: volumes: - ./php/conf.d/:/etc/supportpal/php/conf.d/
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 todocker-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 amake:*
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 hostcustomization
directory, and finally the files removed from the container so that they can be mounted via thecustomization
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 amigration_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.
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