Kiuwan On-Premises Advanced Installation

This guide covers most of the advanced installation procedures that you may need to implement.
 

Modifying the default domain

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

We encourage you 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 preferred editor, open the default configuration file located in your config-shared volume:

sudo vim

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

Set kiuwan.domain as kiuwan.onpremise.local 

Step 2: Update load balancer configuration

Once you have selected your new domain and if you are using the provided Apache load balancer, you should edit the main Apache configuration file:

sudo vim [VOLUMES_DIR]/config-shared/ApacheLoadBalancer/conf/httpd.conf

Edit this line and change the default domain (kiuwan.onpremise.local) to your new domain:

Define kiuwanDomain 

kiuwan.onpremise.local

If you have externalized the provided Apache load balancer, you should edit the equivalent configuration file to set the new domain.

Step 3: Generate new certificates

Please refer 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 [INSTALLER_DIR]/user-content/certs folder:

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

Step 4: 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: single-host and minimum configuration
• Installation: advanced configuration

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

cd [INSTALLER_DIR]

sudo ./stop-all.sh

cd [INSTALLER_DIR]/docker

sudo ./update.sh

cd [INSTALLER_DIR]

sudo ./start-all.sh

Step 5: Update your DNS or hosts files

If you are modifying an existing Kiuwan On-Premises installation, you will need to update your DNS or hosts files.

Note that if you have generated new certificates signed by a different CA than the one that signed the previous ones, you should update your Kiuwan On-Premises clients' certificates or trust stores. 

• 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]

Modifying access protocols

Kiuwan On-Premises installation supports configuring access protocols for:

• Apache load balancer: HTTPS (default protocol) or HTTP.
• Kiuwan front instances: HTTPS (default protocol), HTTP, or AJP.

If you need to change the default access protocols, please take into account:

• Apache load balancer configuration must be manually modified, both when using the provided services or when externalizing it.
• Plaintext connections are not secure.

Step 1: Configure Apache load balancer access protocol

In case you are using the provided Apache service for load balancing or your own Apache as a front-end server, you should manually configure how it accesses Kiuwan, by editing its configuration file. For the provided services you can edit the file like this:

sudo vim [VOLUMES_DIR]/config-shared/ApacheLoadBalancer/conf/httpd.conf

Look for the balancer proxy definition (<Proxy "balancer://mycluster">) and make sure the used protocol matches your needs.

The following example shows the needed configuration for accessing two Kiuwan On-Premises front instances through AJP protocol:

BalancerMember "ajp://wildflykiuwan-f1:8443" route=kwf1 loadfactor=1 connectiontimeout=5 timeout=600 retry=60 hcmethod=TCP hcpasses=2 hcinterval=15 hcfails=1

BalancerMember "ajp://wildflykiuwan-f2:8443" route=kwf2 loadfactor=1 connectiontimeout=5 timeout=600 retry=60 hcmethod=TCP hcpasses=2 hcinterval=15 hcfails=1

The following example shows the needed configuration for accessing two Kiuwan On-Premises front instances through HTTP protocol:

BalancerMember "http://wildflykiuwan-f1:8443" route=kwf1 loadfactor=1 connectiontimeout=5 timeout=600 retry=60 hcmethod=GET hcexpr=ok200 hcuri=/saas/rest/health hcpasses=1 hcinterval=15 hcfails=2

BalancerMember "http://wildflykiuwan-f2:8443" route=kwf2 loadfactor=1 connectiontimeout=5 timeout=600 retry=60 hcmethod=GET hcexpr=ok200 hcuri=/saas/rest/health hcpasses=1 hcinterval=15 hcfails=2

Note that if you are not using a front-end server because you want to access directly to a single Kiuwan front instance, you will be forced to use either HTTPS or HTTP protocols to be able to access Kiuwan On-Premises from a web browser.

ProxyPreserveHost Off

Step 2: Configure Kiuwan front instances access protocol

Kiuwan On-Premises front instances expose a single port for communicating either by using HTTPS, HTTP, or AJP protocols. To configure the protocol to use, edit the main configuration file located in your config-shared volume:

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

Look for the "kiuwan-nodes.access.protocol property and set its value to either "https", "http" or "ajp" depending on the protocol you want to use. For example, to use the AJP protocol:

kiuwan-nodes.access.protocol=ajp

Note that this only sets how Kiuwan front servers are configured. You must configure how Kiuwan will generate access URLs for you by following the next step.

Step 3: Configure client access protocol for URL generation

Kiuwan instances need to know how you are accessing your Kiuwan On-Premises installation to correctly generate dynamic URLs. To configure this, edit the main configuration file, located in your config-shared volume:

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

Look for the "kiuwan.protocol" property and set its value to either "https" or "http". For example, if you want to access Kiuwan On-Premises through https:

kiuwan.protocol=https

Note that "https" and "http" are the only two allowed options here, as you can only access Kiuwan On-Premises from a web browser through one of these protocols.

Step 4: Restart your servers

In case you have made modifications to the provided Apache load balancer, you should restart the server:

cd [INSTALLER_DIR]/docker
sudo ./stop-infrastructure.sh apacheloadbalancer
sudo ./start-infrastructure.sh apacheloadbalancer

If you are using your front-end server, please restart to apply the changes.

In case you have made modifications to the globalConfig.properties file, you should restart the Kiuwan servers:

cd [INSTALLER_DIR]
sudo ./stop-kiuwan.sh
sudo ./start-kiuwan.sh

Modifying exposed ports

Kiuwan On-Premises installation supports changing which ports will be exposed to the outside of the Docker network by any of these services:

• Apache load balancer.
• Kiuwan front instances.
• MySQL database.

Note that the port used by the provided containers inside the Kiuwan Docker Network (172.172.0.0/16) is fixed and cannot be changed. Only the exposed ports are configurable. The following table shows which ports are used by each container inside the Docker network and how they are mapped to the outside by default:

Note that containers can only be accessed from outside their host when at least one port is exposed. These considerations should be taken into account as well:

• If you are accessing any container through HTTPS and you change the provided ports you should update your certificates to modify the provided SANs (Subject Alternative Names). Please refer to Managing certificates page for more information.
• On single-host installations where the provided front-end server (apacheloadbalancer) or the provided MySQL (mysqlkiuwan) are not externalized, changing Kiuwan front instances ports or MySQL port is not usually needed unless there are port conflicts on your host. As we recommend using a dedicated host for Kiuwan On-Premises installations, this should not be the case in most installations. By default, the provided Apache accesses Kiuwan front instances through port 8443, and Kiuwan accesses MySQL through port 3306, as they belong to the same Docker network.
• When using an externalized front-end server, it may be needed to change the Kiuwan front instances' ports if your company has strict traffic guidelines or you just prefer using ports that you are more comfortable with.
• In case you are using your MySQL server, Kiuwan should be instructed to use the port to which your MySQL server is listening to.
• In case you are using the provided MySQL container on a different host and you want to modify the exposed port by the container you must change both the MySQL exposed port and the port used by Kiuwan to communicate with MySQL. Both ports must match.

cd [INSTALLER_DIR]/docker
sudo ./stop-infrastructure.sh apacheloadbalancer
sudo ./start-infrastructure.sh apacheloadbalancer

cd [INSTALLER_DIR]
sudo ./stop-kiuwan.sh
sudo ./start-kiuwan.sh

Modifying exposed ports in Apache load balancer

When using the provided Apache load balancer, the following properties are found in the globalConfig.properties main configuration file will set the exposed ports:

• kiuwan.port.apache.http: sets the exposed port for HTTP.
• kiuwan.port.apache.https: sets the exposed port for HTTPS.

Ports set must be different to avoid conflicts. Note that the provided Apache container will expose both ports to listen HTTPS and HTTP traffic, but you can unset any of them by modifying the provided configuration file.

Step 1: Modify globalConfig.properties file

In case you modify the default ports, you must change the httpd.conf file located under [VOLUMES_DIR]/config-shared/ApacheLoadBalancer/conf folder.

Locate the properties shown above and set them to the ports that you want to expose (default configuration is shown below):

kiuwan.port.apache.http=80
kiuwan.port.apache.https=443

Step 2: Modify httpd.conf file

First, locate the ports Apache will listen to and set your selected ports. The default configuration is shown below (ports 80 and 443):

Listen 80
Listen 443

Second, locate the default virtual host entry and change the assigned port. The default configuration is shown below (port 443):

<VirtualHost *:443>

Open browser and visit https://localhost/saas/web/dashboard/dashboard

Modifying exposed ports in Kiuwan front instances

To change the exposed port of a Kiuwan front instance, edit the main configuration file (globalConfig.properties):

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

Locate the following properties (default values are shown):

By default, only one front instance will be started, but it is recommended to change all available instances just in case you need to add front instances in the future.

Note that the previous properties set the ports that will be exposed outside Kiuwan Docker network. Changing these ports is only recommended when externalizing the Apache load balancer service, as the internal port (8443) will be used when this service is inside the Docker network.
 

Modifying exposed ports in MySQL

To change the exposed port of the provided MySQL service, edit the main configuration file (globalConfig.properties):

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

Locate the following property (default value is shown):

kiuwan.port.mysql=3306

Note that the previous property sets the port that will be exposed outside Kiuwan Docker network. Changing these ports is only recommended when externalizing the MySQL service, as the internal port (3306) will be used when this service is inside the Docker network.
 

Setting which ports Kiuwan should use

Kiuwan instances must know which ports you are exposing both in:

• The provided Apache load balancer or your front-end server.
• The provided MySQL database or your MySQL instance.

As both services can be externalized, there are two additional properties to configure these ports (found in the main configuration file [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties):

• kiuwan.port: the port that will be used when generating dynamic URLs from Kiuwan. This port must match the one exposed by the front-end server.
• mysql.port: the port that will be used by Kiuwan to connect to the MySQL host. This port must match the one exposed by the MySQL server.
   

Configuration examples

Example 1

The following table shows how to set the values in globalConfig.properties file for installation where:

• All Kiuwan containers are deployed on the same host (single host installation).
• Apache load balancer externalized. The Apache server listens to port 444.
• Apache will access Kiuwan On-Premises front servers through port 8009. If new front instances are added, the next port will be used for the new instance.
• MySQL has been externalized and is accessible through port 3344.

The front-end server must use ports 8009, 8010, etc., to access Kiuwan front servers.

Example 2

The following table shows how to set the values in globalConfig.properties the file for installation, where:

• All Kiuwan containers are deployed on the same host (single host installation).
• Apache load balancer is NOT externalized and will listen to port 80 for HTTP and port 443 for HTTPS.
• Kiuwan On-Premises front servers should be accessible from the outside through port 8080. If new front instances are added, the next port will be used for the new instance.
• MySQL has NOT been externalized and will be accessible through port 3406 for direct external connections to the database.

The front-end server must use port 8443 to access Kiuwan front servers, as it belongs to the same Docker network, but a user will be able to access these front servers through ports 8080, 8081, etc., from outside the Kiuwan On-Premises host.