Migrating to a New Server

If you need to move your SupportPal installation to a new server, we recommend to follow the below guide.

Prerequisites

• A development license to temporarily use on the new server.
• Root MySQL access on the new server.
• Running the latest version of SupportPal - prior to migrating, to ensure that the migration is as smooth as possible.

Steps

This guide uses our built-in backup and restore functionality. Larger installation, may find it faster, to use other technologies to migrate their data.

Configure the new server

1. Contact us to obtain a temporary license for your new installation.
2. Install SupportPal using your chosen installation method.

Migrate from the old server to the new server

Perform these steps on your old server:

1. Visit Settings in the operator panel and enable the "Maintenance Mode" option.
2. Disable background services:
   • Cron Job.
   • Email Piping or Remote Email Piping, if used.
3. Staff can still access the operator panel whilst maintenance mode is enabled so we recommend to turn off the web server, or prevent access via some other means. This is to ensure that data does not change after the backup has been generated.
   
   On Docker, this can be achieved by executing the following command:

   docker exec supportpal bash -c "sudo find -L /etc/service -maxdepth 1 -mindepth 1 -type d ! -name 'redis' ! -name '00redis' ! -name 'mysql' ! -name '00mysql' -printf '%f\n' -exec sv stop {} \;"

4. Create a backup of your help desk.
   
   On Docker, please use the --online option. This ensures that background services are not restarted after the back has completed.
5. Copy the backup file to your new server. One way to do this is via the scp Linux command. The below command is an example, placeholders (capitalised), and paths should be replaced for actual usage depending on your scenario:

   scp /var/www/supportpal/storage/app/backups/APP.TAR.GZ [email protected]:/home/user/APP.TAR.GZ

Login to the new server, and follow the below steps:

1. Move the backup file to the storage/app/backups/ directory within your SupportPal installation directory.
   
   On Docker, this can be achieved by executing the below command. Remember to replace APP.TAR.gz with a valid path to your backup:

   docker cp APP.TAR.GZ supportpal:/var/www/supportpal/storage/app/backups/backup.tar.gz

2. Restore your backup file.
   Please choose the restore process which is appropriate for your new installation. For example, you can use Docker if you're restoring into a Docker container.
   It is normal for this process to take a number of hours to run. Depending on the size of your database, it could well be hours or days.
   Whilst not strictly necessary, we recommend to run the restore process as the root MySQL user. If you, or a plugin, have modified the default database in any way then sometimes root access is required to fully import the database backup. It is preferable to use root, to avoid the restore crashing after a number of hours due to a permissions issue.
   
   To update the database credentials in SupportPal:

   1. Backup your existing config/production/database.php file.
   2. Replace the username, and password values in the file with that of your root credentials.
3. If you've migrated from a non-Docker installation to Docker, or are using Meilisearch on your new installation, you will need to populate the search database. This process can take some time and search results may not yield accurate results until it has finished indexing all of your data:

   docker compose exec supportpal bash -c "php artisan models:index"

4. Login to the SupportPal client area and re-issue your license so that it is unlocked.
5. Login to the operator panel.
6. Visit Settings and disable the "Maintenance Mode" option.
7. If your SupportPal URL has changed you will also update your brand URL (Settings > General > Brands > Website (tab) and update the System URL option).
8. Enable the SupportPal cron job (you may need to configure it from scratch on the new server). Verify the tasks are running by visiting Settings -> Core -> Scheduled Tasks and refreshing every few minutes.
9. If you switched the database credentials to use root, you can revert back to the original credentials.
10. Re-enable any e-mail piping configurations on the new server.