Upgrade Guide

Getting started

Please note that iObeya includes a Server ID licensing management procedure since version 4.0. Depending on the version of iObeya you are currently using, you will need to follow the appropriate procedure:

  • Versions prior to 3.7.14: Contact support@iobeya.com to inform them of when you are planning to perform your update. Once your server has been updated to iObeya version 4.0 or later, connect to the administration interface to obtain your server ID. Send this to our Support Team to receive your new iObeya license.
  • version 3.7.14 and later: Connect to the administration interface, edit your license to obtain your server ID and send this to support@iobeya.com to receive your new iObeya license. This will allow you to update your server.
  • version 4.0 and later: You don’t need to upgrade your licence. However, if you are setting up a new pre-production environment to test the upgrade procedure, you will require to connect to the administration interface to obtain your pre-production server ID and send this to support@iobeya.com to get a pre-production licence.

Warning

Please do not forget to always 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 licence 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 taken to upgrade iObeya are the following:

  1. If you are using a specific authentication method, create a local admin account on your platform and ensure that you can connect with this local account. Otherwise you will not be able to connect to iObeya to complete the configuration.
  2. Package the new version of iObeya.
  3. Update the database.
  4. Update the webapp deployed by the application server.

Before beginning the upgrade procedure, please ensure the information below is taken into account.

Upgrade your environment

Please refer to the new technical requirements of the version you plan to install before starting the process to upgrade your iObeya environment.

Warning

If you are using the enterprise directory or single sign-on, please ensure you have a local administrator account on your platform and create one if it does not exist. You may need a local administrator account to access the administration interface in order to configure your authentication policy after the upgrade.

Backing up

A backup of iObeya must be created before upgrading the software. This allows for a restoration of the platform and avoids the loss of data.

To do so, refer to the backup & restore page.

Testing the upgrade on a test environment

We recommend that the platform administrator performs the upgrade on a replica of the production platform to test the procedure and validate it.

Warning

As of version 4.5, the upgrade procedure can take longer time depending the volume of data to migrate. We strongly recommend to test the upgrade procedure on a test environment to estimate the required time to upgrade your production environment.

To do so, follow the procedure below in a test environment.

Step 1: Packaging the new version

Warning

Make sure that a backup of the platform has been created before performing the update.

The very first step consists in packaging the new version of iObeya. This operation will generate the webapp file, the configuration files, and optionally update the database. Please refer to STEP 1 - Packaging instructions of the installation guide before continuing to the next step.

Step 2: Database upgrade

Warning

Make sure that a backup of the platform has been created before performing the update.

Warning

If the option was chosen in the previous step to let the packager update the database, skip this step.

Warning

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> and <database_username> by the name and the username defined during packaging (default values for <database_name> and <database_username> are: 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 and stop Tomcat.

  2. If you are upgrading from a version < 3.5 configure your database:

    1. Open your MySQL/MariaDB configuration file (my.cnf or my.ini).
    2. Make sure to set the client and server character set to utf8mb4. Your configuration file must contains the following lines:
    [client]
default-character-set = utf8mb4
[mysql]
default-character-set = utf8mb4
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
    1. Restart your MySQL/MariaDB server.
  3. In a terminal window, go into the <install_folder>mysqldbscripts directory of the

    installation package.

  4. Determine the scripts that need to be executed. There is a script for each major version and sometimes there is a script for minor versions, and they all must be executed in order, to ensure stability of the database. The scripts that need to be executed are all the scripts where the first version number is superior or equal to your version.

  5. For each script, 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> < 4.X.Y-4.X.Z.sql

2 Update the iObeya database on Oracle

  1. Open a terminal window.

  2. Go into the <install_folder>mysqldbscripts directory of the installation package.

  3. Determine the scripts that need to be executed. There is a script for each major version and sometimes there is a script for minor versions, and they all must be updated in order, to ensure stability of the database. The scripts that need to be executed are all the scripts with the first version number superior or equal to your version.

  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. On the prompt, type the password.
    2. Run the sync-sequences.sql script using the “@” symbol followed by the complete path to the script file.

Step 3: Upgrade on Tomcat

Warning

Make sure that a backup of the platform has been created before performing the update.

Warning

Files used by iObeya are managed in a different way since the release of version 3.7. A base directory is introduced which acts as a reference for other directories. Moreover the data directory has been reorganized, introducing a cache directory, a temp directory and an index directory. To make iObeya work, these directories have to be created.

Follow these steps to update the iObeya on Tomcat:

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

  2. Empty Tomcat’s Work folder.

  3. Rename the old iObeya DocBase folder to DocBase-version (Example: iobeya-37 for iObeya 3.7)

  4. Create the new iObeya DocBase directory.

  5. Unzip the new iobeya.war webapp file into this new DocBase directory.

    Warning

    If you have installed any add-on on your iObeya platform, refer to the updating an add-on procedure.

  6. Rename the old context file and old log4j2.xml file to contextname.xml.version and log4J2.xml.version (Example: ROOT.xml.3.7 and log4j2.xml.3.7)

  7. Put the new context file into the path_to_tomcat_directory/conf/Catalina/localhost directory of Tomcat.

  8. Put the log4j2.xml file into the log4j2FilePath folder.

  9. Verify the defined paths to the following directories:

    1. the base directory
    2. the data directory
    3. the assets directory
    4. the logs directory
    5. the index directory exists. If not, create it.
    6. the cache directory exists. If not, create it.
    7. the temp directory exists. If not, create it.

Step 4: Final steps

1 Install Fonts if you are upgrading from version < 3.5

Two types of fonts need to be installed for screenshot generation:
  • In order to generate screenshots with textual elements, there must be a TrueType font like Arial (or one of the metric compatible fonts: Liberation Sans or Arimo) installed on the server.
  • To be able to generate screenshots of boards containing emojis, there must be an emoji-compatible font installed on the server (like OpenSansEmoji, Symbola or EmojiSymbols).

Install fonts on Windows

For text elements, Arial font is provided by default with Windows.

For Emojis, you need to:

  1. Download a compatible font like OpenSansEmoji. (https://github.com/MorbZ/OpenSansEmoji/blob/master/OpenSansEmoji.ttf)
  2. Drag and drop this file on your Windowsfonts repository.

Install fonts on Linux

For non-European character sets, you must have a compatible font installed on the server.

The installation process depends on your system. You need to restart your application server after installing fonts.

For a European character set:

  • For Linux distributions supporting yum:

    yum install liberation-*

  • For other distributions:

    1. Download the font available here: https://releases.pagure.org/liberation-fonts/ (Take the binary (ttf): liberation-fonts-ttf-1.07.4.tar.gz).
    2. Untar content in the folder: /usr/share/fonts.
    3. Use the following command to let the server integrate the new font: fc-cache -f -v

For other character sets, you can use these commands on compatible systems:

  • Japanese: yum groupinstall “Japanese Support”.
  • Chinese: yum groupinstall “Chinese Support”.
  • Korean: yum groupinstall “Korean Support”.
  • Kannada: yum groupinstall “Kannada Support”.
  • Hindi: yum groupinstall “Hindi Support”.

For Emojis:

  1. Download the font available here: https://github.com/MorbZ/OpenSansEmoji/raw/master/OpenSansEmoji.ttf.
  2. Add the font in the folder: /usr/share/fonts.
  3. Use the following command to let the server integrate the new font: fc-cache -f -v

2 Start Tomcat

Start Tomcat to finalize the upgrade of your iObeya platform and start the web application.

3 After starting Tomcat

When starting Tomcat, the integrityCheckTasks job will be automatically launched. You cannot access the application during this process. Since version 3.7, assets cannot be saved in a database but only in a filesystem. The integrityCheckTasks will automatically remove assets in the database and copy them into the “assets” directory. Before using the application, connect to the administration interface and check that the integrityCheckTasks job has ended. It will finalize applying changes added in the new version, so it may take a significant amount of time depending on the size of your iObeya platform. You can also check that the integrityCheckTasks job has ended by monitoring the app.log file.

4 Configure your authentication policy from the administration section (optional)

Now, to configure a specific method of authentication, you can connect to the administration interface of iObeya to configure your authentication policies. To do this, use the local administrator account that you’ve created in iObeya before starting the upgrade procedure. Please refer to the section “Configuring your authentication policy” in the Administrator guide.