Purpose
The purpose of this documentation is supposed to be supplemental to the documentation provided by Qlik. Their documentation is good aside for two particular components:
- Certificates
- Troubleshooting
My goal is to elaborate on some real life scenarios and issues which are not touched on within the standard install docs. This also means that there will be many things that you may not encounter.
DO NOT FOLLOW THIS GUIDE BLINDLY. There are things that can break if you attempt to follow troubleshooting steps when they are not necessary.
Prerequisites
- Windows 2012+ Server with Qlik Sense Enterprise installed.
- This installation will be on the QSE server
- Linux VM
- Ubuntu
- CentOs
- RedHat Linux
Expectations
Timeframe
- Seamless Install: 2 hours
- This assumes you have access to everything you need.
- Troubleshooting Install: 4-8 hours
Note that if there are particular things you do not have control of then it can be further delayed.
- Ports
- Qlik Sense Certificates
- Host Files / DNS Entries (pending setup)
Skillset
This install is relatively straight forward with the exception of certificates, which I will document in detail in this document.
Required Knowledge (or willingness/ability to look up):
- Opening windows ports
- Generate certificates using OpenSSL
- SSH
- Basic Bash CMDSs (ls, cd, apt/yum install, mv, cp)
- IIS Binding Config
- Navigating Chrome Developer Tools
Prep
- Install .Net Framework 4.7.1 or greater on Windows Machine
- Install IIS 8.0
- I had issues installing IIS through the Server Manager. If you have errors, use the following in PowerShell:
>import-module ServerManager
>Add-WindowsFeature web-server -includemanagementtools > >
Since this does not include everything needed, you will also need to run this command:
- I had issues installing IIS through the Server Manager. If you have errors, use the following in PowerShell:
>Add-WindowsFeature web-http-tracing,web-request-monitor,web-windows-auth,web-net-ext45,web-asp-net45,web-websockets
After installing IIS, change the Default website binding from port 80 to 8080, to minimize possible conflicts with Qlik’s web server.
Configuring NLU on Win
Make sure to restart the linux box, otherwise it won’t accept the connection from the windows box
Configuring NLU
If you are completing an install through ssh, you will need to do the following:
**See Certs section at the end of the document for creating the .pem
files.
Create a folder containing:
- /tmp/
- docker-compose.yml
- nlu_key.pem
- nlu_crt.pem
Then utilize the scp
command to move the files to your linux box.
Cmd: scp -i %1% %2/* %3@%4:/home/%3
Parameters: %1 = PEM File to Linux Box
%2 = Absolute path to /tmp/ folder created above.
%3 = Linux User associated to PEM
%4 = Linux Box Hostname
Example:scp -i ./QlikSenseJune2017.pem /Users/treysmith/tmp/* ubuntu@ec2-x-xxx-xx-xx.compute-1.amazonaws.com:/home/ubuntu
Next ssh
into the box move the .pem files to /home/
*using the previous example
ssh -i "QlikSenseJune2017.pem" ubuntu@ec2-x-xxx-xx-xx
.compute-1.amazonaws.com
sudo mv ./*.pem /home/
Note: If you do this after spinning up the NLU, you will have to overwrite the certificates it created.
Next spin up the NLU:
docker-compose up -d
Using the -d
parameter forces the docker instances to spin up in a detached mode. If you do not use it, it will be attached to your terminal session which you will have to leave open.
DNS Adjustment
Depending on your environment, you will need to make sure that the hostname for your NLU resolves to the appropriate certificate.
This can be done in your cloud console, dns manager, or in the hosts file itself.
Hosts File
In a terminal:
Windows Installation
Certs
!!! Notice!!!
In a production environment, you have to have a SSL certificate validated by a CA Authority.
Self-signed will only work with manual work arounds, which are not suitable for users.
Export certs from the QMC.
- Machine Name should be the computer name that Qlik Insight Bot will be installed on.
In this example the server’s hostname will be trey.bardesscloud.com
.
In the QIB Configuration set-up Qlik panel, you will need to select a certificate for the QRS and proxy set up.
Both of these will be the exported self-signed client.pfx
cert.
After completing the installation, you will need to replace the webchat certs in the following path: C:\ProgramData\Qlik Insight Bot\Certificate
Take your signed certificate (ex: wildcardbardess.pfx’) and put it in a directory, c:\certs
With openssl we need to convert the .pfx
to a system agnostic format.
> cd c:/certs
> openssl pkcs12 -in wildcardbardess.pfx -nocerts -out NluEnc.key
> openssl rsa -in NluEnc.key -out nlu_key.pem
> openssl pkcs12 -in wildcardbardess.pfx -clcerts -nokeys -out nlu_crt.pem
> copy nlu_key.pem webchat.key
> copy nlu_crt webchat.crt
Let’s break this down into what is happening in order of cmd:
- Go to directory where signed certificate is.
- With
openssl
export private key to a key file. - With
openssl
import key file and create key certificate. - With
openssl
export client certificate to a file. - Copy the cert key file, which will be used elsewhere
- Copy the client cert file, which will be used elsewhere.
The NLU certs will be used on your NLU Linux machine. They should be moved to /home/
directory.
The webchat certs should be moved to c:/programdata/qlik insight bot/certificates
.
Both the NLU and Webchat services need a valid CA signed certificate. If they don’t they will get an https error. The other services will be communicating internally, so the self-signed cert will work appropriately, assuming QIB is installed on the same box.
Additional information to be added after doing a QIB install on a separate machine
Teams Integration
On top of the provided documentation, you need to publish the web app to the Teams Channel.
From the Team’s management console you will need to allow side loaded apps.
Also, you will need to make sure the 4434 port is open. The web app’s end point should be: https://<hostname>:4434/api/messages
.
Example: https://trey.bardesscloud.com:4434/api/messages
To access the bot you will need to create a new conversation and enter the Azure App ID in the To field.