Upgrade Guide

This guide provides you general information to upgrade an on-premise deployment of iObeya.

We recommend upgrading your iObeya platform at least once a year to stay no more than one version behind the latest release. The iObeya support policy only supports the most recent minor version of iObeya on-premise servers.

Upgrade path

To successfully upgrade from an old version of iObeya, you must follow the upgrade path and upgrade to every version between the one you currently have and the targeted one.

Warning

If you need to go through several versions to upgrade your iObeya on-premise servers, follow the upgrade path and use the upgrade guide for the targeted version.

For each version of iObeya on-premise servers, it is necessary to first follow the upgrade guide for the corresponding version and restart the iObeya service once before proceeding to the next version.

Note

If you fall behind and your instance is on an unsupported version, please contact your dedicated Customer Success Manager, or our Support team (support@iobeya.com) to get guidance regarding the upgrade path to follow.

Preparation is the key to success. An upgrade is a good opportunity to assess whether the current environment meets your needs, or if it makes sense to make changes.

Additionally, upgrading to a new version may require new hardware or software to meet the technical requirements.

Prepare adequately and identify any necessary changes to ensure that your upgraded system works optimally and meets your needs in the long run.

Expect the best, prepare and plan for the worst. Even though the upgrade procedure is reliable and each new version of iObeya has been tested and validated during months with our Cloud customers, it always makes sense to prepare for any unforeseen issues when upgrading your on-premise instance.

As a precaution, it is important to understand how to revert to the previous version and how to check if you have a complete and consistent backup of your iObeya database and assets files available. This will ensure that you can easily restore your system to its previous state in the event of any unexpected problems during the upgrade process. Use the Backup and restore section to create a backup of your iObeya database and assets files.

Getting started

Warning

Do not forget to check the iObeya license deployed on your server before upgrading to a newer version of iObeya.

Attempting to upgrade to a version that has been released after the support date of your license will lead to the inability to restart iObeya. Information regarding the support date of the current license is available on the License page in the administration interface of the platform, as well as the release date on the Download page of the iObeya Resource Center.

The main steps to upgrade iObeya are the following:

Step 1: Prepare your environment

Check and upgrade your environment according to the technical requirements of the version you want to install.

The technical requirements may vary depending on the version of iObeya you want to install. We highly recommend carefully reviewing the technical requirements before upgrading your platform.

The technical requirements are available on the Resource Center for each on-premise version supported.

Warning

You must upgrade the required dependencies and technical requirements (e.g Java, Oracle or MySQL/MariaDB, Tomcat, JDBC drivers) before starting the upgrade procedure.

Step 2: Backing up your environment

You must back up your iObeya data before upgrading your server to a new iObeya version. With a backup you can roll-back your instance to the previous version if you encounter any unforeseen issues while upgrading your platform.

You can also use the backup to set up a test environment that replicates as closely as possible your production environment and practice the upgrade before upgrading your production environment.

Refer to the Backup and restore section for detailed guidance on creating backups of your iObeya database and assets files, and restoring them in the event of any issues during the upgrade process.

Step 3: Practicing on a test environment

We highly recommend to perform a dry run of the upgrade process in a pre-production environment. This allows you to thoroughly test the upgrade and rollback procedures in a safe and controlled environment before proceeding with the installation process to upgrade your production environment.

By following the Backup and restore instructions, you will be able to create a reliable pre-production environment that accurately reflects your production environment, enabling you to test the upgrade process thoroughly before implementing it in production.

Note

The upgrade procedure can take longer on every new version depending on the volume of data to migrate. We strongly recommend testing the upgrade procedure on a pre-production environment to estimate the required time to upgrade your production environment.

Step 4: Downloading the iObeya on-premise package

The iObeya on-premise package is a ZIP file containing the latest version of the web application, the SQL scripts and the configuration files you need to install iObeya on-prem.

Tip

You can download the latest version of iObeya on-premise on the Resource Center.

Step 5: Extract and configure the webapp

Extract the whole content of the zip file of the on-premise package into a directory of your choice.

Note

We will use <install_folder> to refer to this folder in the following steps of the upgrade procedure.

Warning

  • The default paths and examples given in this documentation are for Unix environment. If you are working on a Windows environment, use compatible paths (e.g. D:/iobeya/data using “/” as mentioned above).
  • To avoid deployment errors, you must use “/” instead of “\” in all the paths you define, even if you are using Microsoft Windows Server.
  • The iObeya web application will not create the paths and directories you define automatically. We recommend you create them while you define the paths during the configuration process.

In the <install_folder> you should find:

  • The iobeya folder, containing the files of the web application to be deployed
  • The scripts folder, containing the SQL scripts for both Oracle and MySQL/MariaDB
  • The Log4j2.xml file, allowing to configure the paths where to store the application logs
  • The ROOT.xml context file, allowing to configure the webapp and the connection to the database server

1 Configure application logs

To change where the application logs are stored, edit the log4j2.xml file of the version you want to install and change the value of the fileName and filePattern attributes for each Log4j 2 appenders declared in the file. The application server must be able to write in this directory.

Note

By default, the log4j2.xml file is configured to store logs in /var/iobeya/logs.

You can find the path that has been configured when installing the previous version of iObeya by editing the log4j2.xml file that is deployed on your iObeya instance.

2 Configure the database connection

You can find the database settings that has been configured when installing the previous version of iObeya by editing the ROOT.xml context file available in path_to_tomcat_directory/conf/Catalina/localhost.

Note

  • The name of the context file will have an impact on the context path to access the application on the server. By default the context file is named ROOT.xml to make it the root application.
  • The iObeya application will be accessible at https://yourserver.com/. To make iObeya available to another context on the server, rename the ROOT.xml file.
  • For instance, if you want to access iObeya via http://yourserver.com/iobeya, rename the file iobeya.xml.

To configure the database server to be used by the web application, edit the ROOT.xml context file of the version you want to install and configure the following attributes:

  • driverClassName (mandatory): by default the file is pre-configured for MySQL. If you plan to use MariaDB or Oracle, you can find the value to be used in the comment block available at the top of the ROOT.xml file.

    • MySQL: driverClassName=”com.mysql.jdbc.Driver”
    • MariaDB: driverClassName=”org.mariadb.jdbc.Driver”
    • Oracle: driverClassName=”oracle.jdbc.driver.OracleDriver”

  • url (mandatory): you need to configure the hostname or IP address of your database server. By default the url is pre-configured for MySQL/MariaDB. If you plan to use MariaDB or Oracle, you will find an example of the url format in the comment block available at the top of the ROOT.xml file.

  • username (mandatory): by default iObeya creates a dedicated user account iobeya to access the database.

    Check the value that was configured in the context file deployed on your running instance.

    • password (mandatory): by default the password for the user created by iObeya is iobeya.

      Note

      We recommend that you change the default password during the installation process. Check the value configured in the context file deployed on your running instance.

3 Configuring the web application

Warning

  • The default paths and examples given in this documentation are for Unix environment. If you are working on a Windows environment, use compatible paths (e.g. D:/iobeya/data using “/” as mentioned above).
  • To avoid deployment errors, you must use “/” instead of “\” in all the paths you define, even if you are using Microsoft Windows Server.
  • The iObeya web application will not create the paths and directories you define automatically. We recommend you create them while you define the paths during the configuration process.

Tip

To find the settings configured during the installation of the previous version of iObeya, edit the ROOT.xml context file available in path_to_tomcat_directory/conf/Catalina/localhost.

To configure the web application, edit the ROOT.xml context file of the version you want to install and configure the following attributes:

  • docBase (mandatory): on Tomcat, you will manually deploy iObeya as an exploded web application in a directory called docBase.

    You will have to copy the web application files into this directory later on. This deployment method gives you more flexibility and control over the application configuration.

    • e.g. /var/iobeya/webapp/4.16.1

  • baseDirectory (mandatory): A root directory that can be used as a reference for other directories.

    • e.g. /var/iobeya/

  • dataDirectory (mandatory): defines the directory where all the files managed by the application will be stored.

    • e.g. /var/iobeya/data

  • tempDirectory (mandatory): defines the directory where all the temporary files managed by the application will be stored.

    • e.g. /var/iobeya/data/temp

  • cacheDirectory (mandatory): defines the directory where all the cache files generated by the application will be stored.

    • e.g. /var/iobeya/data/cache

  • assetDirectory (mandatory): defines the directory where the assets (e.g. images) will be stored.

    • e.g. /var/iobeya/assets

  • indexDirectory (mandatory): defines the directory where the indexes will be stored.

    • e.g. /var/iobeya/index

  • log4j2FilePath (optional): defines the path to an external log4j2.xml configuration file. If not set, all logs go to the main application server log file.

    • e.g. /var/iobeya/settings/log4j2.xml
  • pluginsPropertiesDirectory (optional): defines the directory for the add-on’s external properties file.

    If not set, add-ons that require configuration files will not start.

    • e.g. /var/iobeya/settings/plugins

Step 6: Database upgrade

Warning

  • Make sure that a backup of the platform has been created before upgrading the iObeya database scheme.

    Use the Backup and restore section to create your backup.

  • If an error occurs when you run the scripts, please stop and contact our Support team (support@iobeya.com).

1 Update the iObeya database on MySQL/MariaDB

Replace <database_name> by the value defined when installing iObeya (default value for <database_name>: iobeya). Replace <database_address> by the IP address or the hostname of your database server.

  1. In a terminal window, log in with the user account used to run Tomcat.

  2. Stop Tomcat to stop the iObeya instance.

  3. Go into the <install_folder>/scripts/mysql/update directory of the new iObeya on-premise package.

  4. Determine the scripts that need to be executed.

    The scripts that need to be executed are the one in which the version number is superior or equal to your current version.

    They all must be executed in the right order. For instance, if you are running iObeya 4.12 and you plan to upgrade to iObeya 4.16, you will need to run the following scripts:

    4.13.0.sql

4.14.0-4.15.0.sql

4.15.0-4.16.0.sql

4.16.0.sql

Warning

Be careful when listing files by names on a Unix system, the files will be listed by alphanumeric order, not by version. For instance, 4.16.0.sql will appear listed after 4.1.0 and before 4.2.0, even if the version is higher.

For each SQL script <file_name>, run the following command line with the database root user account. You will be prompted to enter the root password:

mysql -h <database_address> -u root -p <database_name> < <file_name>

2 Update the iObeya database on Oracle

  1. Open a terminal window.

  2. Go into the <install_folder>/scripts/oracle/update directory of the installation package.

  3. Determine the scripts that need to be executed. The scripts that need to be executed are all the scripts where the version number is superior or equal to your current version. They all must be executed in numeric order. For instance, if you are running iObeya 4.12 and you plan to upgrade to iObeya 4.16, you will need to run the following scripts:

    4.13.0.sql

4.14.0-4.15.0.sql

4.15.0-4.16.0.sql

4.16.0.sql

    Warning

    Be careful when listing files by names on a Unix system, the files will be listed by alphanumeric order, not by version. For instance, 4.16.0.sql will appear listed after 4.1.0 and before 4.2.0, even if the version is higher.

  4. Execute sqlplus with the iObeya user; at the prompt, type the password. Run each script using the “@” symbol followed by the complete path to the script file.

    Warning

    Remember to type “commit;” at the end, or the changes will not be recorded.

  5. Optionally, you can synchronize sequences to linked tables. Run the following command line with the database root user account. The administrator will be prompted to enter the password:

    1. Execute sqlplus with the iObeya user.
    2. On the prompt, type the password.
    3. Run the sync-sequences.sql script using the “@” symbol followed by the complete path to the script file.

Step 7: Upgrade the web application

Warning

Make sure that a backup of the platform has been created before upgrading the iObeya database scheme.

Use the Backup and restore section to create your backup.

Follow these steps to update the iObeya web application on Tomcat:

  1. In a terminal window, log in with the user account used to run Tomcat.

  2. Stop Tomcat.

  3. Empty work folder of Tomcat.

  4. Delete old versions of the add-ons from the plugins folder in the iObeya data directory (Example: /var/iobeya/data/plugins/)

  5. Rename the old iObeya DocBase folder to DocBase-oldVersion (Example: iobeya-4.12 for iObeya 4.12)

  6. Move the iobeya directory contained in the new package to be the new DocBase directory (Example: /var/iobeya/webapp/4.16.1/)

    Warning

    As of iObeya 4.16, all the standard add-ons are now packaged in the web application. However, if you have installed any custom add-ons on your iObeya platform, refer to Updating an add-on to update an add-on.

  7. Rename the old context file ROOT.xml and old log4j2.xml file to back them up.

    Example: when upgrading from iObeya 4.12, rename them ROOT.xml.4.12 and log4j2.xml.4.12.

  8. Put the new ROOT.xml into the path_to_tomcat_directory/conf/Catalina/localhost directory of Tomcat.

  9. Put the new log4j2.xml file into the log4j2FilePath folder you configured in the ROOT.xml.

  10. Verify all the directory you defined in the new ROOT.xml exists:

    • the base directory,
    • the data directory,
    • the assets directory,
    • the logs directory,
    • the index directory,
    • the plugins properties directory.

Step 8: Final steps

Warning

Process time of the migration jobs can differ based on the size of your iObeya platform.

To finalize the upgrade of your iObeya platform:

  1. Start Tomcat.

    Warning

    The automated job MandatoryMigrationChecksJob will be automatically launched. You cannot access iObeya web application during this process.

    Note

    Once the first job is completed, iObeya is accessible and the job LongRunMigrationChecksJob is launched.

  2. Connect to the administration platform and check the status of these 2 jobs.

    Note

    The iObeya web application is accessible and can be used while the job LongRunMigrationChecksJob runs.

    It will finalize applying the required changes added in the new version.

    Tip

    You can also check the status of these two jobs by monitoring the iObeya logs files (app.log and error.log).