Introduction

Kiuwan on premise installer is a powerful tool that suits multiple environment 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:

These softwares are also needed:

Please follow Docker official recommendations when installing Docker. These URLs describe the installation process for different Linux distributions:

We also recommend using the target installation hosts exclusively for Kiuwan services. If you plan on running other containers than Kiuwan's in a single-host installation, please make sure that none of them are using the following network:

172.172.0.0/16

Needed internet connections

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

HostNeeded whenPurpose
https://hub.docker.comInstallingThis is the main Docker server where the needed images will be pulled from.
https://static.kiuwan.comInstallingThis is Kiuwan's static content server, needed by the installer to download needed resources.
https://api.kiuwan.com

You own a Kiuwan on Premises Insights license, both for installing and running

This is Kiuwan's central API endpoint, needed to update Insights vulnerabilities database.

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.

ServiceMemoryCPU cores
wildfly-f[n]2GB2 cores
wildfly-a[n]2GB2 cores
wildfly-s[n]2GB2 cores
mysql5GB4 cores
loadbalancer1GB1 core
redis_0000[n]2GB2 cores

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:

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

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:

ResourcePurpose
/config/volumes.propertiesConfiguration file to set where your persistent volumes will reside.
/docker/*.shAdvanced shell scripts to interact with your Kiuwan on premise installation.
/logsThe folder where the tool will write installation logs.
/sslTools that ease the certificate creation to keep Kiuwan on premise under a secure environment.
/user-contentThe folder where you will have to put some resources the installation process will need.
/volumesThe base persistent volumes (that may be copied to different locations depending on your installation needs).

*.sh

Main shell scripts to interact with your Kiuwan on premise installation.

The following sections will guide you through the installation process.

Installation: common steps

This guide will reference two important folders:

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:

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 premise 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:

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

Take note of the locations you choose for each volume. You will need these paths for the next installation step.

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

Please note that this is the file located in your [VOLUMES_DIR], not in the [INSTALLER_DIR], which only contains the base volumes.

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

Installation: single-host and minimum configuration

Follow this section if you want to proceed and install Kiuwan on premise with no further customization.

The defaults will install Kiuwan on premise with these characteristics:

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:

Once the installation is finisished please refer to the Accessing your Kiuwan on Premises installation section.

Installation: advanced configuration

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

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

PropertyDefault valueMeaning
Access configuration
kiuwan.protocolhttpsKiuwan default access protocol
kiuwan.domainkiuwan.onpremise.localKiuwan default domain
kiuwan.port443Kiuwan default access port
Mailing configuration
kiuwan.mail.host Email server host
kiuwan.mail.port Email server port
kiuwan.mail.username Email server username
kiuwan.mail.password Email server password
kiuwan.mail.from Email account you want Kiuwan to use when sending emails
kiuwan.default.mail.account Email account to set to the built-in Kiuwan users
Kiuwan instances shared configuration
timezoneEurope/MadridKiuwan servers timezone
Kiuwan front instances configuration
kiuwan.nodes.front.max.memory1024mMax memory to set to front instances
session.timeout3600Time a session can be inactive before close it (in seconds)
session.securefalseUse the secure attribute of the session cookie
session.httponlyfalseUse the httponly attribute of the session cookie
Kiuwan analyzer instances configuration
kiuwan.nodes.analyzers.max.memory1024mMax memory to set to analyzer instances
queues.reportsGeneratedQueueSize2Number of slots enabled for analysis processing
Kiuwan scheduler instances configuration
kiuwan.nodes.schedulers.max.memory1024mMax memory to set to front instances
Kiuwan file repositories configuration
centralFileRepository.typefilesystemCentral file repository storage type [filesystem|s3]
sourceCodeFileRepository.typefilesystemSource code repository storage type [filesystem|s3]
Amazon S3 bucket configuration (only applies when using AWS S3 type repositories)
s3.privateBucket.bucketName S3 bucket name
s3.privateBucket.subDirectoryName S3 subdirectory name
s3.privateBucket.accessKeyId Access key id
s3.privateBucket.secretKeyId Secret key id
s3.dir.centralFileRepository Central file repository directory
s3.dir.sourceCodeFileRepository Source code file repository directory
MySQL configuration
mysql.hostmysqlkiuwanMySQL server host
mysql.port3306MySQL server port
mysql.usernamecsaasMySQL server username
mysql.password MySQL server password
mysql.config.useSSLfalseEnable or disable the use of encryption when connecting to MySQL
mysql.config.requireSSLfalseForce the use of encryption when connecting to MySQL
mysql.config.verifyServerCertificatefalseForce the validation of the certificate served MySQL
Redis Cluster cache and store configuration
redis.[cache|store].nodesredis_0000[1-6]:6379Redis nodes hosts (use the provided single host name when using elasticache)
redis.[cache|store].timeout2000Redis connection timeout
redis.[cache|store].password Redis password
redis.[cache|store].clientName Redis client name
SSL configuration
java.keystore.password Java keystore password. This must be aligned with the generated keystore password (in case you change the default Kiuwan host name)
java.truststore.password Java truststore password. This must be aligned with the generated truststore password (in case you change the default Kiuwan host name)

Accessing your Kiuwan on Premises installation

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:

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

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

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.

Once the previous steps have been done, you should be able to access Kiuwan on Premises entering your Kiuwan host in your browser:

Handling trusted certificates warning messages in your browser  and clients 

Please refer to the Managing certificates section for a complete explanation on how to correctly handle this situation depending on your installation configuration.

Default users

Kiuwan on premise supplies two user accounts:

UsernameDefault password
sysadminsysadmin
kiuwanadminkiuwanadmin

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