Skip to main content

Upgrade to v5

This guide covers the steps required to upgrade your Mango installation from version 4.x to version 5.x. Mango v5 introduces unified versioning, a redesigned UI, PostgreSQL support, gRPC-based publishing, HTTPS by default, and many other improvements. Before upgrading, review the Mango v5 Highlights page to understand the scope of changes.

New License Required

You will need to purchase a new license for Mango v5. You can submit an upgrade request at radixiot.com/upgrade-request-form.

Pre-Upgrade Checklist​

Before attempting the upgrade, complete the following:

  1. Back up your database. Create a full backup of your SQL database and any NoSQL time-series data. Have a tested recovery plan ready in case you need to roll back.
  2. Test in a non-production environment first. Never upgrade a production instance without validating the process in a development or staging environment.
  3. Verify your data directory. If you have not created a separate data directory, now is the time to do so. If you have been upgrading Mango since version 3.x, your data directory may still reside inside the installation directory. Refer to the Mango v4 upgrade documentation for instructions on creating an external data directory.
  4. Review module compatibility. Check that all third-party or custom modules you rely on have been updated for Mango 5.x compatibility.
  5. Read the release notes. Review the v5 Release Notes for the core and any modules you use to understand what has changed.

Java / JDK Requirements​

Mango v5 requires Java 17 as the minimum supported version. You must install OpenJDK 17 (or later) prior to upgrading and ensure your JAVA_HOME environment variable points to the correct installation.

Radix IoT recommends the Azul Zulu builds of OpenJDK, however any compliant OpenJDK vendor will work.

For Mango 5.4 and later, Java 21 is recommended for best performance and compatibility, though Java 17 remains the minimum requirement. Mango 5.6 is built and tested with Java 25, but Java 17 continues to be supported at runtime.

Upgrade Methods​

Method 1: Upgrade Via the UI​

This is the simplest method for instances with internet access:

  1. Log in to your Mango instance as a superadmin.
  2. Navigate to Administration > Modules.
  3. Press the Check for Upgrade button.
  4. Follow the on-screen prompts to download and install the v5 upgrade.
  5. Mango will restart automatically after the upgrade completes.

Method 2: Upgrade Via the Store (Offline)​

For instances without direct internet access or when you need more control over the process:

  1. Download the latest version of Mango from the Radix IoT store. Do not unzip the file.
  2. Place the zipped Mango file in the root directory of your Mango installation.
  3. If you have a pre-grant license file, place it in the root directory as well.
  4. Restart Mango. The platform will detect the upgrade package and apply it during startup.

Post-Upgrade Steps​

Clear Browser Cache​

When you first upgrade to Mango 5.0, users may see a cached version of the older UI in their browser. To resolve this:

  • If upgrading from Mango 4.x, a prompt to update should appear in the UI automatically.
  • Users should close all browser tabs that have Mango open and reopen them.
  • Alternatively, hold Shift and press Refresh in Chrome (note: this may not work if multiple Mango tabs are open).
  • As a last resort, completely clear your browser's cache.

Database Conversion (Optional)​

If you want to take advantage of the new PostgreSQL support, you should first complete the upgrade to Mango 5.0 on your existing database, then perform the database conversion. See Database Conversions for migration instructions.

Verify HTTPS Configuration​

Mango 5.0 enables HTTPS by default on port 8443. If you were previously running HTTP only, review the ssl.* settings in your mango.properties file. If you do not have a signed TLS certificate, Mango will generate a self-signed certificate automatically, but you should plan to configure a certificate from a trusted Certificate Authority for production use.

Unified Versioning​

Beginning with version 5, Radix IoT introduced unified versioning. All components (core and modules) are released together as a single version. When any component receives an update, the entire platform is released as the next version number. For example, if the Watchlist module receives a minor update, a new bundle is released containing all modules and the core as version 5.0.1.

This approach simplifies dependency management and ensures that all components in your installation are always compatible with each other. When upgrading between patch versions (e.g., 5.5.6 to 5.5.7), simply download and apply the new bundle.

Troubleshooting​

SymptomResolution
Old UI still appears after upgradeClear browser cache completely. Close all Mango tabs and reopen.
Java version errors on startupVerify JAVA_HOME points to Java 17 or later. Run java -version to confirm.
Module compatibility errorsCheck that all modules are at the same version as the core. Remove any modules that have not been updated for v5.
License errorsEnsure you have purchased and installed a Mango v5 license. Contact Radix IoT support if needed.
Database connection failures after conversionVerify your db.type and connection string settings in mango.properties. Ensure the target database server is running and accessible.