Updating OTRS on FreeBSD

I updated OTRS from version 3.1 to 3.3 on a FreeBSD machine. You can't upgrade from 3.1 to 3.3 directly, but have to apply the update procedure from 3.2 as well. Prior to updating the production system, I cloned and exported that virtual machine and used that clone to verify that the update procedure will work.

  1. Download the latest 3.2.x release from http://ftp.otrs.org/pub/otrs/ and extract that package (e.g. otrs-3.2.16.tar.bz2)
  2. Shutdown apache and cron
  3. Backup your database and /usr/local/otrs
  4. Uninstall OTRS 3.1 (pkg_delete otrs-3.1.x)
  5. Copy everything from the otrs-3.2.x directory to /usr/local/otrs without overwriting any existing files
  6. Read UPGRADING.md and at least do otrs.SetPermissions.pl, database upgrade, DBUpdate-to.3.2.pl, otrs.RebuildConfig.pl, and otrs.DeleteCache.pl
  7. Remove everything from /usr/local/otrs that was copied to it at step #5: 
    cd otrs-3.2.x && find . | while read f; do
  cmp -s "$f" "/usr/local/otrs/$f" && rm "/usr/local/otrs/$f"
done
  8. Install otrs-3.3.x from the ports directory: 
    make -C /usr/ports/www/otrs install clean
  9. Same as step #6, but for OTRS 3.3
  10. Rename every file in /usr/local/otrs/var/cron to *.dist since your old cron files have been overwritten by the ports install
  11. From your backup (step #3), restore all files not named *.dist to /usr/local/otrs/var/cron
  12. Copy /usr/local/otrs/var/cron/generate_dashboard_stats.dist to /usr/local/otrs/var/cron/generate_dashboard_stats
  13. Start apache and cron
  14. /usr/local/otrs/bin/Cron.sh restart otrs
  15. Log in to OTRS as an admin
  16. If you installed the iPhoneHandle package, uninstall and reinstall it (Admin -> Package Manage) as updating didn't work for me
  17. If you installed the MasterSlave package, uninstall it and install the new OTRSMasterSlave package
  18. If you installed any self-written modules that deal with DynamicFields (e.g. that pull stuff over from your ERP system), you have to change these modules since the DynamicFields are no longer indexed by their values (what was a dumb idea anyway imho), but their keys (as as hash-like structure should be)
  19. If you added custom links to the toolbar, keep in mind that you now have to provide an icon (Frontend::ToolBarModule -> YourLink -> Icon)
  20. You're done.