Upgrading from previous versions
Upgrading from Mingle 3.3, 3.3.1, 3.4 or 3.4.1
Before you get started
- Please ensure that nobody, other than Mingle administrators completing the upgrade, has access to Mingle during the upgrade process. We expect that the upgrade of Mingle is completed by Mingle administrators only.
- The upgrade to 3.5 involves migration of your existing data which is a very sensitive process. We strongly recommend that you make a backup of the mingle data directory and your database before starting the upgrade process. DO NOT SHUT DOWN THE SERVER IN THE MIDDLE OF THE UPGRADE PROCESS.
- ANY TEMPLATES THAT WERE INSTALLED WITH THE PREVIOUS RELEASES WILL BE REPLACED. This has no impact on any of your existing projects or any templates that you have created yourself. If you have modified the pre-installed templates and wish to keep them, you must export them and then import them using a different name before the upgrade.
- The Mingle database will be upgraded and any projects in your database will be upgraded and fully usable as soon as you start a newly installed 3.5 Mingle server.
- Any old project export files (.mingle files) can be directly imported into this version of the application. They will be automatically upgraded upon import.
Applicability: These instructions are for upgrading from Mingle 3.3, Mingle 3.3.1 or Mingle 3.4 to Mingle 3.5. See Upgrading from Mingle 3.2 for information about how to upgrade from Mingle 3.2. Upgrades and importing projects from earlier versions (such as 1.0, 1.1, 2.0, 2.0.1, 2.1, 2.2, 2.3, 2.3.1, 3.0, 3.1, the 1.0 Early Access and 2.0 Early Access versions) are not supported.
Installing the software
Windows
- Note the location of the Mingle data, swap, config directories and the port on which Mingle is currently running. Typically, the Mingle data directory is in your home directory (C:\Documents and Settings\[username]\Mingle) and the port is 8080.
- Run the Mingle uninstaller to remove your current installation. The uninstaller will stop the Mingle service if it is currently running.
- Run the new installer, specifying the same data, swap, config directories and port as the previous installer. The installer will automatically start the new Mingle service when it completes.
- Open your browser to any Mingle page. You will be warned to backup your data. Accept this and proceed after backing up your database.
- You may like to move the revision cache from the old cache directory (/[swap_dir]/mmmmm_xxxxx/cache) to the new location (/[swapDir]/nnnnn_xxxxx) in order to preserve your revision cache and avoid having to wait for the cache to rebuild (where mmmmm_xxxxx is the identifier for the 3_3_1 version of Mingle and nnnnn_xxxxx is the identifier for the 3_5 version of Mingle).
If you do not uninstall Mingle manually and try to install a newer version at the same location as an existing installation, Mingle will automatically uninstall the existing installation of Mingle before installing the new version.
Linux/Unix/Mac OS X
As the Mac OSX installer is no longer supported, if you have previously used this installer, you will need to migrate to use the Linux/Unix installer.
- Note the path of the data directory and the config directory from the old Mingle launch window. You can safely ignore the the values specified for port and swap directory.
- Follow the Linux/Unix installation steps below specifying your data directory and your config directory locations from your previous installation.
- Note the location of the Mingle data, swap, config directories and port on which Mingle is currently running. You may retrieve these locations by running "ps aux | grep MingleServer".
- If the Mingle server is currently running, stop it by running './MingleServer stop' in the old Mingle installation directory.
- Untar the newly downloaded archive.
- Start Mingle, using './MingleServer --mingle.dataDir=/path/to/your/data start' where /path/to/your/data is the location of your data directory. Use the '--mingle.swapDir' and '--mingle.configDir' switches should you want to override the defaults.
- Open your browser to any Mingle page. You will be warned to backup your data. Accept this and proceed after backing up your database.
- You may like to move the revision cache from the old cache directory (/[swap_dir]/mmmmm_xxxxx/cache) to the new location (/[swapDir]/nnnnn_xxxxx) in order to preserve your revision cache and avoid having to wait for the cache to rebuild (where mmmmm_xxxxx is the identifier for the 3_3_1 version of Mingle and nnnnn_xxxxx is the identifier for the 3_5 version of Mingle).
After installation is complete...
Configuring Mingle's authentication
The authentication settings for Mingle are controlled through the [mingle_data_directory]/config/auth_config.yml file. This file is created by default on all brand new installations.
Advanced configuration
See Advanced configuration for additional configuration options.
Upgrading from Mingle 3.2
Before you get started
-
Java 5 support end-of-life: As of Mingle 3.3, Java 5 (JDK 1.5) is no longer supported. See system requirements and installation and upgrade troubleshooting help for more information.
-
AJP support end-of-life: Starting with Mingle 3.3, Mingle will no longer support the AJP connector. If you have previously configured Mingle to use the AJP connector in the mingle.properties file, you will have to remove it there. Also, in your Apache configuration, instead of mod_jk and mod_proxy_ajp, you will have to set up a different reverse proxy such as mod_proxy. Please go to the Mingle Apache page to see some recommendations on how to set up mod_proxy on Apache.
-
Custom macros (advanced): If you have custom macros, you may be interested in the following changes. Due to some changes to Mingle's infrastructure, we recommend the following changes for custom macros:
- Explicitly require all files (aka classes) that the macro needs in init.rb.
- Be careful about class instance variables. Storing instance variables in the class object may yield unexpected thread-safe results. You may want to use the Thread local space instead.
- Please ensure that nobody, other than Mingle administrators completing the upgrade, has access to Mingle during the upgrade process. We expect that the upgrade of Mingle is completed by Mingle administrators only.
- The upgrade to 3.5 involves migration of your existing data which is a very sensitive process. We strongly recommend that you make a backup of the mingle data directory and your database before starting the upgrade process. DO NOT SHUT DOWN THE SERVER IN THE MIDDLE OF THE UPGRADE PROCESS.
-
The web.xml file has undergone big changes. Some changes in previous versions of Mingle's web.xml file no longer apply in this version of Mingle. If you have made custom changes in your web.xml, we advise you backup your web.xml file and start using the one that comes from the default Mingle 3.3.1 installation, then only transfer your old custom web.xml changes back to the web.xml file if the same setting still exist in the new web.xml. This file is located in the [mingle_installation]/config/ directory.
Mingle 3.3+ will NOT start properly if you are using a web.xml file from older versions of Mingle.
-
Similar to the web.xml file, jetty.xml also has undergone big changes. In the past, some users had to customize their jetty.xml to allow Mingle to serve https requests without Apache and mod_ssl. Starting with 3.3, this is natively supported in Mingle. Instructions on how to configure it can be found in Configure SSL Access section. For any other custom changes to your jetty.xml, we advise you backup your jetty.xml file and start using the one that comes from the default Mingle 3.3.1 installation, and transfer these old jetty.xml changes back to the jetty.xml file. This file is located in the [mingle_installation]/config/ directory.
Mingle 3.3+ will NOT start properly if you are using a jetty.xml file from older versions of Mingle.
- ANY TEMPLATES THAT WERE INSTALLED WITH THE PREVIOUS RELEASES WILL BE REPLACED. This has no impact on any of your existing projects or any templates that you have created yourself. If you have modified the pre-installed templates and wish to keep them, you must export them and then import them using a different name before the upgrade.
- The Mingle database will be upgraded and any projects in your database will be upgraded and fully usable as soon as you start a newly installed 3.5 Mingle server.
- Any old project export files (.mingle files) can be directly imported into this version of the application. They will be automatically upgraded upon import.
- If you are migrating to Mingle 3.5 and have properties containing ';' or '"' in the name, the ';' or '"' will be converted to an '_' and any previous uses of these properties (in formulas, history subscriptions etc…) will be updated. Use in MQL (including MQL filters and conditional aggregates) will not be updated, you will see error message on relevant pages and you must manually update them.
Applicability: These instructions are for upgrading from Mingle 3.2 to Mingle 3.5. Upgrades and importing projects from earlier versions (such as 1.0, 1.1, 2.0, 2.0.1, 2.1, 2.2, 2.3, 2.3.1, 3.0, 3.1, the 1.0 Early Access and 2.0 Early Access versions) are not supported.
Installing the software
Windows
- Note the location of the Mingle data, swap, config directories and the port on which Mingle is currently running. Typically, the Mingle data directory is in your home directory (C:\Documents and Settings\[username]\Mingle) and the port is 8080.
- Run the Mingle uninstaller to remove your current installation. The uninstaller will stop the Mingle service if it is currently running.
- Run the new installer, specifying the same data, swap, config directories and port as the previous installer. The installer will automatically start the new Mingle service when it completes.
- Open your browser to any Mingle page. You will be warned to backup your data. Accept this and proceed after backing up your database.
- You will be walked through the upgrade steps. All existing project data will be upgraded for continued use. A new upgrade step to configure the site URL and secure site URL has been added.
- You may like to move the revision cache from the old cache directory (/[swap_dir]/mmmmm_xxxxx/cache) to the new location (/[swapDir]/nnnnn_xxxxx) in order to preserve your revision cache and avoid having to wait for the cache to rebuild (where mmmmm_xxxxx is the identifier for the 3_2 version of Mingle and nnnnn_xxxxx is the identifier for the 3_4 version of Mingle).
If you do not uninstall Mingle manually and try to install a newer version at the same location as an existing installation, Mingle will automatically uninstall the existing installation of Mingle before installing the new version.
Linux/Unix/Mac OS X
As the Mac OSX installer is no longer supported, if you have previously used this installer, you will need to migrate to use the Linux/Unix installer.
- Note the path of the data directory and the config directory from the old Mingle launch window. You can safely ignore the the values specified for port and swap directory.
- Follow the Linux/Unix installation steps below specifying your data directory and your config directory locations from your previous installation.
- Note the location of the Mingle data, swap, config directories and port on which Mingle is currently running. You may retrieve these locations by running "ps aux | grep MingleServer".
- If the Mingle server is currently running, stop it by running './MingleServer stop' in the old Mingle installation directory.
- Untar the newly downloaded archive.
- Start Mingle, using './MingleServer --mingle.dataDir=/path/to/your/data start' where /path/to/your/data is the location of your data directory. Use the '--mingle.swapDir' and '--mingle.configDir' switches should you want to override the defaults.
- Open your browser to any Mingle page. You will be warned to backup your data. Accept this and proceed after backing up your database.
- You will be walked through the upgrade steps. All existing project data will be upgraded for continued use. A new upgrade step to configure the site URL and secure site URL has been added.
- You may like to move the revision cache from the old cache directory (/[swap_dir]/mmmmm_xxxxx/cache) to the new location (/[swapDir]/nnnnn_xxxxx) in order to preserve your revision cache and avoid having to wait for the cache to rebuild (where mmmmm_xxxxx is the identifier for the 3_2 version of Mingle and nnnnn_xxxxx is the identifier for the 3_4 version of Mingle).
After installation is complete...
Configuring Mingle's authentication
The authentication settings for Mingle are controlled through the [mingle_data_directory]/config/auth_config.yml file. This file is created by default on all brand new installations.
Advanced configuration
See Advanced configuration for additional configuration options.