Installing the HCL Connections Component Pack 6.5 CR1 – Part 6: Configuring the applications

Posted on by

In part 5 I discussed the installation of all components. Now it’s time to configure them. My goal is not to duplicate the HCL documentation on this point, but to highlight where this documentation is ambiguous or incomplete. So by all means, also read that documentation.

OrientMe

The steps to configure OrientMe consist of the following:

  1. Configure IBM HTTP Server
  2. Configure SDI (TDI)
  3. Configure profiles-config.xml and LotusConnections-config.xml
  4. Restart Connections
  5. Test your OrientMe Homepage
  6. Populate the homepage

Configure IBM HTTP Server

To start with IHS, check if all necessary modules are loaded by making sure none of these 4 module load commands are commented out:

  • LoadModule proxy_module modules/mod_proxy.so
  • LoadModule proxy_connect_module modules/mod_proxy_connect.so
  • LoadModule proxy_ftp_module modules/mod_proxy_ftp.so
  • LoadModule proxy_http_module modules/mod_pro

you need to add the following lines in 2 area’s. One time before the <VirtualHost ip-address:443> section and one time in this section:

# **** BEGIN ORIENT ME config ****
ProxyPreserveHost On
ProxyPass "/social" "http://<kubernetes-master-url>:32080/social"
ProxyPassReverse "/social" "http://<kubernetes-master-url>:32080/social"
ProxyPass "/itm" "http://<kubernetes-master-url>:32080/itm"
ProxyPassReverse "/itm" "http://<kubernetes-master-url>:32080/itm"
ProxyPass "/community_suggestions/api/recommend/communities" "http://<kubernetes-master-url>:32080/community_suggestions/api/recommend/communities"
ProxyPassReverse "/community_suggestions/api/recommend/communities" "http://<kubernetes-master-url>:32080/community_suggestions/api/recommend/communities"
ProxyPass "/appreg" "http://<kubernetes-master-url>:32080/appreg/"
ProxyPassReverse "/appreg" "http://<kubernetes-master-url>:32080/appreg/"
ProxyPass "/appregistry" "http://<kubernetes-master-url>:32080/appregistry"
ProxyPassReverse "/appregistry" "http://<kubernetes-master-url>:32080/appregistry"
ProxyPass "/boards" "http://<kubernetes-master-url>:32080/boards"
ProxyPassReverse "/boards" "http://<kubernetes-master-url>:32080/boards"
ProxyPass "/api-boards" "http://<kubernetes-master-url>:32080/api-boards"
ProxyPassReverse "/api-boards" "http://<kubernetes-master-url>:32080/api-boards"
# **** END ORIENT ME config ****

Obviously using the http protocol, this interserver traffic is going to be unencrypted. As long as your server environment is secure, that shouldn’t be a problem, but otherwise you’ll have to exchange certificates and use ssl. I’m not going to cover that though.

Restart your IHS server(s) to activate the changes.

Configure SDI

edit your tdi-profiles-config.xml file in your TDI solutions directory (<TDI Solutions dir>/conf/LotusConnections-config/tdi-profiles-config.xml) and add (only add the lines in green):

</profileExtensionAttributes>
<properties> 
  <!-- Enable SIB events for Component Pack -->
  <property name="com.ibm.lconn.profiles.config.EnableManagerChangeEvent" value="true"/>
  <property name="com.ibm.lconn.profiles.config.EnableTDIEventOverride" value="true"/> 
</properties>
</tdiconfig>

Run sync_all_dns(.sh/.bat) to rerun TDI population.

Configure profiles-config.xml and LotusConnections-config.xml

In the LotusConnections-config directory edit profiles-config.xml and add the lines in green:

<!-- directory page: people type-ahead search (ptas) -->
<property name="com.ibm.lconn.profiles.config.ui.ptas.fireOnKeys" value="1" />
<property name="com.ibm.lconn.profiles.config.ui.ptas.delayBetweenKeys" value="0" />
<property name="com.ibm.lconn.profiles.config.ui.ptas.maxResults" value="20" />
<property name="com.ibm.lconn.profiles.config.ui.ptas.liveNameSupport" value="true" />
<property name="com.ibm.lconn.profiles.config.ui.ptas.expandThumbnails" value="true" />
<property name="com.ibm.lconn.profiles.config.ui.ptas.blankOnEmpty" value="true" />
<!-- Enable SIB events for Component Pack -->
<property name="com.ibm.lconn.profiles.config.EnableManagerChangeEvent" value="true"/>
<property name="com.ibm.lconn.profiles.config.EnableTDIEventOverride" value="true"/>

<!-- variable full text index -->
<property name="com.ibm.lconn.profiles.config.variableFullTextIndexEnabled" value="false"/>

In the LotusConnections-config.xml you need to add some more things, starting with this section:

Warning: HCL messed up this part in their documentation. If you use their example, you will not end up with a working configuration as they forgot to actually enable the service. Below is my configuration:

<!–Uncomment the following serviceReference definition if OrientMe feature is enabled–>
<sloc:serviceReference serviceName=”orient” enabled=”true” ssl_enabled=”true” bootstrapHost=”<your-kubernetes-master-url>” bootstrapPort=”32080″ clusterName=””>
<sloc:href>
<sloc:hrefPathPrefix>/social</sloc:hrefPathPrefix>
<sloc:static href=”https://connections.example.com>” ssl_href=”https://connections.example.com” />
<sloc:interService href=”https://connections.example.com” />
</sloc:href>
</sloc:serviceReference>

At the bottom of this file, enable the actioncenter and orientMe homepage by changing the values of these parameters from false to true:

<genericProperty name="actioncenter">enabled</genericProperty>
<genericProperty name="com.ibm.orient.isOrientHomepage">true</genericProperty>

Optionally, you can disable the homepage switcher so people are forced to use the OrientMe homepage. My customer wanted to give people a choice, so I kept this setting to true:

<genericProperty name="com.ibm.orient.isHomepageSwitcherEnabled">true</genericProperty>

HCL tells you in the documentation to edit a 3rd file, but as that file has the needed configuration already, you can skip that.

Next, do a full sync on your nodes from the WebSphere console and restart the entire environment. If everything went as it should have, you will now see the OrientMe homepage. Don’t continue if that doesn’t work.

HCL in their documentation now explains how to enable and secure your Redis traffic. If everything worked like it should, your Redis traffic is already enabled. If not, the HCl documentation will tell you what to do. Next you have to ask yourself if you want to secure the Redis traffic as this, again, is interserver communication. If you didn’t change the IHS config to use https instead of http, it doesn’t make sense to spend your time now on securing the Redis traffic. If you do want to secure your Redis traffic, then I have to warn you that the HCL documentation is not complete! When you follow the documentation and perform all tests, you will end up with with a working SSH tunnel. However, that tunnel is not used. To use the tunnel you have to reconfigure Redis by running the configureRedis.sh script:

<path-to>/microservices_connections/hybridcloud/support/redis/configeRedis.sh -m <your-kubernetes-master-url> -po 30379 -ic https://localhost -pw Your_Redis_Password -ic_u wasadmin -ic_p password

(little warning. I haven’t tried above myself, so check carefully). Thank you Martin Schmidt for pointing this out.

If you have the OrientMe homepage working, you can continue to populate it. Check the HCL documentation on this point on the different migration options.

Customizer & Push Notifications

Customizer will act between the user and IBM HTTP Server, so to make Customizer work you need to install a reverse proxy in front of your Connections environment which will sent all url’s that should be customized by Customizer to the MW-proxy component and should send all other url’s on to IHS. IHS needs to know where to forward requests for the AppReg so changes also needs to be made in IHS. Luckily the latter you already made when configuring the OrientMe homepage in IHS, so you’re good there. That leaves the changes in the reverse proxy, for which HCL advices nginx. While we’re discussing the configuration of nginx anyway, we can also take another recommendation of HCL along: Configuring an NGINX server for long polling. If you’ve ever monitored your IHS servers, you would have seen that a large number of all connections have the code W for waiting. These are the requests from your Push server. Nginx is more efficient for these kind of requests, so if nginx is in front of IHS anyway, it makes sense to bypass IHS and let nginx forward these requests straight to your Push server.

So here are (parts of) my nginx configuration file:

#Define your cluster of all WebSphere servers that run the push application along with the port for this server
upstream push {
  ip_hash;
  server <websphere-node-1.example.com>:11119;
  server <websphere-node-2.example.com>:11119;
}

# Redirect http requests to https
server {
  listen 80;
  server_name connections.example.com;
  location / {
    return 301 https://$host$request_uri;
  }
}

# The SSL section
server {
  listen 443 ssl;
  listen [::]:443 ssl;

  server_name connections.example.com;
  ssl_certificate /etc/nginx/ssl/connections.example.com.pem;
  ssl_certificate_key /etc/nginx/ssl/connections.example.com.key;

  ### SSL log files ###
  access_log /data/logs/nginx/connect-access.log;
  error_log /data/logs/nginx/connect-error.log;

# Proxy the Push URLs straight to WebSphere and skip IBM HTTP Server
  location /push/ {

    proxy_pass https://push;
    proxy_ssl_name $host;
    proxy_ssl_server_name on;

    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Upgrade $http_upgrade;
    proxy_buffering off;
    keepalive_timeout 160s;
    keepalive_requests 100000;
    proxy_read_timeout 900s;
    proxy_connect_timeout 75;
    proxy_send_timeout 600;
    send_timeout 600;
    proxy_ignore_client_abort on;
  }

  # Forward very specific urls to the MW-proxy (customizer). Below url's are for a customization where the Community Create button
  # is hidden for users that are not allowed to create communities
  location ~ ^/(files/customizer|communities/service/html) {
    proxy_pass http://<k8s-master.example.org>:30301;
  }

  # Forward anything else to IBM HTTP Server
  location / {
    proxy_pass https://<ihs.example.org>:443/;
  }
}

Even though the MW-proxy is rather efficient in forwarding urls it doesn’t need to customise straight back to IBM HTTP Server, it’s still more efficient if they never go there in the first place. That’s why I try to only forward the urls that will be customised.

Elasticsearch

Elasticsearch in the Component Pack is used for two purposes:

  • It serves as the new Metrics component replacing Cognos that was used in previous versions of Connections, but is no longer supported
  • it is used for the Quicksearch index which is used for the type-ahead search

In the documentation HCL split it up in two very separate parts, which makes it easy to forget one or the other. The work that’s identical for both is generating the SSL certificate:

On your Kubernetes master node:

cd <path-to>/microservices_connections/hybridcloud/support
python config_blue_metrics.py --skipSslCertCheck true --pinkhost 
cd /tmp
kubectl get secret elasticsearch-secret -n connections -o=jsonpath="{.data['chain-ca\.pem']}" | base64 -d > chain-ca.pem
kubectl get secret elasticsearch-secret -n connections -o=jsonpath="{.data['elasticsearch-metrics\.p12']}" | base64 -d > elasticsearch-metrics.p12

The documentation at this point tells you to copy these 2 files Copy the certificate files to the Deployment Manager in a common location readable and writable by all WebSphere Application Server nodes. They then advise to write it to /opt/IBM. No idea why as that won’t do the trick. Easiest is to write it to the shared storage in a separate directory. That’s a directory all your nodes can access.

Next you need to run a couple of wsadmin commands on your deployment manager. I’m going to assume you know how to start wsadmin.

execfile('esSecurityAdmin.py')
enableSslForMetrics('/data/shared/es-keys/elasticsearch-metrics.p12', '<your-elastics-search-secret goes here>', '/data/shared/es-keys/chain-ca.pem', '30099')

To explain this one. /data/shared is my NFS share for Connections and es-keys is the directory where I stored the 2 files from the previous step. The Elasticsearch secret you chose when you bootstrapped the environment (helm install –name=bootstrap etc.). The port is the default port for elasticsearch if you didn’t customise that.

Now it’s time to sync all your nodes and restart your whole WebSphere environment. When everything’s back up, get into wsadmin again. Read the HCL documentation before you enter the next commands. Mine were just:

execfile('metricsEventCapture.py')
switchMetricsToElasticSearch()

While you’re at it, also do the configuration for the type-ahead search:

execfile("searchAdmin.py")
SearchService.setESQuickResultsBaseUrl("https://k8s-master.example.org:30099")
SearchService.createESQuickResultsIndex()

To finish this configuration, you need to edit the LotusConnections-config.xml and search-config.xml as described in this piece of the documentation.

Removing SOLR

If you decide to use Elasticsearch for your type-ahead search (strongly recommended), you no longer need SOLR. However, the SOLR pods were deployed when you deployed OrientMe and are using resources. So how do you get rid of them? There are two ways. You can either edit the SOLR deployment and change the replica number’s to 0 (replicas=0) or enter this command on your Kubernetes Master:

kctl delete statefulset solr

(Thank you Christoph Stoettner and Urs Meli for those solutions)
That brings us to the end of this article. I still plan to add one more part on backing up your component pack, but it might be a while before I get to that.

References

HCL documentation on configuring the Component Pack
HCL documentation on configuring type-ahead search
HCL documentation on configuring nginx for push notifications

 

Back to part 5 | On to part 7