Installation Guide¶

Getting started¶

iObeya version 4 includes a Server ID licensing management procedure. Contact our Support team (support@iobeya.com) to inform them on when you are planning to perform the installation to get support. They will be able to send you your private licence according to your Server ID.

The main steps for the installation of iObeya are:

Packaging the application, which includes:
1. Creating a package (WAR file containing the application).
2. Configuring the iObeya parameters (paths to logs and data, communication parameters, add-on configurations).
Creating the database used by iObeya and/or generating the scripts to create it manually.
Configuring/Customizing the application server. Creating the directories defined during the packaging process and deploying the configuration files generated by the iObeya packager.

Follow these steps to install iObeya:

STEP 1: Packaging
STEP 2: Initialization of the database
STEP 3: Installation on Tomcat
STEP 4: Final steps
STEP 5: Optional configurations

Step 1 : Packaging¶

The very first step of iObeya installation process is to create a package containing the application and all the configuration files.

Warning

The packager installs neither the prerequisites, nor the application, nor any configuration files on your application server. You must follow the deployment procedure according to your specific application server.
To avoid errors, you must use “/” instead of “\” in all the paths you define, even if you are using Microsoft Windows Server.
The paths given in this documention are for Unix environment. If you are working on a Windows environment, use compatible paths. e.g. D:/iobeya/data
To execute the iObeya packager, you will need to have Java installed.

Note

The packager will not create any directories automatically. We recommend you create them while you define the paths during the packaging process.

Follow the packaging steps:

Double click on the packager JAR file then click Next or execute it using the java -jar <name of the packager>.jar command.
On the prompt that appears, click Next.
Read the license agreement, select I accept the terms of this license agreement to continue, then click on Next.
Select the installation path targeting the directory where the packager will create all the files at the end of this procedure, then click on Next.
You are now on the screen where you have to select what you wish to do:
- iObeya Webapp (mandatory), to generate the package and the configuration files to install iObeya
- Create/Update database, if you want the packager to do it (optional). This option can be used only if you run the packager from a computer that can access the database server that will be used to install iObeya.
  
  Warning
  
  We do not recommend the use of the option Create/Update database if your are working on a production environment.
Choose your database server between MySQL and Oracle, and then click on « Next ».

Note

If you are using MariaDB, select MySQL.
On the next three pages, define some iObeya settings and then click Next:
- The base directory that will be used to store iObeya data by default. This value will be used as a reference if you want to set other directories relative to the base directory. The application server must be able to read and write in all the directories.
- Add-ons configuration directory, which will contain the properties files for the add-ons. The application server must be able to read in this directory.
- Log4j2 file path & file name: the path and the name of the log4j2 file which will define the application logs. The application server must be able to read in this directory.
- Logs files directory: the directory where the log files will be stored. The application server must be able to write in this directory.
Configure the purge retention days (how long deleted elements remain in the database) and the trash retention days (how long deleted elements remain in the trash), then click Next.
iObeya upload settings: define the maximum size (in Bytes) of a file to upload and the maximum height and width (in pixels) of an image. These settings can be used to constrain the use of storage space on the server, and the network bandwidth.
Tomcat settings: define the name of the context, leave the “Use docBase” checked, and define the directory for the DocBase of the application, then click “Next”. The context name parameter defines the context path in the URL to access the iObeya application on the server. By default the application will be accessible at http://yourserver.com/iobeya. To make iObeya the root application of the server accessible at http://yourserver.com, then set the context name parameter to ROOT. On Tomcat, you will manually deploy iObeya as an exploded web application in a directory called docBase. This deployment method gives you more flexibility and control over the application configuration. Write down the full path of the docBase parameter, you will have to extract the content of the WAR file generated by the iObeya packager into this directory later on.
Define the database connection settings:
- Server address (must be accessible from the application server).
- Server port (must be accessible from the application server).
- Database name.
- Username.
- Password.
Note

These settings are stored in the context file for Tomcat.
Click Next.
Optionally, if you have previously selected the option create/update database, you have to define the database administrator username and password that will be used by the packager to create/update your iObeya database. See the specific database documentation for more information.
Wait for the “pack installation progress” to display Finished, and click Quit. The package is now generated.

In the Installation path directory (see Final steps), the packager has created:

A “mysql” folder, containing all the database scripts
A “tomcat” folder, that contains
- A “configuration” folder, containing the context file for Tomcat
- A “Log4j2” folder containing log4j2.xml
- The “iobeya.war” file
The “installconfig.properties” file

Note

The packager generates an installconfig.properties file where you can find all the parameters you defined during these steps. Please refer to this file for next steps if required.

About configuration parameters¶

This section lists the iObeya configuration parameters that can be set during the packaging process.

These parameters are stored in the context file generated by the packager. It is possible to modify these parameters later by editing the context file.

Note

We recommend using the following directories instead of default directories.

assetStorage (mandatory): defines how the assets (images) will be stored.
- filesystem: the images are stored in a folder on the server. Recommended for good performance, but needs to be backed up separately from the database.
assetDirectory (mandatory): defines the directory where the assets (images) will be stored. Can be relative to dataDirectory.
- e.g. /var/iobeya/data/assets
- e.g. assets
indexDirectory (mandatory): defines the directory where the indexes will be stored. Can be relative to dataDirectory.
- e.g. /var/iobeya/data/index
- e.g. index
useIndex (mandatory): Indexes are used to speed up some searches in iObeya. It is higly recommended to set it to true.
- true or false
scimSearchStrategy (optional): changes the search strategy used
- criteria: uses a strategy with database queries
- client: everything is calculated on the client, which is likely not powerful enough if you have to manage a large number of users.
baseDirectory (mandatory): A root directory that can be used as a reference for other directories.
- e.g. /var/iobeya
cacheDirectory (mandatory): defines the directory where all the cache files generated by the application will be stored. Can be relative to baseDirectory. This directory can be emptied when restarting the application.
- e.g. /var/iobeya/cache
- e.g. cache
dataDirectory (mandatory): defines the directory where all the files managed by the application will be stored. Can be relative to baseDirectory.
- e.g. /var/iobeya/data
- e.g. data
tempDirectory (mandatory): defines the directory where all the temporary files managed by the application will be stored. Can be relative to baseDirectory. This directory can be emptied when restarting the application.
- e.g. /var/iobeya/temp
- e.g. temp
hotDeployPollingFrequency (optional): determines the frequency, in seconds, at which the add-ons directory is scanned for new add-ons to be deployed.
- Default value is 60 (i.e. 1 minute).
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
chunkTempFolder (optional): folder used to temporary store files during upload. If this parameter is not defined, the chunked-temp subfolder from tempDirectory will be used by default.
- e.g. /var/iobeya/temp/chunked-temp
uploadTempDirectory (optional): folder used to temporarily store files during import. If this parameter is not defined, the upload_temp subfolder from tempDirectory will be used by default.
- e.g. /var/iobeya/temp/upload_temp
OSGICacheDirectory (optional): folder used for caching add-ons. If this parameter is not defined, the osgi-cache subfolder from cacheDirectory will be used by default.
- e.g. /var/iobeya/cache/osgi-cache
pluginsDirectory (optional): Folder used for storing add-ons. If this parameter is not defined, the add-ons subfolder from dataDirectory will be used by default.
- e.g. /var/iobeya/data/plugins
bundledPluginsDirectory (optional): folder used for storing default add-ons. If this parameter is not defined, the bundled-plugins subfolder from cacheDirectory will be used by default.
- e.g. /var/iobeya/cache/bundled-plugins
maxUploadSize (optional): determines the maximum file size, in bytes, for uploads to the application (example: board images, board backgrounds,..).
- Default value is: 10485760 (i.e. 10 MB).
maxUploadHeight (optional): determines the maximum allowable height of an image to be uploaded, in pixels.
- Default value is: 7560 pixels.
maxUploadWidth (optional): determines the maximum allowable width of an image to be uploaded, in pixels.
- Default value is: 7560 pixels.
assetCacheSizeLimit (optional): determines the maximum allowable size of an asset to be put in memory cache, in bytes.
- Default value is: 1048576 (i.e. 1 MB).
minScreenshotDelay (optional): used to define the minimum time (in milliseconds) between two screenshot generations for the same board.
- Default value is 60000 ms (i.e. 1 minute).
minScreenshotIdleTime (optional): used to define the delay (in milliseconds) without board content modification, before screenshot generation begins.
- Default value is 5000 ms (i.e. 5 seconds).
screenshotStripeSizePixel (optional): defines the size, in pixels, of strips used for PNG screenshot generation. This parameter can be used to reduce memory consumption while increasing the speed of screenshot generation, as well as the size of generated screenshot. The memory consumed per screenshot is 4x the value of this parameter. Using the maximum value of 38000000 pixels will yield the fastest completion speed, at the cost of 150 MB. The default value is set to 16 MB of memory use, but this can reduce the speed to 7x slower than the previously mentioned maximum value.
- Default value is 83886080 (i.e 8 Megapixels).
pollingInterval (optional): defines how long (in milliseconds) a connection remains open until a message is available.
- 20000 ms (i.e. 20 seconds).
clientWaitInterval (optional): defines how long (in milliseconds) the client waits before it reconnects to read a new message. This reduces the server load by adding latency.
- 0 ms.
clientTimeout (optional): defines how long (in milliseconds) a client not connected (ie: network issue) is considered as “disconnected” by the server.
- 120000 ms (i.e. 2 minutes).
timeToLive (optional): Default lifetime of a message (in milliseconds).
- 240000 ms (i.e. 4 minutes).
clientIdleTimeout (optional): Idle time (in milliseconds) beyond which the client will be automatically disconnected. This measure can reduce the server load by disconnecting inactive users while increasing security by logging out idle terminals. Increase the value of this parameter if you want the sessions to remain active all day long.
- 25200000 ms (i.e. 7 hours)
trashRetentiondays (optional): determines how many days deleted elements are stored and visible in the virtual trash bin in the virtual room. e.g. a value of “2” means that elements that have been in the trash for 2 days or more will be removed from the virtual trash bin. These elements will then be definitively deleted depending on the value of purgeRetentiondays.
- Default value is 1 day.
purgeRetentiondays (optional): determines how many days deleted resources are stored on the platform. e.g. a value of “7” means that elements that have been in the trash for 7 days or more will be definitively removed from the platform when the next purge action occurs.
- Default value is 7 days.
unknownRoomsInHome (optional): determines if public rooms are displayed on the navigation bar. For a large instance with a lot of public rooms, this parameter can provide better performance during the loading of rooms, if it is set to false.
- Default value is true.
allowIFrame (optional): determines if iObeya should be allowed to be displayed in an iFrame or not. Setting this option to “true” will allow session cookies to be set as third party and thus allow iObeya authentication in an iFrame.
- Default value is false.

Note

Since version 3.7 the only value possible for asset storage is “filesystem”. Every asset stored in the database will be copied to the assetDirectory when the IntegrityCheckTask job will be run.
Purge scheduling is configured in the Jobs section in the iObeya administration interface. See Jobs section of the Administrator guide for more details.

Step 2: Database initialization¶

Warning

If the option was chosen to let the packager create the database, you can skip this step and follow STEP 3.

Note

If the installation is upgrading a previous version of iObeya, follow the procedure in the upgrade guide section of the 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 reasons, 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_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.

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/MariaDB server
Use the init-iobeya.sql script, which will create a new database <database_name> and a dedicated user account <database_username>
1. Open the command window.
2. Go into the <install_folder>mysqldbscripts directory of the installation package.
3. Run the following command line with the database root user account. Enter the password.
```
mysql -h <database_adress> -u root -p < init-iobeya.sql
```
Create tables in the iObeya database:
1. Open the command window.
2. Go into the <install_folder>mysqldbscripts directory of the installation package.
3. Run the following command line with the database root user account. Enter the password.
mysql –h <database_address> –u root –p <database_name> < createtables-iobeya.sql
Initialize default values:
1. Open the command window.
2. Go into the <install_folder>mysqldbscripts directory of the installation package.
3. Run the following command line with the database user account <database_username>. Enter the password.
mysql -h <database_address> -u <database_username> -p <database_name> < filltables-iobeya-default.sql

2 Installation on Oracle¶

Replace <database_name> and <database_username> by the name and the user name defined during packaging.

Create a new database <database_name> (default iobeya) and a dedicated user account <database_username> (default iobeya):
1. Open a terminal window.
2. Go into the <install>/oracle/dbscripts 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>\oracle\dbscripts\init-iobeya.sql
Note

For the next steps, execute sqlplus with the iObeya user.
Create tables in the database <database_name>: on the sqlplus prompt, execute the createtables-iobeya.sql script using the @ symbol followed by the complete path to the script file:
@<install>\oracle\dbscripts\createtables-iobeya.sql
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>\oracle\dbscripts\create-triggers-iobeya.sql
```
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>\dbscripts\filltables-iobeya-default.sql
```

Step 3: Installation on Tomcat¶

1 Upload the iObeya installation directory¶

Connect to the server with the user account used to run Tomcat.
Verify that the directory generated by the packager contains the following content:
1. tomcat folder with:
  1. configuration contains the context file for tomcat: iobeya.xml by default.
  2. log4j2 contains the log4j2.xml file.
  3. iobeya.war the iObeya WAR file.
Upload the folder generated by the packager to the server. This folder will be referred to as <install folder> for this procedure description.

2 Deploy the iObeya Webapp in Tomcat¶

Tomcat directory¶

Put the 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. If the XML context file is named iobeya.xml, then the iObeya application will be accessible at http://yourserver.com/iobeya. To make iObeya the root application of the server (http://yourserver.com), then rename the iobeya.xml file to ROOT.xml.
Copy the JDBC drivers into the Tomcat lib directory.
- For Oracle: http://www.oracle.com/technetwork/database/features/jdbc/default-2280470.html
- For MySQl/MariaDB: https://dev.mysql.com/downloads/connector/j/

iObeya webapp directory¶

All the parameters and paths have been defined during the packaging. They can be found in the installconfig.properties file in the <intall_folder>.

Verify that the DocBase directory that was defined exists.
Unzip the iobeya.war into this folder.
Verify that the defined Log4J2 directory directory exists.
Copy the log4j2.xml file into this folder.
Verify that the defined data directory exists.
Verify that the defined temp directory exists.
Verify that the defined cache directory exists.
Verify that the defined assets directory exists.
Verify that the defined index directory exists.
Verify that the defined logs directory exists.

Warning

If the directories above do not exist, you need to create them in the designated folders.

Step 4: Final steps¶

There are final steps to go through with different procedures to follow, specific to the environment being used to install iObeya:

Windows
Linux

1 Install 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:

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

Install fonts on Linux¶

For non-European character sets, 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 binary (ttf): liberation-fonts-ttf-1.07.4.tar.gz).
2. Un-tar 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:

Download the font available here:

https://github.com/MorbZ/OpenSansEmoji/raw/master/OpenSansEmoji.ttf.

Add the font in the folder:

/usr/share/fonts

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, which it makes 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 - unfortunately, this amount is inadequate for standard iObeya installations so this 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

Identify the name of the service that Tomcat is installed under in

Windows. From Control Panel ‣ Administrative Tools ‣ Services (for example: Tomcat8).

Open the command window.
Go into the /bin directory of the Tomcat installation.
Run the following command for Tomcat 8.X:
```
Tomcat8w //ES//Tomcat8
```
Click on the Java tab to see the list of current start-up options.
Set the maximum memory allocation to 2048m or more, depending on the memory you want to allocate. We recommend to not set a value higher than 55% of the total memory allocated to the machine or virtual machine.
Also add to the java options section the following parameters:
1. -XX:MaxMetaspaceSize=512m (We recommend to not set a value higher than 15% of the total memory allocated to the machine 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 by viewing the option list in the registry.

To set properties for Windows services via the Windows registry:

Launch the registry editor (Start >> Run >> regedit32.exe).
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
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. We recommend to not set a value higher than 55% of the total memory allocated to the machine or virtual machine. Create a new REG_DWORD property if any of the JvmMs or JvmMx do not exist.
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. We recommend to not set a value higher than 15% of the total memory allocated to the machine 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:

From path_to_tomcat_directory/bin, open setenv.sh
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 depending on the memory you want to allocate. However we recommend for Xms, Xmn and MaxMetaspaceSize parameters to not set a value higher than 15% of the total memory allocated to the machine or virtual machine. For Xmx parameter the value should not be higher than 55% of the total memory.

3 Start Tomcat¶

Warning

This action can take a long time. Check the progress and 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 licence key.

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

Example: http://<server>:<port>/<context>/admin where <server> is the address of the Tomcat server, <port> is the Tomcat port for communication (Tomcat default port: 8080) and <context> is the name of the context defined (default is iobeya, if you change the context file name to ROOT.xml, then there is no context to specify).

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

Once there, the platform administrator is automatically redirected to the license page.
Note the Server ID and send it by email to our Support team (support@iobeya.com). You will then rapidly receive your private license key.
Open the license file you had received in a text editor, then select all the text.
Copy and paste the license key text from the text editor into the license text zone in the administration interface of your iObeya platform.
Click on Save.
The license becomes active immediately.

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 address of the Tomcat server, <port> is the Tomcat port for communication (Tomcat default port: 8080) and <context> is the name of the context defined (default is iobeya, if you change the context file name to ROOT.xml, then there is no context to specify).

Step 5: 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.

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

Find the following lines:

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

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:

https://tomcat.apache.org/tomcat-8.5-doc/ssl-howto.html

http://httpd.apache.org/docs/current/mod/mod_proxy.html