Kiuwan On-Premises Installation Tool

Kiuwan On-Premise could be installed and used in both privileged-mode docker setup and unprivileged-mode docker setup. The latter is the recommended way due to the improved security of the setup.

This guide references two important folders:

• [INSTALLER_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 (Install in a rootless mode - recommended for security): Create a non-root user for installing Kiuwan

The execution of this step requires administrative permissions. The user executing this section needs sudo privileges. Only execute this section if you are installing Kiuwan, this should be run in unprivileged environment (recommended). Ensure the existing user is added to the docker group and can execute docker commands.

For example, let's suppose the non-root username is steve. The actual username should be used in its place.

Execute the command to add the user to the ‘docker’ group:

sudo usermod -aG docker steve

To configure user namespace mappings correctly, entries must be added to /etc/subuid and /etc/subgid. This involves mapping a non-root user to a specified range of subordinate user and group IDs. It should be ensured that the specified ranges do not overlap with those assigned to any other user in the respective files. Further details can be found in the documentation here.

Example: In /etc/subuid add these lines.

steve:<steve_user_id>:1
steve:100000:65536

In /etc/subgid add these lines.

steve:<steve_group_id>:1

steve:100000:65536

The user's UID and GID can be retrieved by executing the following command:

id steve

By adhering to these guidelines, it will be ensured that the subordinate ID mappings are correctly established and do not conflict with other users. The changes will take effect only when a new user session is started.

Then, edit the file: /etc/docker/daemon.json. Add a new userns-remap entry in it. The final JSON would look something like the following:

{
.... ,
.... ,
"userns-remap": "steve"
}

Run below commands to restart Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

Switch to the non-root user for the next steps, if you are installing as a non-root user.

Step 2: Download kiuwan-cluster

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

The latest available installation tool is downloaded to the current directory.

Note that, as stated in System requirements, you will need access to static.kiuwan.com in order to download this file. You should also check your proxy configuration if you access the internet over a proxy server.

Step 3: untar kiuwan-cluster

Once downloaded, you should untar the provided gz file:

tar xvzpf kiuwan-cluster.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 [INSTALLER_DIR] throughout this guide.

Step 4: Copy license files

To start a Kiuwan On-Premises installation, you need two license files:

• configq1.zip
• license.zip

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

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

hostid
uname -a
docker info
wget https://static.kiuwan.com/download/analyzer/agent.version

Step 5: 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 https://cdn.mysql.com/archives/mysql-connector-java-5.1/mysql-connector-java-5.1.39.tar.gz

Untar the downloaded file:

tar xvzpf 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/mysql-connector-java-5.1.39-bin.jar [INSTALLER_DIR]/user-content

Step 6: Configure the volumes paths

The installation tool provides the base volumes needed to boot a first installation of Kiuwan On-Premises. Three volumes are included:

• 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 of each service.

The installation tool needs to know where you want these volumes to reside. To do so, edit the file located in [INSTALLER_DIR]/config/volumes.properties and set desired locations:

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

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

Note that you need to create the configured folders by running the following command (it is conditional, based on root or rootless installation):

[sudo] mkdir [VOLUMES_DIR]

In case you are using different base directories for each volume, you must create all the needed base directories.

Step 7: Initialize your volumes

Copy the provided volumes to the configured location by running this script (it is conditional, based on root or rootless installation):

cd [INSTALLER_DIR]

[sudo] ./deploy-volumes.sh

Step 8: Configure your email server

Kiuwan On-Premises needs a working and accessible email 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/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.authentication: a flag to indicate if your mail server needs authentication or not.
• kiuwan.mail.username: the username to use when authenticating with your email server (only applies if kiuwan.mail.authentication is true).
• kiuwan.mail.password: the password to use when authenticating with your email server (only applies if kiuwan.mail.authentication is true).
• kiuwan.mail.from: the email account to use as the sender.
• kiuwan.mail.secure.layer: the security layer that your mail server uses (ssl, tls or none). Set to none if your mail server uses a plaintext connection.
• kiuwan.mail.secure.layer.value: the value to set to the ssl or tls (true or false). Only applies if kiuwan.mail.secure.layer is not none.
• kiuwan.default.mail.account: the email account to set to the default Kiuwan user (kiuwanadmin).

Mail server configuration examples

If your mail server uses a plaintext connection without authentication, set these properties values (other mail server properties values will be ignored):

• kiuwan.mail.authentication=false
• kiuwan.mail.secure.layer=none

If your mail server uses a TLS secure connection but does not need authentication:

• kiuwan.mail.authentication=false
• kiuwan.mail.secure.layer=tls
• kiuwan.mail.secure.layer.value=true

If your mail server uses a SSL secure connection and needs authentication:

• kiuwan.mail.authentication=true
• kiuwan.mail.username=myuser
• kiuwan.mail.password=mypassword
• kiuwan.mail.secure.layer=ssl
• kiuwan.mail.secure.layer.value=true

If your mail server uses a plaintext connection and needs authentication:

• kiuwan.mail.authentication=true
• kiuwan.mail.username=myuser
• kiuwan.mail.password=mypassword
• kiuwan.mail.secure.layer=none

Step 9 (When installing in a rootless mode): Enable namespaces in Kiuwan config 

Only execute this section if you want to install Kiuwan as a non-root user. Edit with your preferred editor the main configuration file, found in your [VOLUMES_DIR].

vim [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties
Set kiuwan.ownNamespaceEnabled=true

Step 10: (Optional) Enable MySQL database port access

Only execute this section if you want to install kiuwan as a non-root user and you want to enable access to MySql port on host. The default value is false. This can be enabled later on after the upgrade separately if you are unsure right now. Edit with your preferred editor the main configuration file, found in your [VOLUMES_DIR].

vim [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties
Set kiuwan.accessMySql=true

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 Kiuwan On-Premises Distributed 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.

If you plan to change the default domain, please refer to the Modifying the default domain section before continuing and come back here after you have made the needed changes.

Step 1: Deploy user content

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

[sudo] ./deploy-user-content.sh

This copies the user-content files to the configured volumes and sets the needed permissions.

Step 2: Install Kiuwan On-Premises

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

sudo ./install.sh

This will:

• Check if your host meets the minimum installation requirements.
• 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 finished, please refer to the Accessing your Kiuwan On-Premises installation section.

Accessing your Kiuwan On-Premises installation

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.

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 on 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 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 of how to handle this depending on your installation configuration.

Step 3: Access Kiuwan On-Premises

Accessing the web application

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

https://kiuwan.onpremise.local

Note that although the installation process may have finished, the Kiuwan servers may need some minutes to start up. If this is the case, a loading page will be shown (as long as you are using the provided Apache load balancer service):

Once Kiuwan On-Premises services are started, you will be redirected to your Kiuwan On-Premises installation's main login page:

Downloading Kiuwan Local Analyzer

Once logged into the web application, you can download Kiuwan Local Analyzer by clicking Download Kiuwan Local Analyzer option in the top right drop-down menu. 

Consuming Kiuwan REST API

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

http(s)://[KIUWAN_DOMAIN]/saas/rest/v1

Please refer to the Kiuwan REST API documentation deployed in your Kiuwan On-Premises server for more details:

http(s)://[KIUWAN_DOMAIN]/pub/doc/rest-api/kiuwan-rest-api.html

You can also access the REST API documentation through the link shown in your Kiuwan On-Premises login page.

Configuring Kiuwan for Developers

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

For more information visit Kiuwan for Developers page.

Default users

Kiuwan On-Premises is provided with two user accounts:

Please make sure you change these passwords as soon as possible, by selecting the option Account management from the menu in the upper right corner and selecting Change Password.

Enable MySQL port after completing installation (When installed in rootless mode)

If you want to enable MySQL port access on the host machine after namespace is enabled. You need not run this if you have already enabled it during installation. Only execute this section if you are running as a non-root user. For root user installation ii is enabled by default.

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

vim [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties
Set kiuwan.accessMySql=true

Change the directory to [INSTALLER_DIR] and execute:

./openMysqlPort.sh