Daniel Lange's blog

1. Create a diff between the current release and the target release

For Limesurvey it is essential that you keep a version of the currently running release before you have applied your templates and other customizations. If you missed that step or are doing the upgrade like this the first time, the Limesurvey github releases page is a useful source but not necessarily complete (see update from 28.06.2020 below for details).

In this example we are upgrading from release 4.2.6 to 4.3.0. So we skipped 4.2.7.

I assume you're working in a /root/install directory for this step. You should definitely work outside the webroot.

You should have a 4.2.6 directory containing the unpacked Limesurvey 4.2.6 zip or tarball.

Download the 4.3.0 release, mkdir 4.3.0 and (for example) unzip -d 4.3.0/ limesurvey4.3.0+200616.zip.

Create the diff with # diff -N -u -r 4.2.6/ 4.3.0/ > mydiff

-N allows to create new files as a diff from /dev/zero and to remove files similarly
-u creates a "unified diff", so a diff with some context that will allow to apply patches even to files that you changed locally
-r makes the diff recurse through subdirectories

2. Inspect the diff

As a first step look at the size of the diff:

That looks reasonable, it's a web app .

If you get 8.5m lines, you have managed to get one directory wrong and the whole app is removed and re-created.

Now read through the diff and inspect for changes that may collide with your local modifications or that look fishy.

If you see a line with "Binary files ... differ", your diff will not contain all changes. This typically happens with the binary translation files (locale/<lang>/<lang/.mo). The -a option of diff doesn't help much, so it is better to note the files and updates these with cp or rsync. You can just overwrite the whole locale/ directory hiearchy in Step #4 below if you do not translate limesurvey yourself beyond what is available from upstream. There is (currently) nothing in locale/ that is not .mo files and empty index.html files.

So grep "^Binary files .* differ$" mydiff will tell you whether the specific update of limesurvey has such binary (translation) updates, or may be contain a changed image file.

A list of the files that got created or removed may be useful to inspect at minimum:

3. Make backups of the application webroot

4. Patch a copy of the application in-place

The --verbose is important so you see deleted files. -N forces a forward-patch as everything else would not make sense. -p 2 strips two directories off the beginning of the paths in the diff. That makes sense as 4.3.0/limesurvey is not needed when you have limesurvey_new as your working directory.

The output will look like this:

If you see any hunks rejected (.rej files created), find the reason and fix it before continuing.

You can use find /var/www/limesurvey_new -name "*.rej" to see if you have any reject files. You typically shouldn't but double checking is never bad, is it?

If you have binary files changed from Step #2 above, copy them over manually or (for the typical case of translation updates) just copy over the whole locale/ subdirectoy hierarchy. Something like rsync -a -v --delete-after /root/install/4.3.0/limesurvey/locale/ /var/www/limesurvey_new/locale/ will suffice if you are not changing translation strings locally.

5. (optional) stop the web server

If you run a stupid webserver, a complex setup, external opcode caches or just have high load (survey writes likely), you may want to stop the httpd now.

For "normal loads" (a few hundred answers to surveys per day) and when using Apache you can typically just move the webroot.

In any case even with stopping the httpd, the downtime should be very short.

6. Make a backup of the production database

Make a backup of the production database. In our case this is as simple as calling backup-mysql.

If you don't have a specific way to backup your database

mysqldump --quick --extended-insert --skip-comments limesurvey | gzip -9 > /root/install/limesurvey_database_${date "+%y%m%d"}.sql.gz

should be a good start.

7. Move the patched application to the production webroot

mv limesurvey limesurvey_old && mv limesurvey_new limesurvey

This will overwrite the old webroot and is two fast atomic operation on sane filesystems (e.g. ext4), so this is rather safe™ to do.

You can as well patch the production webroot in place. Esp. if you have stopped the httpd. You should have made a backup in step 3. You did, didn't you?

Note: If you want a fully atomic replacement of the application webroot, you have to use symlinks for the old and new tree and use mv -T, see Richard Crowley's Things UNIX can do atomically for a discussion.

8. (if 5) Start the webserver

If you stopped the webserver, start it again.

9. Upgrade the database (if needed)

Depending on whether the upgrade needed database schema upgrades, you want to inspect the Admin UI at:

https://limesurvey.example.org/admin

The 4.2.6 -> 4.3.0 upgrade does not need any database changes.

10. Check the application

As a good last step - as always - take a critical look at the application whether everything runs as it should. Are the images loading, can you do a test survey?

If so, all fine and until the next upgrade.

Updates

25.06.2020: For the 4.3.0 to 4.3.1 update the diff -u is just 995 lines with 358 of these not being context lines only. And still most are just translation updates. The update fixes two security bugs and is essential if you run MySQL 8.0 or later. Because from that version MySQL considers "groups" a reserved name and Limesurvey uses that as a table name.

The diff is very easy to review and safe to patch in-place. The update took less than 5 minutes.

28.06.2020: The Limesurvey releases page may have releases that Github has not. E.g. the current - as of 16 June 2020 - 4.3.1 release is missing in Github still two weeks later as it has been marked in the release notes and version.php but not been tagged appropriately in the repository (yet?) cf. commit e55a12f. It is available from the Limesurvey releases page (and from the downloads page until it gets superceeded by the next 4.3.x release).

05.07.2020: 4.3.1 to 4.3.2 is just 296 lines of unified diff and seven updated .mo files. Again very little work.

13.07.2020: We skipped 4.3.3, so 4.3.2 to 4.3.4 is 84402 lines of diff (and updated translations) but we had to get the release off the github commit (essentially wget https://github.com/LimeSurvey/LimeSurvey/archive/75f0c373084d2cf929c64bce74c8e26f5bac7ce9.zip) as the release 404's on the limesurvey download page and it seems the release tags on github are always only made available for the previous version when a new one is released.

This time we had a database upgrade as well and that worked fine: