orcharhino Upgrade Guide

This guide describes how to upgrade orcharhino to a newer version.

orcharhino is a large software suite undergoing active development. It is necessary to upgrade orcharhino when ATIX releases new versions to take advantage of its new features and bug fixes. Refer to the orcharhino Release Notes for more information.

ATIX provides guided upgrades performed by our consultants as part of our support subscriptions. Please contact us if you would like to make use of this service.

Warning

Make sure you carefully read all of the instructions, warnings, and recommendations presented in this guide and the appropriate version specific orcharhino Upgrade Notes in the ATIX Service Portal. ATIX does not offer support for recovery from a failed upgrade if you did not follow our upgrade guide.

Version Specific Instructions

Version specific upgrade instructions are published in the ATIX Service Portal. Log in with your ATIX Support login credentials and follow the link to the orcharhino Upgrade Notes. Make sure you carefully read the version specific instructions before starting the upgrade.

If you are skipping versions in a single upgrade, read all of the version specific instructions for all intermediary versions. For example, if you are upgrading from orcharhino 5.0 to 5.2, then you should read instructions for the upgrade to version 5.2 as well as instructions for the upgrade to version 5.1. Please contact us if you are unsure on how to start with your orcharhino upgrade.

Using Foreman Maintain

orcharhino upgrades are performed using the foreman-maintain utility. By default, foreman-maintain will interactively guide you through the upgrade process.

See the inbuilt documentation to modify this behaviour and for advanced options:

foreman-maintain --help
foreman-maintain upgrade --help
foreman-maintain upgrade run --help

Make sure there are no paused tasks before starting the upgrade.

Upgrade Steps

Note

Always check the version specific upgrade steps before upgrading and always create a snapshot/backup as part of your upgrade.

  1. Check what orcharhino versions are available for upgrade

    1. Ensure foreman-maintain knows about the latest orcharhino releases

      yum update orcharhino-maintain-definitions
      
    2. List the available orcharhino releases

      foreman-maintain upgrade list-versions
      

      Refer to the orcharhino Release Notes for more information.

  2. Backup your orcharhino system

    We generally recommend running orcharhino as a virtual server and performing a system snapshot at this point. See the backup mechanisms section for more information.

  3. Perform the upgrade itself

    foreman-maintain upgrade run --target-version <target_version>
    

    <target_version> must be one of the versions obtained from step 1b.

    Refer to using foreman maintain for more information.

  4. Verify that everything works

    Check the backend system status: Important system components are listed in the backend system status area of the about page. The info box should list each component with OK as its status.

You now have a new orcharhino version. Enjoy!

Once you have upgraded successfully, it may be useful to create another snapshot/backup. This will allow you to roll back to the state immediately after upgrading, saving you the need to repeat the upgrade if a roll back becomes necessary.