You're browsing the documentation for an old version of SupportPal. Consider upgrading to the [latest version](https://docs.supportpal.com/current/Deploy+On+Docker). 

# 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)](Deploy+On+Docker+HA).

## 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). 
    
    **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)
    
    ```
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](#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

  **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. Create or update `docker-compose.override.yml`, for example: ```
    
    version: '3.8'
    
    services:
        supportpal:
            ports:
                - '443:443'
            environment:
                HTTPS_ENABLED: 1
                EMAIL_ADDRESS: "my@email.com"
                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 my@email.address
    }
    
    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
    ```

---

### 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](Plugin+Development) customization/plugins   [Creating reports](Custom+Reports) 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 -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](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. 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](Migration+Script#download-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.

  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

```

### 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](https://docs.docker.com/config/containers/logging/journald/) as the logging driver. See the `docker compose` [logging directive](https://docs.docker.com/compose/compose-file/compose-file-v3/#logging) for more help.