Upgrade guide

Overview

The Mambo Platform continually evolves to better meet your requirements and resolve any defects that may have eluded our comprehensive automated test suite. This guide will walk you through the process of safely upgrading your Mambo installation.

Prerequisites

Before beginning the upgrade process, ensure you have:

• Access credentials for all servers running the platform
• Administrator access to your MongoDB database
• A copy of your current mambo.properties file
• The new Mambo release WAR file
• Sufficient downtime allocated for the upgrade process

Testing procedure

Prior to upgrading your production environment, you must create and test on a staging environment:

1. Create a complete copy of your production environment, including at least:

   • One Mambo application server
   • One database server

2. Use this staging environment to:

   • Test the upgrade process itself
   • Verify all integrations function correctly after the upgrade

3. Choose one of these integration testing approaches:

   Approach	Description	Recommendation
   Recommended	Create a test/copy environment for your integrated product and point it to the upgraded test servers	Preferred for all situations
   Alternative	Point your live production system to the test environment	Only use when there are NO users in the system OR with an isolated copy of production

warning

Always perform thorough testing on every upgrade to ensure your integrations continue to function properly. Major upgrades may include migration paths with specific instructions for updating integration code.

Update process

Follow these steps to update your Mambo Gamification Platform:

1. Access all servers running the platform

2. Stop Tomcat service

   Bash

   sudo /etc/init.d/tomcat7 stop

3. Backup your current mambo.properties file

   Bash

   sudo cp /path/to/mambo.properties /path/to/mambo.properties.backup

4. Deploy the new WAR file following the procedure in the Installation Guide

5. Configure your new mambo.properties file:

   • Refer to your backup for existing values
   • Important: Do not simply copy and paste the old file
   • Check for new configuration fields and requirements

6. Start Tomcat service

   Bash

   sudo /etc/init.d/tomcat7 start

7. Monitor the upgrade process in the log file

   Bash

   sudo tail -f /var/log/mambo/mambo.log

Post-upgrade verification

After completing the upgrade:

1. Verify the application starts correctly
2. Check that all integrations are functioning
3. Test core platform features like points awarding and redemption
4. Monitor error logs for at least 24 hours

Troubleshooting

Upgrade process lock

If your upgrade fails and you need to retry, you may encounter this error:

Log

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

Or in newer versions:

Log

[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 indicates the upgrade failed and left a lock in the database. To resolve:

1. Log into your MongoDB shell:

MongoDB Shell

use mambo
db.engine.upgradedb.lock.deleteMany({})

2. Restart Tomcat after removing the lock

Deserializing session errors

If the upgrade changes session structures and sessions were created before completion, you might see:

Log

org.springframework.core.serializer.support.SerializationFailedException

With this prefix near the top of the stack trace:

Log

org.springframework.session.*

To resolve, clear the sessions via the database:

MongoDB Shell

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

---

Related topics

• Installation guide
• Release notes
• Backup and restore