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 scripts folder: contains the SQL scripts for both Oracle 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.

  • 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 modifying the SQL scripts init-iobeya.sql 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 modifying the SQL scripts init-iobeya.sql 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 the installation is upgrading a previous version of iObeya, follow the procedure in the Upgrade Guide.

Warning

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

1 Installation on MySQL or MariaDB

Warning

For security purposes, replace the % wildcard by the application server IP in the following lines of the init-iobeya.sql script:

CREATE USER 'iobeya'@'%' IDENTIFIED BY 'iobeya';
GRANT SELECT,INSERT,UPDATE,DELETE ON iobeya.* TO 'iobeya'@'%';

Replace <database_username> by the username defined during the previous step (default values for <database_username> is iobeya). Replace <database_address> by the IP address or the hostname of your database server.

  1. Configure your database:

    1. Open your MySQL/MariaDB configuration file (my.cnf).

    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

    3. Restart your MySQL or MariaDB server.

  2. Use the init-iobeya.sql script, which will create a new database iobeya and a dedicated user account <database_username>:

    1. Open the command window.

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

    3. Run the following command line with the database root user account. Enter the root password:

      mysql -h <database_adress> -u root -p < init-iobeya.sql

  3. Use the createtables-iobeya.sql script, which will create tables in the iObeya database:

    1. Open the command window.

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

    3. Run the following command line with the database root user account. Enter the root password.

      mysql –h <database_address> –u root –p iobeya < createtables-iobeya.sql

  4. Use the filltables-iobeya-default.sql script, which will initialize default values:

    1. Open the command window.

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

    3. Run the following command line with the <database_username> account. Enter the password (default value is iobeya).

      mysql -h <database_address> -u <database_username> -p iobeya < filltables-iobeya-default.sql

2 Installation on Oracle

Replace <database_username> by the username defined during the configuration process.

  1. Create a new database iobeya and a dedicated user account <database_username> (default iobeya):

    1. Open a terminal window.

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

    3. Execute sqlplus with the SYSTEM user. At the prompt type the SYSTEM password of the database.

    4. On the sqlplus prompt, execute the init-iobeya.sql script using the “@” symbol followed by the complete path to the script file:

      @<install_folder>\oracle\init-iobeya.sql

  2. Execute sqlplus with the <database_username> user (default: iobeya).

  3. Create tables in the database iobeya: on the sqlplus prompt, execute the createtables-iobeya.sql script using the “@” symbol followed by the complete path to the script file:

    @<install_folder>\oracle\createtables-iobeya.sql

  4. Create database triggers: on the sqlplus prompt, execute the create-triggers-iobeya.sql script using the “@” symbol followed by the complete path to the script file:

    @<install_folder>\oracle\create-triggers-iobeya.sql

  5. Initialize default values: on the sqlplus prompt, execute the filltables-iobeya-default.sql script using the “@” symbol followed by the complete path to the script file:

    @<install_folder>\oracle\filltables-iobeya-default.sql

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

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: