Loading

Help documentation

Back to previous page

Upgrading from previous versions

Before you get started

    Applicability: These instructions are for upgrading from Mingle 12.1+. Upgrades and importing projects from earlier versions are not supported. (To learn more about ThoughtWorks Studios' Lifecycle Policy, please go here.)

  • 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 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 Mingle.
  • Any old project export files (.mingle files) and old plan export files (.plan files; Mingle Plus only) can be directly imported into this version of the application. They will be automatically upgraded upon import.
  • If you are using Apache to serve the Mingle public folder, please make sure to update the Apache configuration to point to the new Mingle location. We suggest using a symlink to the latest Mingle install location to avoid having to make this change each time you upgrade.

    • Running Oracle database migrations during upgrade may cause increased disk usage for your archive log space. If archive log space is a concern, please consider temporarily disabling your archive log while upgrading Mingle. For more recommendations for running Mingle on Oracle, please go here.

Installing the software

Windows

  1. 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.
  2. Run the Mingle uninstaller to remove your current installation. The uninstaller will stop the Mingle service if it is currently running.
  3. 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.
  4. Open your browser to any Mingle page. You will be warned to backup your data. Accept this and proceed after backing up your database.

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 OS X 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.

  1. 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".
  2. If the Mingle server is currently running, stop it by running './MingleServer stop' in the old Mingle installation directory.
  3. Untar the newly downloaded archive.
  4. 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.
  5. Open your browser to any Mingle page. You will be warned to backup your data. Accept this and proceed after backing up your database.

See Advanced configuration for additional configuration options.

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.