Sysadmin Guide

Upgrade from a legacy version


Upgrade from v4 builds <= 443

If your v4 instance is not yet using the last v4 release, v443, then you need to update to v443 first.

  1. Download Deskpro 443 from https://www.deskpro.com/deskpro.443.zip

  2. Make a backup of all the current files in the directory where you installed DeskPRO before you install updates in case you need to revert back.

  3. Move the existing data/ directory from within the Deskpro directory to a safe place.

  4. Copy your existing config.php to a safe place.

  5. Extract the contents of deskpro.zip you downloaded in step 1, overwriting all existing files.

  6. From inside the Deskpro install directory, run the command-line upgrade tool:

php cmd.php dp:upgrade

The upgrade tool will ask if you want to produce a database backup before applying updates. We highly recommend you answer ‘yes’, in case you need to revert the upgrade.

  1. The data/ directory created in the install process may contain important log information, so take a copy of it.

  2. Move the original data/ directory from step 3 back into the Deskpro install directory.

  3. Move the original config.php file from step 4 back into the Deskpro install directory.

Upgrade from v4 (exactly v443)

Note: If your v4 instance is not yet on v443, please update to v443 first as described above.

There are different server requirements between v4 and the latest version of Deskpro. Therefore the best way to upgrade is actually to configure a brand new server and migrate your existing data to the new server.

1. First, ensure your current helpdesk is using build #443 as described above.

2. Install a brand new version of Deskpro. Refer to any of the guides in this manual as listed on the left.

3. Finally, follow the guide Migration Overview to move your existing data into place on the new server.

4. If you have a data/encryption-key.bin file, copy it to the config/ directory.

Upgrade from v3 (circa 2011)

If you have a Deskpro installation from v3 or earlier, you will need to follow a special process to upgrade to a modern (v4) Deskpro version.

The process of upgrading from v1, v2 or v3 to Deskpro v4 is done using a completely automated tool. The process is different from a normal v3 upgrade.

Warning

Be sure to download the special v4 version. You must use that specific version of Deskpro to run the import process.

The upgrade process installs Deskpro v4 into a new database and directory, leaving your old v3 DeskPRO installation intact.

The v4 upgrade process runs on v3 databases of at least version 3.3 (from 2008-09-18). If you are using v1 or v2, or an older version of v3, then the upgrade tool will automatically upgrade your helpdesk to v3.3 before proceeding with the v4 upgrade. If you are already using v3.3 or newer, then your old v3 database is only used as a read-only database and the v4 upgrade will not write any changes to it.

Preparing to upgrade

Deskpro v4 has different server requirements. Specifically:

  • The minimum PHP version is now v5.3.9 (up from v5.0).
  • The minimum MySQL version is now 5.0 (up from 4.1).
  • GD (or imagick) is now required.
  • OpenSSL is now required.
  • iconv is now required.

Deskpro will automatically check all of the server requirements when you attempt to upgrade.

Switch email piping to POP accounts

If you are currently usng the piping mechanism in Deskpro v3, convert your email accounts into POP3 accounts before upgrading.

Improving import performance

You can enable a fast_import option under Deskpro Import Settings in your config.php to skip processing some unnecessary data (the KB search log, tech timelog, and data saving of unsupported tables).

$DP_CONFIG['import'] = array(
   //...
   'fast_import' => true,
   //...
);

You can also improve performance by moving file attachments from the v3 database to the filesystem. This will reduce the number of queries needed to copy files from the database.

You can move v3 files to the filesystem from Admin > Settings > File Storage or in config.php add:

store_attachment_files => true

If you have a very large number of tickets in your helpdesk and find the import is still running too slowly, see the Upgrading large v3 databases section below for more ways to improve performance.

Running the upgrade

If you want to test that the upgrade process works, you can run the upgrade and leave your v3 helpdesk running as it is. Once you are ready to move for good, you should run the upgrade again.

When you are ready to switch permanently, you should disable the v3 helpdesk (from Admin > Settings > Modify Settings) and disable the v3 cron jobs.

  1. Download the special version of v4 Deskpro including the importer. You must use this version.
  2. Extract the files and upload them to a new, empty directory on your webserver (not your existing v3 directory). Make sure the /data directory inside is writable by the webserver.
  3. Create a new empty MySQL database for v4.
  4. In the new v4 directory, copy /config.new.php to /config.php.
  5. Edit /config.php with a text editor and insert your new database details near the top.
  6. Further down the file, find the section titled “Deskpro Import”, enter your old database details.

Now proceed to the section below which matches your platform:

On Linux/BSD:

  1. Use SSH to connect to your server, or if you have a local install, open a new terminal window.

  2. Change to the Deskpro v4 directory. For example: cd /var/www/.

  3. Execute the command: php import.php (you may need to specify the path to your PHP binary.)

  4. Follow the on-screen instructions.

  5. Log into Deskpro v4 using your browser.

  6. Schedule a cron task to run /cron.php every minute.

    You would typically do this by editing your crontab file to add a line similar to this:* * * * * /usr/bin/php /var/www/deskpro/cron.php

  7. Back up the old Deskpro v3 files and then delete them from the v3 install directory.

  8. Move the new Deskpro v4 files to the v3 install directory.

  9. Enable your imported email accounts in Admin > Tickets > Email Accounts.

  10. You are now on an outdated version of v4. Update to the latest version using the Command-line updater or following the From v4

On Windows:

  1. Run cmd.exe.
  2. Go to the Deskpro v4 directory. For example: cd "C:\inetpub\deskpro".
  3. Execute the command: "C:\wamp\bin\php\php5.3.0\php.exe" import.php (using the location where PHP.exe is installed on your server).
  4. Follow the on-screen instructions.
  5. Log into Deskpro v4 using your browser.
  6. Run /schedule.bat from the new install folder to create a scheduled task that runs cron.php every minute (or use Task Scheduler to do it manually).
  7. Back up the old Deskpro v3 files and then delete them from the v3 install directory.
  8. Move the new Deskpro v4 files to the v3 install directory.
  9. Enable your imported email accounts in Admin > Tickets > Email Accounts.
  10. You are now on an outdated version of v4. Update to the latest version using the Command-line updater or following the From v4

Upgrading large v3 databases

Upgrading to v4 involves copying all of your data from a v3 database into a fresh v4 database. This is a fairly intensive task, and if you have a very large database there will be millions of queries being executed and lots of data being moved around.

Run the upgrade tool on a separate server

Since the process involves so many queries (both read and write queries), you should not run the upgrade tool on a live server. Ideally you want a spare server that is doing nothing but running the upgrade tool. This way, the upgrader isn’t competing for resources with other services you might be running.

Store attachments in the filesystem

To avoid large blobs being sent to and from the database, you should make sure you have the filesystem storage mechanism enabled for your attachments. In your config.php file make sure under the “import” section you have the following option enabled:

store_attachment_files => true

Make sure your server has lots of memory

The best way to improve performance for large databases is to ensure MySQL has lots of memory at its disposal.

Use MySQL with a ramdisk for best performance; alternatively, use MySQL with an SSD.

Tune MySQL’s INNODB Settings

MySQL’s default configuration may not be suitable for your server. There is no perfect combination of settings that will work for everyone; it will take some experimentation. There are many guides available which explain MySQL performance tuning. One useful resource is the MySQL Performance Blog.

Further reading: InnoDB Performance Optimization Basics on the MySQL Performance Blog.

Importing very large v3 databases with minimal downtime

When running the v3 to v4 importer, your helpdesk has to be disabled for the duration of the import to prevent data corruption (e.g. a half-inserted ticket).

If your helpdesk has a very large database, the import process may take a long time and the downtime may be unacceptable. To avoid this, you can use a two- stage import to reduce downtime to a matter of minutes rather than hours.

You must take a snapshot of the live database that the importer will run on. See the MySQL manualfor one possible method of duplicating your database.

Stage 1: Running the import

The first stage is running the import from start to finish. Refer to our “Upgrading to Deskpro v4” guide. The instructions are exactly the same, except make sure you run the import against your duplicated database you just made.

Stage 2: Running the rerun tool

Now that you have a completed import, you need to update the database with changes made on your live helpdesk since the import first ran. For example, your live helpdesk will have new tickets and new replies and the v4 database will need to be updated with that new data.

Disable your v3 helpdesk. Now that we are preparing to go live with v4, we need to make sure the v3 helpdesk is no longer processing any new tickets. Edit your v4 /config.php file and change the database information under “Deskpro Import Settings” to point to your live v3 database. Your live database will have the most up to date data and this is the data we need to process now. From the command-line, run the import tool the rerun flag:

/usr/bin/php import.php --rerun

Since the rerun is only processing new data, the dataset is much smaller and will complete very quickly. As soon as the rerun finishes, you can proceed to put the v4 helpdesk “live”.

Upgrade again to the latest version

Once you are upgraded to v4, you need to upgrade again to get to the latest version of Deskpro. Follow the guide at the top fo this page, "Upgrade from v4".

Comments (0)

Add a comment

Add a comment

You need to log in before you can submit a comment.

Need a password reminder?