Manual installation

How to populate metadata database

The metadata database must contains a schema which will collect all Knowage metadata. For configuring such a schema, the user must execute the creation scripts provided for the DBMS in use. The package which includes the DDL will contain the following SQL files:

Listing 3 Scripts for metadata schema
XXX_create.sql
XXX_create_quartz_schema.sql

where XXX represents the DBMS type (as instance ORA stands for Oracle). The corresponding SQL files for deleting tables are also provided.

Using Tomcat

Dependencies

You must add required libraries into TOMCAT_HOME/lib folder:

  • the JDBC connector for the metadata database with its dependencies (if any);
  • the JDBC connector for the business data database with its dependencies (if any);
  • the module which includes the commonj library with its dependencies (if any):

Important

Enterprise Edition only

To enable the Import/Export capability, please also add the JDBC connector for HyperSQLDB , taking care of using version 1.8.0.2 .

File system resources

Create the folder TOMCAT_HOME/resources. Such a folder will contain some useful static resources and the indexes for the search engine used by Knowage.

Metadata database connection

To create a new connection, edit the TOMCAT_HOME/conf/server.xml and add the information related to the metadata database inside the GlobalNamingResources tag. Specify: username, password, driver class name and URL. We need to create two connection:

  • jdbc/knowage: Knowage metadata
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
<Resource auth="Container"
                driverClassName="<JDBC driver>"
                name="jdbc/knowage"
                password="<password>"
                type="javax.sql.DataSource"
                url="<JDBC URL>"
                username="<user name>"
                maxActive="10"
                maxIdle="1"
                validationQuery="<validation query>"
                removeAbandoned="true"
                removeAbandonedTimeout="3600"
                logAbandoned="true"
                testOnReturn="true"
                testWhileIdle="true"
                timeBetweenEvictionRunsMillis="10000"
                minEvictableIdleTimeMillis="60000" />
  • jdbc/ds_cache: Knowage cache, this must be an empty schema
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
 <Resource auth="Container"
                driverClassName="<JDBC driver>"
                name="jdbc/ds_cache"
                password="<password>"
                type="javax.sql.DataSource"
                url="<JDBC URL>"
                username="<user name>"
                maxActive="10"
                maxIdle="1"
                validationQuery="<validation query>"
                removeAbandoned="true"
                removeAbandonedTimeout="3600"
                logAbandoned="true"
                testOnReturn="true"
                testWhileIdle="true"
                timeBetweenEvictionRunsMillis="10000"
                minEvictableIdleTimeMillis="60000" />

Connection to business data

Edit the TOMCAT_HOME/conf/server.xml and add the information related to the metadata database inside the GlobalNamingResources tag, specifying username, password, driver class name and URL.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
 <Resource auth="Container"
                driverClassName="<JDBC driver>"
                name="jdbc/dwh"
                password="<password>"
                type="javax.sql.DataSource"
                url="<JDBC URL>"
                username="<user name>"
                maxWait="-1"
                maxActive="10"
                maxIdle="1"
                validationQuery="<validation query>"
                removeAbandoned="true"
                removeAbandonedTimeout="3600"
                logAbandoned="true"
                testOnReturn="true"
                testWhileIdle="true"
                timeBetweenEvictionRunsMillis="10000"
                minEvictableIdleTimeMillis="60000"
                factory="org.apache.tomcat.jdbc.pool.DataSourceFactory" />

Environment variables definition

Edit the file TOMCAT_HOME/conf/server.xml in Tomcat and add the following constants in the GlobalNamingResources tag, by setting the domain within the host_url value. That domain will be used by the browser to call Knowage server.

Listing 4 Tomcat environment variables configuration.
1
2
3
4
5
<Environment name="resource_path" type="java.lang.String" value="${catalina.home}/resources"/>
<Environment name="sso_class" type="java.lang.String" value="it.eng.spagobi.services.common.JWTSsoService"/>
<Environment name="service_url" type="java.lang.String" value="http://localhost:8080/knowage"/>
<Environment name="host_url" type="java.lang.String" value="<server URL which is hosting knowage>"/>
<Environment name="hmacKey" description="HMAC key" type="java.lang.String" value="<PUT ANY RANDOM STRING HERE>"/>

Such environment variables have the following meaning:

  • resource_path: resources folder path,
  • sso_class:SSO connector class name,
  • service_url:backend services address, typically set to http://localhost:8080/knowage,
  • host_url: frontend services address, the one the user types in his browser,
  • hmacKey: secret key to generate JWT tokens used by the default security mechanism. You must change it, and do not distribute it. You can put any random alphanumeric string in it, and you can change it everytime you want, you just need to restart Tomcat to apply the change.

Important

Again we stress the point that the HMAC key must be a random string. Please DO NOT copy and paste it from this documentation, since this will compromise the security of the application.

Applications deploy

To deploy Knowage you have to copy all the WAR files inside the TOMCAT_HOME/webapps folder. Once the first start is ended each WAR file will be unzipped. It is also possible to unzip the WAR files manually using the unzip utility.

Thread pool defintion

You must configure TOMCAT_HOME/conf/server.xml file and add the settings related to the pool of thread editing the GlobalNamingResources tag, as shown follow.

1
<Resource auth="Container" factory="de.myfoo.commonj.work.FooWorkManagerFactory" maxThreads="5" name="wm/SpagoWorkManager" type="commonj.work.WorkManager"/>

Advanced memory settings

It is recommended to increase the memory dimension used by the application server. This can be done by adjusting some properties. The memory required by each application server depends on many factors: number of users, type of analyses, amount of handled data, etc. The minimum requirements are Xms1024m and Xmx2048m.

[LINUX] Insert at the beginning of the TOMCAT_HOME/bin/setenv.sh file this command:

1
export JAVA_OPTS="$JAVA_OPTS -Xms1024m -Xmx2048m -XX:MaxPermSize=512m"

[WIN] Insert at the beginning of the TOMCAT_HOME/bin/setenv.bat file this command:

1
set JAVA_OPTS= %JAVA_OPTS% -Xms1024m Xmx2048m -XX:MaxPermSize=512m

Configuration of the metadata db dialect

Verify that the right dialect has been set inside hibernate.cfg.xml files. We list all the possible dialects that can be used:

1
2
3
<property name="hibernate.dialect">org.hibernate.dialect.MySQLDialect</property>,
<property name="hibernate.dialect">org.hibernate.dialect.PostgreSQLDialect</property>
<property name="hibernate.dialect">org.hibernate.dialect.Oracle9Dialect</property>

You have to configure these following Hibernate configuration files and set the chosen dialect:

1
2
3
4
5
6
7
8
knowagekpiengine/WEB-INF/classes/hibernate.cfg.xml
knowagegeoreportengine/WEB-INF/classes/hibernate.cfg.xml
knowage/WEB-INF/classes/hsql/hibernate.cfg.xml
knowage/WEB-INF/classes/hibernate.cfg.xml
knowagesvgviewerengine/WEB-INF/classes/hibernate.cfg.xml
knowagemeta/WEB-INF/classes/hibernate.cfg.xml
knowagecockpitengine/WEB-INF/classes/hibernate.cfg.xml
knowagedataminingengine/WEB-INF/classes/hibernate.cfg.xml

Important

Context update

The modification of these files will be effective as soon as the web application is reloaded or the application server is restarted.

Modification of the Quartz configuration

The scheduler is configured in knowage/WEB-INF/classes/quartz.properties. It is essential to enhance in this file the property org.quartz.jobStore.driverDelegateClass with the right value, according to the metadata database in use. Following the possible values:

1
2
3
4
5
6
7
 # Hsqldb delegate class
 #org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.HSQLDBDelegate
 # Mysql delegate class org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.StdJDBCDelegate
 # Postgres delegate class
 #org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
 # Oracle delegate class
 #org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.oracle.OracleDelegate

Clustering

When Knowage is installed in cluster with several nodes, it is necessary to activate the Cluster modality, adding these parameters to the knowage/WEB-INF/classes/quartz.properties file of every involved machines:

1
2
3
4
 org.quartz.jobStore.isClustered = true
 org.quartz.jobStore.clusterCheckinInterval = 20000
 org.quartz.scheduler.instanceId = AUTO
 org.quartz.scheduler.instanceName = RHECMClusteredSchedule

Logging

It is necessary to set up a folder where Knowage and its analytical engines can store their respective log files. From now on, we will call LOG_DIR such folder and LOG_DIR_PATH the path that leads to it. This path is configured in file log4j.properties located inside the \WEB-INF\classes\ available in each web application. Shortly, to configure the Knowage log folder the user must execute the following steps:

  • create the LOG_DIR folder on all cluster nodes on which it is intended to deploy Knowage Server and/or one of its analytical engines. The LOG_DIR_PATH string must be the same for every node;
  • [LINUX] verify that Knowage has write permissions on this folder; set the property log4j.appender.knowage.File inside the WEB-INF/classes/log4j.properties to LOG_DIR_PATH/knowage.log;
  • set the property log4j.appender.knowageXXXXXEngine.File inside the WEB-INF/classes/log4j.properties file of each engine to LOG_DIR_PATH/knwoageXXXXXEngine.log;
  • only for the Birt Engine, to set the property logDirectory inside the WEB-INF/classes/BirtLogConfig.properties file of the knowagebirtreportengine application to LOG_DIR_PATH.