KOP Monolithic Installation Guide

This guide will explain how to install the monolithic version of Kiuwan On-Premises. 
 

System Architecture Overview

Kiuwan On-Premises (KOP) is based on a client-server architecture with the following major server components:

• WildFly application server
• MySQL database
• Redis in-memory datastore

KOP solution is deployed on a centralized server (all the components are installed in the same host) and accessed by users via HTTP website access or by IDE plugins (Eclipse, Visual Studio).

KOP also supports distributed architecture with high availability and load-balancing. For these scenarios, please contact Kiuwan support.

Server Host Requirements

Installation requirements

The Kiuwan On-Premises (KOP)  solution is deployed on a centralized server host (all the components are installed in the same host) and accessed by users via HTTP or by IDE plugins (Eclipse, Visual Studio).

KOP installation process consists of building a Docker image.

The installation must be executed by a Unix user with privileges to execute docker server commands.

During the installation process, you will need to specify a KOP UNIX user and group :

• KOP user will be the owner of the KOP processes that will run within the docker container
• the docker persistent volume will be owned by KOP user

KOP User and Group are specified during the KOP Installation process as KIUWAN_USER and KIUWAN_GROUP properties

You can create a KOP user and group by executing the following commands (no special privileges are needed):

• sudo groupadd ${KIUWAN_GROUP}
• sudo useradd -g ${KIUWAN_GROUP} -s /bin/false -m -d /home/${KIUWAN_USER} ${KIUWAN_USER}

KOP Persistent Volume is created by the installation process and must be specified as DIR_PERSISTENT_VOLUME property

$ docker info | grep "Supports d_type:"
Supports d_type: true

$ xfs_info /docker-mount-point | grep ftype 
naming =version 2         bsize=4096      ascii-ci=0     ftype=1

 mkfs.xfs -n ftype=1 /mount-point

CPU and memory requirements

 Server CPU and memory requirements depend on several factors:

• how many lines of code will need to be scanned
• how many analyses will need to be executed in parallel
• how many users will access the web application

Above factors heavily influence host server requirements, but the  minimum requirements are:

Note: CPU clock speed and disk speed will affect overall response time. 

The above configuration is recommended for a system load that requires continuous service for:

• Parallel execution of 2 analyses (any additional parallel analysis request will be enqueued, and it will be executed as soon as any of the running analyses finishes), and
• 50 concurrent web-users

Additional system requirements can be met by following the next recommendations:

• In case you need a higher number of parallel analyses executions, you should add 1 CPU core and 512 Mb for any additional required parallel analysis
• In case you need to improve response time to web users, consider adding 1 GB for every 50 additional web users.

Dependencies

KOP docker image is built based on these external dependencies

Installation steps

Before installing KOP, make sure that you understand the System Architecture Overview, that your server host(s) complies with the Server Host Requirements, and that you have properly prepared the Environment as follows:

Step 1: Download and unpackage KOP Installation Package

Step 2: Configure Kiuwan Docker image

KOP Deployment scenarios

Before installing KOP, you should decide your KOP deployment scenario. 

Below picture displays these different scenarios

Scenario 1 - Direct connection to KOP server

First, you should decide on the external URL that KOP clients will use. By KOP clients, we mean Browsers, Kiuwan Local Analyzer, Kiuwan for Developers, and API-REST clients.

To configure your KOP in this scenario, please follow the next steps

Scenario 1.1 - Direct KOP access through HTTP

Your URL will be something like http://mykop.mydomain.com:7080/saas

You must configure below properties:

Scenario 1.2 - Direct KOP access through HTTPS

Your URL will be something like https://mykop.mydomain.com:7080/saas

Procedure :

1. First, create the image as HTTP using 1.1 HTTP scenario configuration (PremisesInstallationGuide-Scenario1.1-DirectKOPaccessthroughHTTP)
2. Once the image is built, convert it to HTTPS following steps described in Premises Installation Guide -Step 5. (Optional) Making Kiuwan On Premise running on HTTPS

Step 3: Build the Kiuwan Docker image

cd $KOP_INSTDIR/master.YYYYMMDDHHMM.buildnumber
./create_and_init_kop.sh

After the image creation, you will be able to list the images in your docker server and identify your kiuwan image by issuing the next command:

docker images

Step 3.1 (Optional) Moving the image to another server host

After creating the image, if you want to move it to another host server you first must save it to a tarball by executing: 

docker save kop:v1.2 > kop_v12_saved_image.tar 

docker load --input kop_v12_saved_image.tar 

run_kop.sh 

run_init_kop.sh 

     docker stop <my_container_name>

Step 4.1 Execution in debug mode (only sshd) 

Just in case you are running with problems while executing the Kiuwan container, you can run it in debug mode.

This means to apply the configuration but not starting the services, allowing you to access the container through SSH.

docker run --rm --name <my_container_name> \
-h <my_container_host_name> \
-v <server_host_mount_dir:container_mount_dir> \
-p <ssh_port_ext>:22 \
-d \
<image_name:version>

Step 5: Making Kiuwan On-Premises run on HTTPS (Optional)

 If you need to execute Kiwuan On-Premises over HTTPS protocol, please follow the next steps. 

Step 5.1 Create your KOP SSL configuration file

SSL configuration  is currently done by creating a configuration file (ssl.custom) within ssl directory 

There's a file (ssl.tpl) you can use as a template to configure your settings.

1. cd ssl
2. Create ssl.custom file by copying the template file
   • cp ssl.tpl ssl.custom
3. Edit the properties of ssl.custom file and change default values

Step 5.2 Create the Private key and Certificate Signing Request (CSR) for your server

1. Within SSL directory execute the script CreateKey_and_ReqCSR.sh
2. This script generates the CSR file under ssl/certs
   • That file is named <yourhost.yourdomain.com>.csr, according to  $KIUWAN_HOST configuration property
3. Send CSR file to your CA (Certificate Authority)
4. CA will send back to you two files:
   • CA's Certificate file (IMPORTANT: rename it to ca.crt )
   • Your host's Certificate file: for example yourhost.yourdomain.com.crt
5. Copy received files to ssl/certs directory

Step 5.3 Create the Keystore and switch from HTTP to HTTPS

1. Within SSL directory execute the script TransferFilesToContainer.sh
   • This script transfers your server's certificate, your private key and CA's certificate to KOP container
   • Also, it transfers the script templates that will be used to create the keystore and to change the configuration from http to https
2. Within SSL directory execute the script run_create_Keystore.sh
   • This script executes (into the container) the script create_Keystore.sh (created from template create_Keystore.tpl)
3. Within ssl directory execute the script run_change_ToHTTPS.sh
   • This script stops wildfly service and executes the script change_ToHTTPS.sh (created from template change_ToHTTPS.tpl), this script will create files with .rollback extension of modified ones
   • Then, it starts wildfly service 

Step 5.4 Just in case you are using your own CA, make it valid to your browsers and Java 

If the certificate is signed by your own Certification Authority, the browsers will not recognize it as a valid CA and you will get an error messages such as:

Your connection is not private
Attackers might be trying to steal your information from youthost.yourdomain.com (for example, passwords, messages, or credit cards).

NET::ERR_CERT_AUTHORITY_INVALID

To solve this issue, you have to import your CA Certificate into your browser : 

• In Chrome: Configuration >> Settings >> Advanced >> Manage certificates >>  Import (ca.crt) into "Trusted root certification entity store"

Log in to the KOP container and execute the next commands:

1. cd /opt/jdk*/jre/lib/security/
2. supervisorctl stop wildfly
3. cp cacerts cacerts.bck.original
4. keytool -import -noprompt -alias root -keystore cacerts -trustcacerts -file /<kiuwan_vol>/configurations/ssl/ca.crt -storepass changeitsupervisorctl start wildfly
   • NOTE: change <kiuwan_vol> to the value of $KIUWAN_VOL (as configured in settings.custom) 

Then, log in to your Docker server and make the above changes persistent (i.e. to keep them after rebooting the container):

1. docker commit <kop docker name> <kop docker image>
   • NOTE: run 'docker ps' to get NAMES and IMAGE values of your KOP container

Rollback to HTTP

Advanced Configuration

As above specified, the settings.custom file allows you to specify most (but not all) configuration parameters.

Appendix 1 - Configuring Apache as FrontEnd WebServer to KOP

If you choose the Apache web server as the front-end for your Kiuwan On-Premises installation, you may follow the following configuration examples and/or check your current configuration agrees with the suggested examples.

HTTP Protocol

For this kind of access, you just need to add a virtual host and configure how Apache will talk to Kiuwan.

Before this, make sure your Apache installation has these modules available:

• mod_proxy
• mod_proxy_ajp (if you want AJP communication between front and backend servers)
• mod_proxy_http (if you want AJP communication between front and backend servers)
• mod_proxy_wstunnel

To add a virtual host for Kiuwan On-Premises, you can add a file in your Apache installation folder (i.e. /etc/apache2/sites-available/kop.conf) with the following content. Make sure you replace the variables put inside brackets for those you previously configured when installing your Kiuwan On-Premises instance, and a protocol is set (choose between AJP or HTTP) in the ProxyPass directives:

<VirtualHost *:[KIUWAN_WEBSERVER_PORT]>
ServerName [KIUWAN_WEBSERVER_HOST]
ServerAdmin webmaster@localhost
DocumentRoot /var/www/html


LogLevel debug
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined


ProxyRequests Off
ProxyPreserveHost On
<Proxy *>
Require all granted 
</Proxy>


ProxyPass       /   [ajp|http]://[KIUWAN_HOST]:[KIUWAN_PORT]/
ProxyPassReverse    /   [ajp|http]://[KIUWAN_HOST]:[KIUWAN_PORT]/

<Location />
Require all granted
</Location>
</VirtualHost>

HTTPS Protocol

For this kind of access you will need:

• A virtual host configured in Apache will talk to Kiuwan (see below).
• Open an https port in Apache (usually 443).
• A certificate for the exposed hostname (KIUWAN_WEBSERVER_HOST).

Before this make sure your Apache installation has these modules available:

• mod_proxy
• mod_proxy_ajp (if you want ajp communication between front and backend servers)
• mod_proxy_http (if you want ajp communication between front and backend servers)
• mod_proxy_wstunnel
• mod_rewrite
• mod_ssl

Please make sure you generate a certificate for your Kiuwan hostname and that it is signed by a trusted CA inside your organization. At this point, you need three files:

• [KIUWAN_WEBSERVER_HOST].crt: the certificate for your kiuwan host.
• [KIUWAN_WEBSERVER_HOST].key: the private key.
• ca.crt: the trusted CA certificate.

Refer to PremisesInstallationGuide Step 5.2 Create the Private key and Certificate Signing Request (CSR) for your serverfor more information on how to create and install certificates.

Please note that you must install the CA certificate on the docker container before proceeding.

Place the previous files at these locations (we put here the default locations for these files, but it is up to you to change these paths):

• /etc/ssl/certs/[KIUWAN_WEBSERVER_HOST].crt
• /etc/ssl/private/[KIUWAN_WEBSERVER_HOST].key
• /etc/apache2/ssl.crt/ca.crt

Now you should tell Apache to listen on the configured HTTPS port, editing the ports.conf file (i.e. /etc/apache2/ports.conf):

Listen [KIUWAN_WEBSERVER_PORT]

To add a virtual host for Kiuwan On-Premises, you can add a file in your Apache installation folder (i.e. /etc/apache2/sites-available/kop.conf) with the following content. Make sure you replace the variables put inside brackets for those you previously configured when installing your Kiuwan On-Premises instance, and a protocol is set (choose between AJP or HTTP) in the ProxyPass directives:

<VirtualHost *:[KIUWAN_WEBSERVER_PORT]>
ServerName [KIUWAN_WEBSERVER_HOST]
ServerAdmin webmaster@localhost
DocumentRoot /var/www/html


SSLEngine on
SSLCertificateFile /etc/ssl/certs/[KIUWAN_WEBSERVER_HOST].crt
SSLCertificateKeyFile /etc/ssl/private/[KIUWAN_WEBSERVER_HOST].key
SSLCertificateChainFile /etc/apache2/ssl.crt/ca.crt


LogLevel debug
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined


ProxyRequests Off
ProxyPreserveHost On
<Proxy *>
Require all granted 
</Proxy>


ProxyPass       /   [ajp|http]://[KIUWAN_HOST]:[KIUWAN_PORT]/
ProxyPassReverse    /   [ajp|http]://[KIUWAN_HOST]:[KIUWAN_PORT]/


<Location />
Require all granted
</Location>


# Redirect http traffic to https
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^.*$ https://%{SERVER_NAME}%{REQUEST_URI} [R,L]


</VirtualHost>