KB 2.9.0 manual installation

  • Last updated on January 9, 2025 at 10:44 AM

This documentation explains the operations to manually install KB from version 2.9.0.

In this documentation :


Prepare

  • Unzip the KB distribution archive into the directory of your choice. In the rest of this documentation, we will refer to this directory as $KB_bundle

You will get the following directory structure :

> $KB_bundle 
    > admin_scripts
    > apache-tomcat-9.0.84
    > elasticsearch-6.8.23
    > neo4j-community-3.5.35
  • Create a user that will run all applications, for instance ‘kb’
  • Update the maximum number open files for this user : as root, edit /etc/security/limits.conf
    kb - nofile 65536

    For Ubuntu only : as root, edit /etc/pam.d/su and uncomment the following line :
    #session required pam_limits.so
  • Note that these ports (by default) will be used by the components of KB :
    • 7474 and 7687 for Neo4j (internal use, no public access needed)
    • 9200 and 9300 for Elasticsearch (internal use, no public access needed)
    • 8005, 8009 and 8080 for Tomcat
  • Since KB 2.9.0, integration with Keycloak is required in order to secure the access to data-modifying endpoints. You will need the Keycloak URL in order to complete the configuration of Tomcat.


Install Neo4j

Neo4j default ports are 7474 (for HTTP) and 7687 (BOLT port for internal API access). If you need to change this, as kb, edit $KB_bundle/neo4j-community-3.5.35/conf/neo4j.conf
– Update the line dbms.connector.http.listen_address=:7474 with the right port for HTTP
– Update the line dbms.connector.bolt.listen_address=:7687 with the right port for BOLT (API)

Neo4j scripts rely on a JAVA_HOME environment variable that should point to a Java 11 JRE (or JDK) :

  • If JAVA_HOME environment variable does not exist, create it, and set it to your Java 11 installation
  • If your JAVA_HOME is already set to another version, and you do not want to change it, you can modify Neo4j scripts :
    – as kb : edit $KB_bundle/neo4j-community-3.5.35/bin/setenv.sh
    – uncomment the JAVA_HOME variable and set the path to your installation of Java 11

In this bundle, we have set up Neo4j memory options in $KB_bundle/neo4j-community-3.5.35/conf/neo4j.conf to be the following :
dbms.memory.heap.initial_size=2g
dbms.memory.heap.max_size=2g
dbms.memory.pagecache.size=1g

If you want to allocate more memory to Neo4j, make sure to set appropriate values by refering to the detailed instructions at https://neo4j.com/docs/operations-manual/3.5/performance/memory-configuration/

Give execution rights on all the scripts to the kb OS user

cd {$KB_bundle}/neo4j-community-3.5.35/bin
chmod u+x *

Initialize the password for Neo4j’s default user whose name is “neo4j” :

cd {$KB_bundle}/neo4j-community-3.5.35/bin
./init_password.sh

You should get the following message on the console :

Changed password for user 'neo4j'.

Now let’s start Neo4j server , as kb OS user,

cd {$KB_bundle}/neo4j-community-3.5.35/bin
./neo4j start

You should get the following message on the console :

Starting Neo4j.
Started neo4j (pid 25220). It is available at http://0.0.0.0:7474/
 There may be a short delay until the server is ready.
 See /home/neo4j/neo4j-community-3.5.35/logs/neo4j.log for current status.

Neo4j ‘s configuration is now finished.

For more information about Neo4j installation, you can check : https://neo4j.com/docs/operations-manual/current/installation/linux/tarball/


Install Elasticsearch

Similarly to Neo4j, ElasticSearch scripts rely on a JAVA_HOME environment variable that should point to a Java 11 JRE (or JDK)

  • If you have configured your JAVA_HOME to point to Java 11 JRE, then you’re fine for this step
  • If your JAVA_HOME is already set to another version, and you do not want to change it, you can modify ElasticSearch scripts :
    – as kb user, edit $KB_bundle/elasticsearch-6.8.23/bin/elasticsearch-env
    – add the JAVA_HOME variable and set the path to your Java 11 installation at the beginning of your file. For example :
(...)
ES_CLASSPATH="$ES_HOME/lib/*"

# now set the path to java
# ADD THE FOLLOWING LINE TO DEFINE JAVA_HOME
JAVA_HOME="/usr/lib/jvm/java-11-openjdk-amd64"
 
if [ -x "$JAVA_HOME/bin/java" ]; then
  JAVA="$JAVA_HOME/bin/java"
(...)


Elasticsearch default ports are by default 9200 (for HTTP) and 9300 (for API). If you need to change this :
As kb user, edit $KB_bundle/elasticsearch-6.8.23/config/elasticsearch.yml
– Edit the http.port property, and replace 9200 with the correct port
– Edit the transport.tcp.port property, and replace 9300 with the correct port

In this bundle, we have set up ES JVM options with 2Gb. You can adjust this by edit the file in $KB_bundle/elasticsearch-6.8.23/config/jvm.options

Give execution rights on the scripts to the kb user :

cd {$KB_bundle}/elasticsearch-6.8.23/bin
chmod u+x *

In order to support extended Unicode features, we need to install the ICU plugin. This operation will require access to the internet :

cd {$KB_bundle}/elasticsearch-6.8.23/bin
./elasticsearch-plugin install analysis-icu

Without access to the Internet, you can download the plugin manually from https://artifacts.elastic.co/downloads/elasticsearch-plugins/analysis-icu/analysis-icu-6.8.23.zip. and perform an offline install.

For instance, if the path to the zip you downloaded is /home/kb/ analysis-icu-6.8.23.zip, then your commands to install should be the following:

cd {$KB_bundle}/elasticsearch-6.8.23/bin
./elasticsearch-plugin install file:///home/kb/analysis-icu-6.8.23.zip

Now let’s start Elasticsearch server, as kb user:

cd {$KB_bundle}/elasticsearch-6.8.23/bin
./elasticsearch  -d -p pid

Elasticsearch’s configuration is now finished.


Configure Keycloak

  1. Create a new client called "kb-cli" in Keycloak, with Service Account setting. You can copy the settings from the existing client kb-ui :


kb-cli settings

 


 In the Authentication flow: check "Service accounts roles"

 

In the Credentials tab, pick "Client Id and Secret" and generate a secret. Copy the secret, to be used later in this procedure.

Save the kb-cli client.

Install Tomcat


Similarly to Neo4j and Elasticsearch, Tomcat scripts rely on a JAVA_HOME environment variable that should point to your Java 11 JRE.

If you have configured your JAVA_HOME to point to Java 11 JRE, then you’re fine for this step.

If your JAVA_HOME is already set to another version, and you do not want to change it, you can modify Tomcat scripts :

  • as kb user, edit $KB_bundle/apache-tomcat-9.0.84/bin/setenv.sh
  • uncomment the JAVA_HOME variable and set the correct path to your Java 11 installation

We have set up Tomcat memory options in $KB_bundle/apache-tomcat-9.0.84/bin/setenv.sh to be the following :

-Xms2048m
-Xmx2048m

Edit these values if you want to allocate more memory to Tomcat.


Tomcat by default needs the port 8080, 8005 and 8009 to run. If you need to change this, edit $KB_bundle/apache-tomcat-9.0.84/conf/server.xml , as kb user :

  • replace the HTTP port 8080 in the line <Connector port= “8080” protocol= “HTTP/1.1″‘>
  • replace the SHUTDOWN port 8005 in the line <Server port=”8005″ shutdown=”SHUTDOWN”>
  • replace the AJP port 8009 in the line <Connector port=”8009″ protocol=”AJP/1.3″ redirectPort=”8443″>

To configure the integration with Keycloak, edit $KB_bundle/apache-tomcat-9.0.84/bin/setenv.sh  once again, and set the URL to keycloak :

 ...
#URL to Keycloak
export CATALINA_OPTS="$CATALINA_OPTS -Dkeycloak.auth-server-url=https://YOUR_KEYCLOAK_SERVER_DNS/auth" 
...


You can also check the other variables that can be adjusted in this setenv.sh file :

  • logging.level.com.mondeca. Java system property to set the log level. Possible values are : {TRACE, DEBUG, INFO(default), WARN, ERROR,FATAL}
  • kb.security.basic: Java system property to activate authentication with a login. Possible values are :
    • false: users will have to authenticate through a login page to enter the portal (default)
    • true: only the endpoints modifying the data need authentication
  • DOCBASE_DIR: environment variable to set the directory for static files served by Tomcat. Default is '/home/kb/KB-distribution/static/'
  • CONTEXT_PATH : environment variable to set the URL path to reach the static files. Default is '/resources'
  • KB_REMOTE_CSS_URL: environment variable to set the URL to an external CSS files that will be taken into account by the KB UI. The file must of course be accessible from the KB portal. For example : 
KB_REMOTE_CSS_URL="https://example.com/kb/styles/custom-kb-styles.css"


Finally, give execution rights on the scripts to the kb user :

cd {$KB_bundle}/apache-tomcat-9.0.84/bin
chmod u+x *

Now start Tomcat, as kb user :

cd {$KB_bundle}/apache-tomcat-9.0.84/bin
./startup.sh

The Knowledge Browser should be now up and running, BUT without any repository or data to serve.

You can now check this documentation describing how to load data into KB.



Advanced configuration

Serving static files with Tomcat

Tomcat allows serving static files stored in a specific directory (and its subdirectories) on the host.

Our Tomcat bundle for KB is pre-configured to serve files located in the directory {$KB_bundle}/static/. These files are then accessible at the URL <KB>/resources/<path_to_file>.

It is possible to adjust the configuration to serve files from a different directory and to have a different URL path to access them.

To do this, modify the file {$KB_bundle}/apache-tomcat-9.0.84/bin/setenv.sh and update the following environment variables:

  • DOCBASE_DIR: Environment variable to set the directory where static files are served by Tomcat. The directory must exist; otherwise, Tomcat will not start.  
  • CONTEXT_PATH: Environment variable to set the URL path to access the static files. 


Was this article helpful?

Visit our website