Upgrading from previous versions

Upgrading from Mingle 3.1

Before you get started

These instructions are for upgrading from Mingle 3.1 to Mingle 3.2. Look here to see how to upgrade from Mingle 3.0. 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, the 1.0 Early Access and 2.0 Early Access versions) are not supported.

Please ensure that no-one, 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.2 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 AT ANY COST.
The web.xml file will be replaced. If you have made custom changes to this file, you should backup this file and merge in your changes to the new web.xml. This file is located in the [mingle_installation]/config/ directory.
In particular, the cache_revision_content servlet command has changed from
```
RevisionContentCachingProcessor.run_once(:batch_size => 5, :timeout => 5000)
```
to
```
RevisionsContentCaching.run_once(5, false)
```
If you changed your batch size for RevisionContentCachingProcessor, you will want to change the first argument to RevisionsContentCaching as well.
The LDAP and CAS authentication properties, 'auto_enroll' and 'auto_enroll_as_mingle_admin', are no longer supported in mingle_data_directory/config/auth_config.yml. You will need to remove them from your configuration to start Mingle. The default behavior has not changed.
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 3.1 database will be upgraded and fully usable as soon as you start a newly installed 3.2 Mingle server.
Any old project export files (.mingle files) can be directly imported into the 3.2 version of the application. They will be automatically upgraded upon import.

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.
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_1 version of Mingle and nnnnn_xxxxx is the identifier for the 3_2 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.

OS X

Note the location of the Mingle data, swap, config directories and the port on which Mingle is currently running. These are both visible from the Mingle launcher application window.
Stop Mingle and quit the Mingle launcher application.
Drag the new copy of the Mingle application (Mingle_3_2_xxxx.app) into your Applications directory (overwriting the old Mingle).
Start Mingle, specifying the same data, swap, config directories and port as before.
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.
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_1 version of Mingle and nnnnn_xxxxx is the identifier for the 3_2 version of Mingle).

Linux/Unix

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.
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_1 version of Mingle and nnnnn_xxxxx is the identifier for the 3_2 version of Mingle).

For further information on configuring Mingle see here.

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. For a detailed explanation of how to change Mingle's authentication please see here.

Advanced configuration

For further information on configuring Mingle see here.

Upgrading from Mingle 3.0

Before you get started

These instructions are for upgrading from Mingle 3.0 to 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, the 1.0 Early Access and 2.0 Early Access versions) are not supported.

Please ensure that no-one, 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.2 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 AT ANY COST.
The web.xml file will be replaced. If you have made custom changes to this file, you should backup this file and merge in your changes to the new web.xml. This file is located in the [mingle_installation]/config/ directory.
In particular, the cache_revision_content servlet command has changed from
```
RevisionContentCachingProcessor.run_once(:batch_size => 5, :timeout => 5000)
```
to
```
RevisionsContentCaching.run_once(5, false)
```
If you changed your batch size for RevisionContentCachingProcessor, you will want to change the first argument to RevisionsContentCaching as well.
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 3.0 database will be upgraded and fully usable as soon as you start a newly installed 3.2 Mingle server.
Any old project export files (.mingle files) can be directly imported into the 3.2 version of the application. They will be automatically upgraded upon import.

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.
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_0 version of Mingle and nnnnn_xxxxx is the identifier for the 3_2 version of Mingle).

OS X

Note the location of the Mingle data, swap, config directories and the port on which Mingle is currently running. These are both visible from the Mingle launcher application window.
Stop Mingle and quit the Mingle launcher application.
Drag the new copy of the Mingle application (Mingle_3_2_xxxx.app) into your Applications directory (overwriting the old Mingle).
Start Mingle, specifying the same data, swap, config directories and port as before.
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.
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_0 version of Mingle and nnnnn_xxxxx is the identifier for the 3_2 version of Mingle).

Linux/Unix

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.
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_0 version of Mingle and nnnnn_xxxxx is the identifier for the 3_2 version of Mingle).