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:
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.
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 tohttp://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
|
Datasource link within the applications¶
You would set up ResourceLink for JNDI datasource. To do so, you have to configure each knowage*/META-INF/context.xml
and set the ResourceLink for each JNDI data source previously created. Inside the released packages two links are already defined:
- one for the
jdbc/knowage
resource, which the user must keep - the other for the
jdbc/foodmart
, which should be renamed withjdbc/dwh
.
1 2 3 4 5 6 7 8 9 10 11 | <Context docBase="knowage-ee" path="/knowage" reloadable="true">
<ResourceLink global="jdbc/dwh" name="jdbc/dwh" type="javax.sql.DataSource"/>
<ResourceLink global="jdbc/knowage" name="jdbc/knowage" type="javax.sql.DataSource"/>
<ResourceLink global="jdbc/ds_cache" name="jdbc/ds_cache" type="javax.sql.DataSource"/>
<ResourceLink global="resource_path" name="resource_path" type="java.lang.String" />
<ResourceLink global="sso_class" name="sso_class" type="java.lang.String" />
<ResourceLink name="hmacKey" global="hmacKey" type="java.lang.String"/>
<ResourceLink global="host_url" name="host_url" type="java.lang.String" />
<ResourceLink global="service_url" name="service_url" type="java.lang.String"/>
<ResourceLink global="wm/SpagoWorkManager" name="wm/SpagoWorkManager" type="commonj.work.WorkManager" />
</Context>
|
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.
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. TheLOG_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 theWEB-INF/classes/log4j.properties
toLOG_DIR_PATH/knowage.log
; - set the property
log4j.appender.knowageXXXXXEngine.File
inside theWEB-INF/classes/log4j.properties
file of each engine toLOG_DIR_PATH/knwoageXXXXXEngine.log
; - only for the Birt Engine, to set the property
logDirectory
inside theWEB-INF/classes/BirtLogConfig.properties
file of the knowagebirtreportengine application toLOG_DIR_PATH
.