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
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/master/templates/docker-monolithic/setup.sh)
Windows
winpty bash <(curl -LsS https://raw.githubusercontent.com/supportpal/helpdesk-install/master/templates/docker-monolithic/setup.sh)
-
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
.
-
Start the containers:
docker compose up -d
-
Install SupportPal:
docker compose exec supportpal /bin/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 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.
-
Create or update
docker-compose.override.yml
, for example:version: '3.8' services: supportpal: hostname: 'supportpal.example.com' ports: - '443:443'
-
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
-
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):
- Create a directory named
customization
in the same directory as yourdocker-compose.yml
file -
Create or update
docker-compose.override.yml
, for example:version: '3.8' services: supportpal: volumes: - ./customization:/customization
-
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 - Add your extensions to the directory
-
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
- 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'
-
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.