Introduction

Kiuwan On-Premises installer is a powerful tool that suits multiple environment scenarios:

• Single-host full contained installation.
• Multi-host installation where infrastructure services are externalized.
• Multi-host installation where kiuwan services are distributed (only AWS environments supported so far).
• Any combination of the two previous scenarios.

Depending on your needs, a different installation approach will be needed. Check this installation guide for details on how to proceed and to find the solution that best fits your requirements.

System requirements

Installation requirements

It is mandatory for any host where Kiuwan On-Premises is installed to meet these requirements:

• Linux distribution
• Linux kernel version 3.10 or higher
• Connectivity to SMTP Mail Server.
• Internet connectivity during the installation process (see Installation guide).
• Installing user must be root or have sudo privileges.

These softwares are also needed:

• Docker CE >=19.03.2
• Docker-compose >= 1.24.1
• Unzip
• GNU tar
• Java Runtime Environment >=8 (needed to generate keystores for custom hosts).
• Openssl >= 1.1.1 (needed to generate certificates for custom hosts).

Needed internet connections

Please make sure your host machines have connection to these servers when installing Kiuwan On-Premises:

CPU and memory minimum requirements

The following table shows the minimum requirements for each service. Note that these are only minimum requirements. You should take care of giving each service enough resources depending on your system demands.

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

With the above configuration, a system with the following load should give continuous service without problems:

• Parallel processing 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)
• 50 concurrent web users or REST API calls.

Given the table above, for a single-host installation where no service is externalized the minimum system requirements are:

• 14GB of RAM and a processor with 8 cores for Kiuwan On-Premises.

It is recommended that you overscale these characteristics for the OS to have resources available for itself.

The Kiuwan On-Premises installation tool (kiuwan-cluster)

The Kiuwan On-Premises installation process is carried out by our "kiuwan-cluster" tool.

The tool is provided as a tar.gz file. The following table summarizes the resources you will find once the tool distribution is extracted:

The following sections will guide you through the installation process.

Installation: common steps

This guide will reference two important folders:

• [INSTALL_DIR]: where the installation tool (kiuwan-cluster) will be located.
• [VOLUMES_DIR]: where the persistent volumes will be located.

Sometimes these folders will be referenced inside command line examples. Please make sure you replace any of them with the needed real path.

Note that it is up to you where these folders will be located.

Step 1: download kiuwan-cluster

The first step is to download kiuwan-cluster (the Kiuwan On-Premises installation tool). It can be downloaded directly from a terminal like this:

wget https://static.kiuwan.com/download/onpremise/kiuwan-cluster.tar.gz

This will download the latest available installation tool to the current directory.

Step 2: untar kiuwan-cluster

Once downloaded, you should untar the provided gz file:

tar xvzpf kiuwan-cluster_master.tar.gz

This will untar the installation tool to a folder with extended version information of the tool. For example:

/home/user/kiuwan-cluster_master.XXXX-2.8.YYMM.V

This folder will be referred to as [INSTALL_DIR] throughout this guide.

Step 3: copy license files

In order to be able to start a Kiuwan On-Premises installation, you will need two license files:

• configq1.zip
• license.zip

Copy these files to the user-content folder of your installation tool directory (please replace [INSTALL_DIR] with the real location of your installation directory):

cp configq1.zip [INSTALL_DIR]/user-content
cp license.zip [INSTALL_DIR]/user-content

Step 4: download and copy the needed driver version for MySQL

Kiuwan On-Premises needs this exact MySQL driver:

mysql-connector-java-5.1.39-bin.jar

You can download it by executing this command and extracting the jar file included inside the tar:

wget http://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-5.1.39.tar.gz

Copy the connector jar file to the user content folder:

cp mysql-connector-java-5.1.39-bin.jar [INSTALL_DIR]/user-content

Step 5: initialize your volumes

The installation tool comes with the base volumes to boot a first installation of Kiuwan On-Premises. We provide three volumes:

• config-shared: contains the base configuration, shared between different services.
• data-shared: contains the base data structure, shared between different services.
• data-local: contains the base data structure, independent for each service.

Copy the provided volumes to your desired location:

sudo cp -rp [INSTALL_DIR]/volumes/config-shared [VOLUMES_DIR]/config-shared
sudo cp -rp [INSTALL_DIR]/volumes/data-shared [VOLUMES_DIR]/data-shared
sudo cp -rp [INSTALL_DIR]/volumes/data-local [VOLUMES_DIR]/data-local

Step 6: configure the created volume paths

Edit the file located in [INSTALL_DIR]/config/volumes.properties and set the previous paths to each property:

config.shared=[VOLUMES_DIR]/config-shared
data.shared=[VOLUMES_DIR]/data-shared
data.local=[VOLUMES_DIR]/data-local

Please remember that [VOLUMES_DIR] here is just a placeholder for the real path you chose.

Step 7: configure your email server

Kiuwan needs an working and accessible e-mail server to send notifications.

Edit with your preferred editor the main configuration file, found in your [VOLUMES_DIR]:

sudo vim [VOLUMES_DIR]/config-shared/globalConfig.properties

Edit the following properties under the section named "Kiuwan instances shared configuration":

• kiuwan.mail.host: the host of your email server.

• kiuwan.mail.port: the port of your email server.

• kiuwan.mail.username: the username to use when authenticating with your email server.

• kiuwan.mail.password: the password to use when authenticating with your email server.

• kiuwan.mail.from: the email account to use as the sender.

• kiuwan.default.mail.account: the email account to set to your default Kiuwan user.

Installation: single-host and minimum configuration

Follow this section if you want to proceed and install Kiuwan On-Premises with no further customization.

The defaults will install Kiuwan On-Premises with these characteristics:

• Single-host installation, including these services (see System architecture for more details):
  • Apache as a load balancer.
  • A Kiuwan front instance.
  • A Kiuwan analyzer instance.
  • A Kiuwan scheduler instance.
  • MySQL database.
  • Redis cluster.
• HTTPS support when accessing Kiuwan and between the loadbalancer and Kiuwan instances.
• Kiuwan On-Premises deployed in the default domain (https://kiuwan.onpremise.local).

If this is enough for you, just continue with the following steps.

Step 1: deploy user content

On a terminal, navigate to the [INSTALL_DIR] folder and execute this command:

sudo ./deploy-user-content.sh

This will copy the user-content files to the configured volumes and set the needed permissions.

Step 2: install Kiuwan On-Premises

On a terminal, navigate to the [INSTALL_DIR] folder and execute this command:

sudo ./install.sh

This will:

• Download and run the needed Docker images.
• Install the database resources for Kiuwan On-Premises.
• Download the latest available Local Analyzer, Engine and Kiuwan for Developers to make them available in your installation.
• Install the engine data in your Kiuwan On-Premises database.
• Autogenerate the needed configuration for each Kiuwan instance.
• Run all the needed containers.

Once the installation is finisished please refer to the Installation guide section.

Installation: modifying the default domain

The default configuration sets "kiuwan.onpremise.local" as the default domain to access Kiuwan On-Premises.

We encourage to change the default domain, but take into account that this means updating the provided certificates to keep your installation connections secure.

Step 1: edit the global configuration file

Using your favourite editor, edit the default configuration file located in your config-shared volume:

vim [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties

Edit these properties (kiuwan.port is only needed if you want to use https under a different port than the default 443):

• kiuwan.domain
• kiuwan.port

Step 2: generate new certificates

Please refere to the Managing certificates guide and follow the needed steps depending on your needs.

Once this is done, you should have these files under the [INSTALL_DIR]/user-content/certs folder:

• cacert.pem
• domainkey.pem
• domaincert.pem
• domainkeystore.jks
• truststore.jks

Step 3: complete your installation

If you are performing a new Kiuwan On-Premises installation, please refer to the steps indicated in the following sections, depending on your installation needs:

• Installation guide
• Installation guide

If you have already installed Kiuwan On-Premises, you will need to stop your containers, update the deployed configuration and restart them. To do so, execute these commands:

cd [INSTALL_DIR]/docker
sudo ./stop-kiuwan.sh
sudo ./stop-infrastructure.sh
sudo ./update.sh
sudo ./start
sudo ./start-infrastructure.sh
sudo ./start-kiuwan.sh

Installation: advanced configuration

All configuration properties you can edit are located in this file located inside your data-shared volume:

• [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties

Here is a complete list of the properties you can configure and their meaning (default passwords are omitted):

Accessing your Kiuwan On-Premises installation

In order to access your Kiuwan On-Premises installation you should follow a few more steps.

Step 1: add your domain to your local network DNS

To access your Kiuwan On-Premises installation you should take into account whether the selected domain is available in the DNSs your local network may use.

In order to access Kiuwan you will need to do one of the following options:

• Add kiuwan.onpremise.local to your DNS (recommended option).
• Add kiuwan.onpremise.local to your hosts file.

For testing purposes or if you choose the second option, edit this file in the host where you plan to access Kiuwan from:

• Windows OS: C:\Windows\System32\drivers\etc\hosts
• Linux OS: /etc/hosts

Add the following entry to the previous file:

[kiuwan_on_premise_host_ip] [kiuwan_on_premise_host]

For example, the previous entry may look like this for an installation pointing to the default host (note that the IP of the example may change in your local network):

192.168.0.56 kiuwan.onpremise.local

Step 2: add your certificates' CA to your clients

Depending on whether you are using a trusted CA or not to sign your certificates, you may need to add the CA to your client's certificate store to avoid warning messages. 

Please refer to the Adding the provided or a custom CA to Kiuwan On-Premises' clients section for a complete explanation on how to handle this depending on your installation configuration.

Step 3: wait for Kiuwan services to be started

Note that although the installation process may have finished, the Kiuwan servers may need some minutes to start up. Please wait if you receive a "404 - Not Found" error message when accessing Kiuwan On-Premises.

Step 4: access Kiuwan On-Premises

Accessing the web application

Once the previous steps have been done, you should be able to access Kiuwan On-Premises entering your Kiuwan host in your browser which by default is:

https://kiuwan.onpremise.local

You will access you Kiuwan On-Premisesinstallation's main login page:

Exploiting Kiuwan REST API

To access  your Kiuwan On-Premises installation via its REST API, you should point to this URL:

https://[KIUWAN_DOMAIN]/saas/rest/v1

Configuring Kiuwan for Developers

To install Kiuwan for Developers plugins you should point to the corresponding download endpoint for each Kiuwan for Developers distribution:

Please refer to Kiuwan for Developers page for more information.

Default users

Kiuwan On-Premises supplies two user accounts:

Please make sure you change these passwords as soon as possible accessing the upper right menu option "Account management", section "Change password".