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.

  • From iObeya 4.5, you have to upgrade to iObeya 4.6 (4.6 download)
  • From iObeya 4.6, you have to upgrade to iObeya 4.8 (4.8 download)
  • From iObeya 4.8, you have to upgrade to iObeya 4.12 (4.12 download)
  • From iObeya 4.12, you have to upgrade to iObeya 4.16 (4.16 download)
  • From iObeya 4.16, you have to upgrade to iObeya 4.20 (4.20 download)
  • From iObeya 4.20, you have to upgrade to iObeya 4.31 (4.31 download)

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 download page for each on-premise version.

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 liquibase folder, containing liquibase files for Oracle, MariaDB and MySQL,
  • 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.

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.cj.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. 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. By default the installation procedure create a database schema named iobeya. If you changed the database schema name during the installation process, you will have to change this value in the url. Check the value that was configured in the context file deployed on your running instance.

  • 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.20.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).

Starting with iObeya version 4.20, Liquibase (https://docs.liquibase.com/) is used to version control the iObeya database schema. Liquibase is an open-source database-independent library for tracking, managing, and applying database schema changes. It provides a way to apply changes to the database in a consistent and trackable manner. In this chapter, you will learn how to use Liquibase to upgrade the iObeya database schema.

Liquibase directory structure

In the iObeya packages you’ve downloaded you will find a Liquibase directory containing the following files and directories:

  • iobeya-sql-changelog.jar (the Liquibase changesets package containing all the changes to initialize the iObeya database)
  • mysql
    • mysql-connector-java.jar (the JDBC driver for MySQL)
    • liquibase.properties (Liquibase configuration file preconfigured for MySQL)
  • mariadb
    • mariadb-java-client.jar (the JDBC driver for MariaDB)
    • liquibase.properties (Liquibase configuration file preconfigured for MariaDB)
  • oracle
    • ojdbc8.jar (the JDBC driver for Oracle)
    • liquibase.properties (Liquibase configuration file preconfigured for Oracle)

Liquibase configuration

First, you will have to edit the preconfigured liquibase.properties file corresponding to your database server to provide the information that Liquibase needs to connect.

Warning

Even if it’s possible, we strongly recommend that you do not include authentication information in your liquibase.properties file. You can use instead command line arguments to provide sensitive credentials using environment variables for instance.

From the root directory of the iObeya packages:

  1. Open the liquibase directory

  2. Open the directory corresponding to your database server (e.g mariadb, mysql, oracle)

  3. Edit the liquibase.properties file

  4. Change the following parameters:

    • liquibase.command.url: provide the url and port of your database server

    Warning

    By default, the installation procedure creates a database schema named iobeya. If you changed the database schema name during the installation process, you will have to change this value in the url parameter defined in the liquibase.properties file. Check the value that was configured in the context file deployed on your running instance.

Upgrading the iObeya database schema

  1. Open a terminal window in the liquibase directory.

MySQL: Upgrading the iObeya database schema

Please run the following command to upgrade your database for the migration to the latest version on-premises of iObeya. Replace <ROOT_USERNAME> and <ROOT_PASSWORD> with the ROOT username and password of your MySQL server.

java -jar iobeya-sql-changelog.jar --defaultsFile=mysql/liquibase.properties --username=<ROOT_USERNAME> --password=<ROOT_PASSWORD> update

Liquibase is going to execute the changesets required to upgrade the iObeya database schema. At the end of the process, you should see the following message.

Liquibase command 'update' was executed successfully.

MariaDB: Upgrading the iObeya database schema

Please run the following command to upgrade your database for the migration to the latest version on-premises of iObeya. Replace <ROOT_USERNAME> and <ROOT_PASSWORD> with the ROOT username and password of your MariaDB server.

java -jar iobeya-sql-changelog.jar --defaultsFile=mariadb/liquibase.properties --username=<ROOT_USERNAME> --password=<ROOT_PASSWORD> update

Liquibase is going to execute the changesets required to upgrade the iObeya database schema. At the end of the process, you should see the following message.

Liquibase command 'update' was executed successfully.

Oracle: Upgrading the iObeya database schema

Please run the following command to upgrade your database for the migration to the latest version on-premises of iObeya. Replace <DATABASE_USERNAME> and <DATABASE_PASSWORD> with the values configured in the context file deployed on your running instance.

java -jar iobeya-sql-changelog.jar --defaultsFile=oracle/liquibase.properties --username=<DATABASE_USERNAME> --password=<DATABASE_PASSWORD> update

Liquibase is going to execute the changesets required to upgrade the iObeya database schema. At the end of the process, you should see the following message.

Liquibase command 'update' was executed successfully.

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 version of the JDBC drivers from path_to_tomcat_directory/lib/ directory of Tomcat.

  5. Copy the new JDBC drivers into the path_to_tomcat_directory/lib/ directory of Tomcat.

    Note

    Check the iObeya the technical requirements to identify which version of the JDBC drivers you should use according to your database server.

    Note

    From our experience, we get better performance with the MariaDB JDBC connector compared to the MySQL JDBC connector.

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

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

  8. Move the iobeya directory contained in the new package to be the new DocBase directory (Example: /var/iobeya/webapp/4.20.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.

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

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

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

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

  12. 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

Configure Tomcat memory and classpath settings

Warning

This step is mandatory when upgrading from iObeya 4.20 to iObeya 4.31, or when upgrading Tomcat (changing default configurations).

The latest version of iObeya requires to:

  • review Tomcat memory settings.

    Procedures and guidelines for configuring memory and classpath settings are fully documented in our installation guide.

  • install and use Jemalloc 3.3.1 to optimize memory allocation if you only upgrade iObeya on a Linux environment (or Unix-based environment).

    Procedures for installing and using Jemalloc 3.3.1 are fully documented in our installation guide.

You must ensure that your Tomcat is configured following our recommendations before moving to the next step.

Restart iObeya

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).