Upgrade Guide

Overview

The Mambo Gamification Platform is always evolving to better suit your needs and to fix any bugs which may have slipped through our battery of automated tests.

Testing Process

Prior to upgrading you must create a copy of your production environment with at least one Mambo application server and one database server. This copy must be used to test the upgrade process and more specifically to test whether the integrations built are still functioning correctly.

With major upgrades that could cause disruptions we will provide migration paths which show you how to move from the current integration code to the updated version. However, smaller releases may have simple changes or new defaults which could impact the integrations depending on how they are built.

In order to test the integrations you can either: 1) create a test / copy environment for the product you integrated with and point it to the new updated test servers (recommended option!), or; 2) point the live production system to the test environment. Option (2) should only be performed when there are NO users in the system, or by taking an instance of the production system, taking it off the primary network and upgrading only that version (effectively creating a sandbox / test environment from the production environment).

Please perform the Testing Process step on every upgrade to ensure there are no problems with your integrations and upgrades.

Update Process

In order to update the Mambo Gamification Platform follow these steps:

1. Access the servers running the platform
2. Stop Tomcat from running (example: sudo /etc/init.d/tomcat7 stop)
3. Make a copy of your mambo.properties file (see the Installation Guide) to have the current properties at hand
4. Repeat the Deploying the WAR File section of the Installation Guide with the new Release WAR file
5. Use the mambo.properties you saved to help fill in the new mambo.properties file. Do not copy and paste. Check if there are new fields to fill in before copying and pasting the old file over the new one.
6. Start Tomcat (example: sudo /etc/init.d/tomcat7 start)
7. Follow the upgrade process using the log file (example: sudo tail -f /var/log/mambo/mambo.log)

Troubleshooting

Upgrade Process Lock

When an upgrade doesn't run smoothly and you need to retry, you may face the following error:

[2020-07-07 07:42:47,786] INFO  [Mongobee dao] Mongobee did not acquire process lock. Throwing exception.

Or in newer versions of Mambo:

[2020-07-07 07:42:47,786] INFO  [com.github.mongobee.dao.ChangeEntryDao] Upgrade did not acquire process lock. Another upgrade process is already running or an error occurred during a previous upgrade. In the case of an error, please remove the lock document from the database.

This means that the upgrade failed and that the lock was left in the database.

In order to resolve this, we need to log into our MongoDB shell and type the following commands:

> use mambo
> db.engine.upgradedb.lock.remove({})

Once that's done you will need to restart Tomcat.

Deserializing Session

When an upgrade results in changes to the session and one is created before the upgrade completes, it may result in the following error in the logs:

org.springframework.core.serializer.support.SerializationFailedException

With the following prefix near the top of the stack trace:

org.springframework.session.*

In case this happens, you can clear the sessions via the database by running the following command:

> use mambo
> db.engine.sessions.remove({})