Step 3: Extracting and configuring the webapp

Warning:

• To avoid deployment errors, you need to 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 does 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. You 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 to configure the paths where to store the application logs,

• the ROOT.xml context file: allows 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:

1. Edit the log4j2.xml file.

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

1. Edit the ROOT.xml context file.

2. 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 can 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 create a database schema named iobeya. You can change this value: edit this attribute in the url and specify the Liquibase command line arguments accordingly, or manually creating the database schema in your database server.

     • MySQL: url =”jdbc:mysql://localhost:3306/iobeya?autoReconnectForPools=true”

     • MariaDB: url=”jdbc:mariadb://localhost:3306/iobeya?autoReconnectForPools=true”

     • Oracle: url=”jdbc:oracle:thin:@//localhost:1521/orcl”

   • username (mandatory): By default, the SQL scripts create a new user iobeya to access the database.

     You can change this value: edit this attribute in the context file and specify 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: edit this attribute in the context file and specify 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

Learn how to create the different directories that are 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 you can use 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 are 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 are stored.

   • e.g. /var/iobeya/data

5. Create the Asset directory (mandatory): defines the directory where the assets (e.g. images) are stored.

   • e.g. /var/iobeya/assets

6. Create the Index directory (mandatory): defines the directory where the indexes are 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 do not start.

   • e.g. /var/iobeya/settings/plugins

8. Create the Logs directory (mandatory): defines the directory that stores the application logs of iObeya.

   • e.g. /var/iobeya/logs

You 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 need to 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 does 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:

1. Edit the ROOT.xml context file.

2. Configure the following attributes:

   • docBase (mandatory): on Tomcat, you manually deploy iObeya as an exploded web application in a directory called docBase.

     You need 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 you can use as a reference for other directories.

     • e.g. /var/iobeya/

   • dataDirectory (mandatory): defines the directory where all the files managed by the application are stored.

     • e.g. /var/iobeya/data

   • tempDirectory (mandatory): defines the directory where all the temporary files managed by the application are stored.

     • e.g. /var/iobeya/temp

   • cacheDirectory (mandatory): defines the directory where all the cache files generated by the application are stored.

     • e.g. /var/iobeya/data/cache

   • assetDirectory (mandatory): defines the directory where the assets (e.g. images) are stored.

     • e.g. /var/iobeya/assets

   • indexDirectory (mandatory):defines the directory where the indexes are 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 do not start.

     • e.g. /var/iobeya/settings/plugins