Skip to main content

How to Upgrade Mango

Mango automatically checks for new updates daily and notifies you on the Modules page, displaying the number of modules that can be upgraded. New features and bug fixes are released regularly, so it is good practice to check for updates often. An event is also raised when new upgrades are available, which you can configure to send email notifications.

note

It is recommended that you read the release notes for every upgrade before performing it to ensure it will not cause unexpected changes to your Mango configuration. Use caution when installing any new modules -- be sure you understand what they do before installing them.

Step 1: Check for Upgrades​

Navigate to Administration > Modules and click the Check for upgrades button. Mango will contact the store and display a list of available upgrades and new modules.

The Modules page showing available upgrades with version numbers and checkboxes

Step 2: Select and Install​

Select the modules you want to upgrade and click the Upgrade/Install button. Mango will:

  1. Download the selected module packages.
  2. Shut down automatically.
  3. Install the new modules.
  4. Restart with the updated modules.

Offline Upgrade​

If your Mango server does not have internet access, you can perform an offline upgrade:

  1. On a machine with internet access, download the Module manifest file from your Mango Modules page.
  2. Upload the manifest at https://store.mango-os.com/account/manualUpdate to download the offline update package.
  3. Transfer the package to your Mango server.
  4. Use the offline upgrade option on the Modules page to apply the update.

Pre-Upgrade Checklist​

Before performing any upgrade:

  1. Read the release notes for all modules being upgraded.
  2. Create a full backup of the MA_HOME directory, including both databases. See How to Backup Your Mango System.
  3. Verify your mango.properties customizations are in the overrides directory (MA_HOME/overrides/properties/). This ensures your settings survive the upgrade.
  4. Note your current version so you can report issues accurately if the upgrade causes problems.
  5. Plan for downtime -- Mango must restart during the upgrade process.

Standard Manual Upgrade Instructions​

For systems that cannot use the automatic upgrade:

  1. Stop Mango.
  2. Create a full backup of the MA_HOME directory and database. For MySQL, run mysqldump to back up the database.
  3. Ensure your customized properties file has been copied to MA_HOME/overrides/properties/mango.properties (this ensures changes are preserved after the upgrade).
  4. Delete the lib directory in MA_HOME.
  5. Download and extract the new Mango release zip file into the MA_HOME directory, overwriting existing files.
  6. Start Mango and verify the upgrade completed successfully.

Windows Service Management​

If you are running Mango as a Windows service, keep the following in mind when upgrading:

  1. Use the automatic upgrade from the Modules page and select the option to not restart Mango after downloading.
  2. Once the download completes, stop the Mango Windows service.
  3. Start Mango once from the command line using bin\mango.cmd to allow the upgrade to complete.
  4. After verifying the upgrade was successful, stop the command-line instance and restart the Windows service.

Troubleshooting​

Module Versions Not Updating​

If the Modules page still shows old versions after an upgrade, the lib directory may not have been properly cleaned. Stop Mango, delete the lib directory, re-extract the release files, and restart.

Upgrade Event Notifications​

Configure an email event handler for the "Upgrade Available" system event to receive automatic notifications when new versions are released.