Installation Guide

iObeya includes a Server ID licensing management procedure. Once iObeya is installed, contact our Support team (support@iobeya.com) and send us the Server ID that will be displayed in the platform administration interface. With your private Server ID we will be able to send you the corresponding license to be activated in the administration interface.

The main steps for the installation of iObeya are:

Step 1: Check and install the technical requirements

Warning

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

The technical requirements may vary depending on the version of iObeya you want to install. Carefully review the technical requirements before installing your platform.

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

Step 2: Download the iObeya on-prem package

The iObeya on-prem 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.

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

Step 3: Extract and configure the webapp

Warning

  • To avoid deployment errors, you must use “/” instead of “\” in all the paths you define, even if you are using Microsoft Windows Server.
  • The default paths and the 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).
  • 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.

Extract the whole content of the ZIP file of the on-prem package into a directory of your choice. We will use <install_folder> to refer to this folder in the following steps of the installation procedure.

In the <install_folder> you find:

  • the iobeya folder: contains the files of the web application to be deployed,
  • the liquibase folder: contains liquibase files for Oracle, MariaDB and MySQL,
  • the log4j2.xml file: allows you to configure the paths where to store the application logs,
  • the ROOT.xml context file: allows you to configure the webapp and the connection to the database server

1 Configure application logs

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

To change where the application logs are stored, edit the log4j2.xml file 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.

2 Configure the database connection

To configure the database server to be used by the web application, edit the ROOT.xml context file 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. 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 SQL scripts will create a database schema named iobeya. You can change this value by editing this attribute in the url and specifying the Liquibase command line arguments accordingly, or manually creating the database schema in your database server.

  • username (mandatory): by default the SQL scripts will create a new user iobeya to access the database. You can change this value by editing this attribute in the context file and specifying the Liquibase command line arguments accordingly, or manually creating the user in your database server.

  • password (mandatory): by default the password for the user created by the SQL scripts is iobeya. You can change this value by editing this attribute in the context file and specifying the Liquibase command line arguments accordingly, or manually creating the user with the password of your choice in your database server.

3 Create the folder structure on the application server

With this section, you will create the different directories that will be used to store the files of the application (the webapp, the log files, the images, etc).

  1. Connect to the application server with the user account used to run Tomcat.
  2. Create the Base directory (mandatory): this is the root directory that can be used as a reference for other directories.
    • e.g. /var/iobeya/
  3. Create the docBase directory (mandatory): defines the directory where all the webapp application files will be stored.
    • e.g. /var/iobeya/webapp/4.16.1
  4. Create the Data directory (mandatory): defines the directory where all the files managed and generated by the application will be stored.
    • e.g. /var/iobeya/data
  5. Create the Asset directory (mandatory): defines the directory where the assets (e.g. images) will be stored.
    • e.g. /var/iobeya/assets
  6. Create the Index directory (mandatory): defines the directory where the indexes will be stored.
    • e.g. /var/iobeya/index
  7. Create the Plugins Properties directory (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
  8. Create the Logs directory (mandatory): defines the directory that will store the application logs of iObeya.
    • e.g. /var/iobeya/logs

You will need the paths to these directories when you configure your ROOT.xml in Tomcat so that Tomcat knows where these directories are located.

4 Configure the web application

Warning

  • To avoid errors, you must use “/” instead of “\” in all the paths you define, even if you are using Microsoft Windows Server.
  • The default paths and the 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)
  • 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.

To configure the webapp, edit the ROOT.xml context file 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 4: Database initialization

Warning

If you are upgrading from a previous version of iObeya, follow the procedure in the Upgrade Guide.

Warning

If an error occurs when you run during the database initialization, 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 initialize 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
    • if your database MariaDB or MySQL you have to set the variable createDatabaseIfNotExist to true at the end of the connection url

    Warning

    During the database initialization procedure, Liquibase will create a dedicated database named iobeya. If you want to change the database name during the process, you will have to adapt accordingly the database name in the URL defined in the liquibase.properties file.

Initialize the database

To initialize your database, go into the Liquibase directory of the iObeya packages and run the CLI commands corresponding to your database server. For each supported database, we provide you one procedure to initialize the iObeya database with our default settings, and an advanced procedure allowing to change the database settings.

  1. Open a terminal window in the liquibase directory

MySQL: Initializing the database with default settings

If you want to keep the default iObeya database settings, use the following command and 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 initialize the iObeya database schema. At the end of the process, you should see the following message.

Liquibase command 'update' was executed successfully.

MySQL: Initializing the database with custom settings

If you want to modify the default iObeya database settings (database name, username, or password), use the following command. Replace <ROOT_USERNAME> and <ROOT_PASSWORD> with the database ROOT username and password of your MySQL server, and provide the values for <DATABASE_NAME>, <DATABASE_USERNAME>, and <DATABASE_PASSWORD>.

java -Ddb.username=<DATABASE_USERNAME> -Ddb.default.password=<DATABASE_PASSWORD> -Ddb.name=<DATABASE_NAME> -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 initialize the iObeya database schema. At the end of the process, you should see the following message.

Liquibase command 'update' was executed successfully.

MariaDB: Initializing the database with default settings

If you want to keep the default iObeya database settings, use the following command and 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 initialize the iObeya database schema. At the end of the process, you should see the following message.

Liquibase command 'update' was executed successfully.

MariaDB: Initializing the database with custom settings

If you want to modify the default iObeya database settings (database name, username, or password), use the following command. Replace <ROOT_USERNAME> and <ROOT_PASSWORD> with the database ROOT username and password of your MariaDB server, and provide the values for <DATABASE_NAME>, <DATABASE_USERNAME>, and <DATABASE_PASSWORD>.

java -Ddb.username=<DATABASE_USERNAME> -Ddb.default.password=<DATABASE_PASSWORD> -Ddb.name=<DATABASE_NAME> -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 initialize the iObeya database schema. At the end of the process, you should see the following message.

Liquibase command 'update' was executed successfully.

Oracle: Initializing the database with default settings

If you want to keep the default iObeya database settings, use the following command and replace <ROOT_USERNAME> and <ROOT_PASSWORD> with the SYSTEM username and password of your Oracle server.

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

Liquibase is going to execute a first changeset required to initialize the iObeya database. At the end of the process you should see the following message.

Liquibase command 'update' was executed successfully.

Now run the following command to finilize the database initialization process.

java -jar iobeya-sql-changelog.jar --defaultsFile=oracle/liquibase.properties --contexts=default update

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

Liquibase command 'update' was executed successfully.

Oracle: Initializing the database with custom settings

If you want to modify the default iObeya database settings (database name, username, or password), use the following command. Replace <ROOT_USERNAME> and <ROOT_PASSWORD> with the database SYSTEM username and password of your Oracle server, and provide the values for <DATABASE_NAME>, <DATABASE_USERNAME>, and <DATABASE_PASSWORD>.

java -Ddb.username=<DATABASE_USERNAME> -Ddb.default.password=<DATABASE_PASSWORD> -Ddb.name=<DATABASE_NAME> -jar iobeya-sql-changelog.jar --defaultsFile=oracle/liquibase.properties --username=<ROOT_USERNAME> --password=<ROOT_PASSWORD> --contexts=init_oracle_db update

Liquibase is going to execute a first changeset required to initialize the iObeya database. At the end of the process you should see the following message.

Liquibase command 'update' was executed successfully.

Now run the following command to finilize the database initialization process.

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

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

Liquibase command 'update' was executed successfully.

Step 5: Application server configuration

1 Upload the iObeya installation directory

  1. Connect to the application server with the user account used to run Tomcat.
  2. Upload the <install_folder> to the server.

2 Deploy the iObeya webapp

Tomcat directory

  1. Copy the ROOT.xml context file into the path_to_tomcat_directory/conf/Catalina/localhost directory of Tomcat. If these directories do not exist, they should be created manually.

    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. Then the iObeya application will be accessible at http://yourserver.com/. To make iObeya available to another context on the server then rename the ROOT.xml file. For instance, if you want to access iObeya via http://yourserver.com/iobeya, then rename the file iobeya.xml.

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

iObeya webapp directory

  1. Copy the content of <install_folder>/iobeya/ into the docBase folder.
  2. Copy the log4j2.xml file into the log4j2FilePath folder.

Step 6: Final steps

1 Installing fonts

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 system.
  • To be able to generate screenshots of boards containing emojis, there must be an emoji-compatible font installed on the system (like OpenSansEmoji, Symbola or EmojiSymbols).

Install fonts on Windows

For text elements, Arial font is provided by default with Windows. You can skip this step if you are using Windows as a server and you are not planning to use Japanese. If you consider using Japanese, its language pack must be installed on your Windows server.

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 in your Windows Fonts directory.

Install fonts on Linux

For a non-European character set, you must have a compatible font installed.

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 TrueType (ttf) binary).

    2. Extract the content to 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 Increase server memory allocation

Java applications like iObeya run in a “Java Virtual Machine” (JVM), instead of running directly within an operating system.

When started, the Java Virtual Machine is allocated a certain amount of memory available to applications it hosts. By default, Java Virtual Machines are allocated 64Mb of memory, no matter how many gigabytes of memory the server may actually have available. This amount is inadequate for standard iObeya installations so it needs to be increased.

Increase server memory allocation on Windows

There are two ways to configure system properties if Tomcat is started as a service.

Setting properties for Windows services via command line

  1. Go into the /bin directory of the Tomcat installation.

  2. Execute Tomcat9w.exe.

  3. Set the maximum memory allocation to 2048m or more, depending on the memory you want to allocate.

    Tip

    We recommend to set a value inferior or equal to 55% of the total memory allocated to the server or virtual machine.

  4. Click on the Java tab to see the list of current start-up options.

  5. Add to the java options section the following parameters:

    1. -XX:MaxMetaspaceSize=512m

      Tip

      We recommend to set a value inferior or equal to 15% of the total memory allocated to the server or virtual machine)

    2. -XX:CompressedClassSpaceSize=1G

    3. -XX:+UseParallelGC

Setting properties for Windows services via the Windows registry
In some versions of Windows there is no option to add Java variables to the service. In these cases, the properties must be added in the option list in the registry.

To set properties for Windows services via the Windows registry:

  1. Launch the registry editor (Start >> Run >> regedit32.exe).

  2. Find the Services entry:

    32-bit: HKEY_LOCAL_MACHINE >> SOFTWARE >> Apache Software Foundation >> Procrun 2.0 >> <TOMCAT SERVICE NAME >> Parameters >> Java

    64-bit: HKEY_LOCAL_MACHINE >> SOFTWARE >> Wow6432Node >> Apache Software Foundation >> Procrun 2.0 >> <TOMCAT SERVICE NAME >> Parameters >> Java

  3. To change existing properties, especially increasing Xms or Xmx memory, double-click on the appropriate value (respectively JvmMs or JvmMx) and set it to 2048m or more, depending on the memory you want to allocate. Create a new REG_DWORD property if any of the JvmMs or JvmMx do not exist.

    Tip

    We recommend to set a value inferior or equal to 55% of the total memory allocated to the server or virtual machine.

  4. To add additional properties like MaxMetaspaceSize, double-click on options and add a new line with the following values. There is a maximum of one parameter per line. If the option does not exist, create it as a “Multiple String” value.

    1. -XX:MaxMetaspaceSize=512m

      It could be 512m or more.

      Tip

      We recommend to set a value inferior or equal to 15% of the total memory allocated to the server or virtual machine.

    2. -XX:CompressedClassSpaceSize=1G

    3. -XX:+UseParallelGC

Increase server memory allocation on Linux

To increase heap or perm gen space memory in Linux installations:

  1. From path_to_tomcat_directory/bin, open setenv.sh
  2. Find the JAVA_OPTS section and set the following values:

-Xms512m -Xmx2048m -Xmn512m -XX:MaxMetaspaceSize=512m -XX:CompressedClassSpaceSize=1G -XX:+UseParallelGC

You can set higher values depending on the memory you want to allocate.

Tip

However we recommend for Xms, Xmn and MaxMetaspaceSize parameters to set a value inferior or equal to 15% of the total memory allocated to the server or virtual machine. For Xmx, parameter the value should be inferior or equal to 55% of the total memory.

3 Start Tomcat

Warning

This action can take a long time. Check the progress by watching the log files and see if you have any error.

Start Tomcat to start the web application.

Set the iObeya license

You must access the administration interface of your iObeya platform to finalize the installation by providing the license key.

Enter your iObeya server URL in your browser address bar and add “/admin”.

Example: http://<server>:<port>/<context>/admin where:

  • <server> is the hostname or IP address of the Tomcat server,
  • <port> is the Tomcat port for communication (Tomcat default port: 8080),
  • <context> is the name of the context defined. By default iObeya is configured to be accessible as the root application on your server. However, if you changed the context file name ROOT.xml to something else, you need to provide the custom context in the URL. For instance, if you renamed the file ROOT.xml to iobeya.xml, the URL would be http://<server>:<port>/iobeya/admin.

By default, a platform administrator is created: admin (password: admin)

  1. The platform administrator is automatically redirected to the license page.
  2. Note the Server ID and send it by email to our Support team (support@iobeya.com) explaining if this is for your production instance or a preproduction instance. You will rapidly receive your private license key.
  3. Open the license file received from our Support team in a text editor and select all the text.
  4. Copy and paste the license key text from the text editor into the license text zone in the administration interface of your iObeya platform.
  5. Click Save.

The license is immediately active.

Access to the application

Type the server URL into the address bar of a web browser to access the homepage of iObeya.

Example: http://<server>:<port>/<context> where:

  • <server> is the hostname or IP address of the Tomcat server,
  • <port> is the Tomcat port for communication (Tomcat default port: 8080),
  • <context> is the name of the context defined. By default iObeya is configured to be accessible as the root application on your server. However, if you changed the context file name ROOT.xml to something else, you need to provide the custom context in the URL. For instance, if you renamed the file ROOT.xml to iobeya.xml, the URL would be http://<server>:<port>/iobeya.

Step 7: Optional configurations

Configure Tomcat to run on a different port (Optional)

It is possible to change Tomcat’s default ports by editing the server.xml file in the Tomcat’s conf directory.

  1. To change the Tomcat’s ports, open the tomcat_installation_path/conf/server.xml file.

  2. Find the following lines:

    <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />

  3. Change the value of the connector port to a port that is free on the machine, and save the file.

Configure Tomcat to run as a service (Optional)

Configure Tomcat to run as a Windows service

It is possible to run Tomcat as a service by reading the following procedure Windows Service HOW-TO.

Configure Tomcat to run as a Linux service

It is possible to run Tomcat as a service: refer to your Unix distribution documentation.

Running iObeya over HTTPS (Optional)

To secure the access to iObeya with HTTPS (HTTP over SSL), either enable HTTPS connector on Tomcat, or use an Apache HTTPD as a proxy that handles HTTPS connections. SSL encryption is a good way to encrypt iObeya data and user logins to avoid the risk of being intercepted and read during transport.

No modification of iObeya is required when switching to a secure connection. For more details, please refer to: