# Deploy SupportPal on Docker Deploy SupportPal using a monolithic image which runs all the necessary services in a single container. ## Prerequisites - [Docker Engine](https://docs.docker.com/engine/install/) - [Docker Compose](https://docs.docker.com/compose/install/#install-compose) --- ## Installation Our docker compose deployment makes use of an example [ `docker-compose.yml` file](https://github.com/supportpal/helpdesk-install/blob/master/templates/docker-monolithic/docker-compose.yml). 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: The script must be run in a bash compatible terminal. If you're on Windows, use [Git Bash](https://git-scm.com/downloads). ``` bash <(curl -LsS https://raw.githubusercontent.com/supportpal/helpdesk-install/6.x/templates/docker-monolithic/setup.sh) ``` 2. Browse to the created installation directory, noted in the `setup.sh` output. For example: ``` cd supportpal_1745496963_5176 ``` 3. Review the generated `.env` file: - It may be necessary to update the `MAIL_DOMAIN_NAME` environment variable. This specifies the fully-qualified domain name (FQDN) of the built-in mail server; it should have an A and PTR DNS record configured. - See [customisation](#Customisation) for additional configuration options such as how to enable `HTTPS`. 4. Start the containers: ``` docker compose up -d ``` 5. 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. 1. Expose port `443` in `docker-compose.override.yml`, for example: ``` services: supportpal: ports: - '443:443' ``` 2. Add or update the following environment variables in your `.env` file: ``` HTTPS_ENABLED=1 CADDY_DOMAIN_NAMES=help.domain.com, my.domain.com CADDY_EMAIL_ADDRESS=my@email.com ``` - The `CADDY_EMAIL_ADDRESS` environment variable must be a valid e-mail address, and is used to manage your SSL certificates at the ACME service (LetsEncrypt / ZeroSSL). - The `CADDY_DOMAIN_NAMES` environment variable specifies a comma delimited list of domain names to request SSL certificates for. Each domain must have correctly configured DNS. 3. Recreate the container. ``` 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. 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 } ``` 3. Create an `ssl/` directory within the same path as your `docker-compose.yml` files, and add your certificate files to that directory. 4. Create or update `docker-compose.override.yml` using the example below. Change the filenames for the SSL certificates as appropriate. ``` services: supportpal: ports: - '443:443' 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 ``` 5. Add the following environment variable to your `.env` file: ``` CADDY_CONFIG_PATH=/etc/supportpal/Caddyfile ``` 6. Recreate the container: ``` 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: ``` services: supportpal: volumes: - ./ssl/foo.crt:/usr/local/share/ca-certificates/foo.crt ``` Note that all certificates must use the `.crt` extension. 3. Recreate the container: ``` 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: ``` services: supportpal: volumes: - ./php/pool.d/:/etc/supportpal/php/pool.d/ ``` 3. Recreate the container: ``` 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 for assistance with PHP directives. 3. Create or update `docker-compose.override.yml`, for example: ``` 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. Recreate the container: ``` docker compose up -d ``` --- ### Customising MySQL You can extend our default MySQL configuration by copying files into the containers. 1. Create `mysql/99_custom.cnf` in the same directory as your `docker-compose.yml` file 2. Add your MySQL configuration to the file. See for assistance with MySQL server options. For example: ``` [mysqld] max_connections=1000 ``` 3. Create or update `docker-compose.override.yml`, for example: ``` 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. 4. Recreate the container: ``` 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: ``` 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](Plugin+Development) customization/plugins [Creating reports](Report+Development) customization/reports [Creating translations](Language+Packs) customization/languages [Creating themes](Templates) 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 -u supportpal -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. Recreate the container: ``` docker compose up -d ``` --- ### Updating SupportPal config files To create [SupportPal config files](Updating+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. Add the following environment variable to your `.env` file: ``` CRON_ENABLED=0 ``` 2. Recreate the container: ``` 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](Migration+Script#download-script) in the `migration_script` directory. 3. Update `docker-compose.override.yml`, for example: ``` services: supportpal: volumes: - ./migration_script:/var/www/migrator ports: - '8081:8081' ``` 4. Add the following environment variables to your `.env` file: ``` CRON_ENABLED=0 MIGRATOR_MODE=1 ``` 5. Recreate the container: ``` 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 ```