Deploy SupportPal on Docker (High Availability)
Deploy SupportPal using a multi-node configuration with Docker Compose on GNU/Linux. Experience with Docker is recommended.
Prerequisites
Ensure your system meets our recommended system requirements. Operating system and software requirements are already satisfied by our Docker containers.
Additional software is required to deploy SupportPal on Docker:
- Install Docker.
- Install the latest version of Docker Compose (1.24 or greater).
- Install Git.
-
Install GNU Make:
CentOS / RHEL
sudo yum install make -y
Ubuntu / Debian
sudo apt install make -y
- Install Docker Desktop.
- Install Git.
- Install Homebrew.
-
Install GNU Make through homebrew:
brew install make
- Install Docker Desktop.
- Install Git Bash.
- Install Chocolatey.
-
Install GNU Make through Chocolatey:
choco install make
Installation & Configuration
Install SupportPal
To start the installation, run the following:
Linux / MacOS
bash <(curl -LsS https://raw.githubusercontent.com/supportpal/helpdesk-install/master/templates/docker-compose/setup.sh)
Windows
winpty bash <(curl -LsS https://raw.githubusercontent.com/supportpal/helpdesk-install/master/templates/docker-compose/setup.sh)
Next Steps
Congratulations, you've successfully installed SupportPal!
You can control the state of the containers via the make
command:
make help
We now recommend that you learn how to administer your installation.
Customisation
In order to add customizations to the environment, Update the Makefile
file, replacing the
COMPOSE_FILES
variable:
COMPOSE_FILES=-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml
All updates should be done in your docker-compose.custom.yml
file, refer to the
compose file specifications or instructions later
in the setup.
Configuring HTTPS
By default, the software will run on HTTP using port 80, however we recommend using HTTPS for added security. To allow HTTPS, we provide an integration with LetsEncrypt, start the process with the following steps:
-
Change the current working directory to the
docker-compose
directory, for example:cd helpdesk-install/templates/docker-compose
-
Stop the containers if they are currently running:
make stop
-
Update the
Makefile
file, by appending to the following string toCOMPOSE_FILES
variable, if the variable does not exist, copy its contents from Makefile.dist:-f docker-compose.https.yml
-
Add your help desk domain name to the
.env.custom
file. If you intend to use multiple domains / brands with your helpdesk, only specify one - it does not matter which one you choose.DOMAIN_NAME=example.com
You may now either set up a self-signed SSL certificate (if your domain is not available to the public), or a full LetsEncrypt SSL certificate for your domain.
Self-Signed SSL Certificate
Execute the script, replacing the top level domain names with your own. You can list as many domain names as you need:
./../../configs/letsencrypt/create-self-signed.sh -- example.com www.example.com
LetsEncrypt SSL Certificate
In order for this step to succeed, the domain name must be reachable for verification over port 80.
Execute the script, replacing the domain names and email address. You can list as many domain names as you need.
At least one of the domain names needs to be the DOMAIN_NAME
specified in the .env.custom
file.
./../../configs/letsencrypt/init-letsencrypt.sh --email user@company.com -- example.com www.example.com
Restart the containers for your changes to take effect:
make restart
Configuring nginx
You can extend our default nginx configuration by making changes to
templates/docker-compose/gateway/custom.conf
within the helpdesk-install
repository.
See https://nginx.org/en/docs/ for assistance with nginx config directives.
Restart the containers for your changes to take effect:
make restart
Configuring PHP
You can extend our default PHP configuration by copying files into the containers.
-
Add PHP ini configuration files to the
templates/docker-compose/php/
directory. The configuration inside these files will be merged with the default configuration, overriding them on duplication. See https://www.php.net/manual/en/configuration.file.php for assistance with PHP directives. -
Restart the containers for your changes to take effect:
make restart
Extending SupportPal
It is easy to extend your SupportPal installation. Simply add your files to the relevant directory in the
helpdesk-install
repository:
Extension | helpdesk-install Directory |
---|---|
Creating plugins | templates/docker-compose/customization/plugins |
Creating reports | templates/docker-compose/customization/reports |
Creating translations | templates/docker-compose/customization/languages |
Creating themes | templates/docker-compose/customization/templates |
The changes should be immediately visible in your SupportPal installation without needing to restart the containers.
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:/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.
Using the migration script
To get started using the migration script follow the below steps:
- Download and extract migration script
- Ensure the SupportPal docker containers are already running
-
In the directory where the migration script was extracted run:
docker compose up -d
-
Access the migration script via
http
on port8081
at the same hostname / IP address as the help desk. When finished with the migration script, rundocker compose down -v
to remove the container. -
Configure Step 1
-
Ensure the
storage/
directory is writable by thewww-data
user:docker compose exec migrations chown -R 33:33 storage/
-
Set the database details:
- Hostname:
db
- Name:
supportpal
- Username: can be found in
templates/docker-compose/secrets/db_user.txt
- Password: can be found in
templates/docker-compose/secrets/db_password.txt
- Hostname:
-
Set the application details:
- Storage Path:
/supportpal/storage
- Application Key: can be found in
config/production/app.php
within thesupportpal
container
- Storage Path:
-
Ensure the
Uninstall
This sequence of commands will permanently erase your installation, including the database data.
To completely remove your help desk installation, follow the steps below:
-
Change the current working directory to the
docker-compose
directory, for example:cd helpdesk-install/templates/docker-compose
- Take a full backup.
-
Run the
uninstall
command:Linux
sudo make uninstall
MacOS / Windows
make uninstall