Sample steps to install or upgrade to Component Pack 7

Use these sample steps to help you install Component Pack 7, or upgrade to it in cases where don't plan to migrate existing data from Elasticsearch 5 to 7. If you do plan to migrate Elasticsearch data, skip this section and see Sample steps to upgrade and migrate data from Component Pack 6.5 to 7

Before you begin

For background information and where to get the latest download, see Installation and upgrades.

Before we start with the sample steps, let's make a few assumptions about the environment.

We are installing an environment which will be available behind web1.cnx-dev.net. However, this is just a public domain, and entry point to the Connections (and dynamicHost of Connections).

All the nodes are available using their FQDNs and are in a different domain:

  • Connections, with WebSphere and IHS is on connections1.internal.cnx-dev.net
  • DB2 is on db1.internal.cnx-dev.net
  • Kubernetes cluster is just a single node, and it is on cp1.internal.cnx-dev.net
  • NFS master is collocated with cp1.internal.cnx-dev.net and its IP address is 172.27.1.48 and all our folders are created in 172.27.1.48:/pv-connections/

About this task

This example uses the preceding assumptions to walk you through the following steps, in a logical order, to get your Component Pack deployment up and running:

Set up NFS

We don't recommend or support any particular configuration of NFS - you can use whatever NFS implementation is available. For the sake of this example, however, let's assume that that our NFS is on cp1.internal.cnx-dev.net, you have root access there, you installed NFS, you know how to manage it, and you just need to stuff needed for Component Pack.
  • Create /pv-connections folder on cp1.internal.cnx-dev.net
  • Inside that folder, create this set of subfolders:
    • /pv-connections/customizations with permissions 0005
    • /pv-connections/esbackup-7 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/esdata-7-0 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/esdata-7-1 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/esdata-7-2 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/esmaster-7-0 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/esmaster-7-1 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/esmaster-7-2 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/kudos-boards-minio with permissions 0700
    • /pv-connections/mongo-node-0 with permissions 0700
    • /pv-connections/mongo-node-1 with permissions 0700
    • /pv-connections/mongo-node-2 with permissions 0700

Ensure that all of the preceding folders are exported and mountable from your Kubernetes workers before you proceed.

Download and set up the package

On the server which has Helm v3 and kubectl configured for your non-root user, download and unpack the Component Pack archive to /opt/microservices_connections.

Create the namespace

On the server which has Helm v3 and kubectl configured for your non-root user, create the Connections namespace in Kubernetes by running the following command:
kubectl create namespace connections

Push the images to the Docker Registry or Amazon ECR

Inside your Component Pack package, you got basically a bunch of Docker prebuild images and Helm charts. We need to push those images now to some Docker Registry, which in this example lives on cp1.internal.cnx-dev.net on port 5000, has SSL enabled, and you can login to it using username admin and password password (or whatever you set, hopefully not this):

  • Go to component_pack_installation_folder/hybridcloud/support
  • Run this command: ./setupImages.sh -dr cp1.internal.cnx-dev.net:5000 -u admin –p password

Once this finishes, you should be good to go.

The same script is compatible with Amazon ECR.

Note: For upgrades, just repeat this step. It will add only the new packages, and Helm charts know which version they need.

Create Docker Registry credentials

In this step you need to map your credentials for Docker Registry or Amazon ECR with some secret inside the Kubernetes cluster, so that Kubernetes workers can use it to authenticate to your registry when pulling the images.

In all the Helm charts, hardcoded name for this is myregkey and you cannot change it if you don't manually edit each and every Helm chart to do it (which we definitely don't advise).

To create this credential, run:
kubectl create secret docker-registry myregkey –n connections --docker-server=cp1.internal.cnx--
dev.net:5000 --docker-username=admin --docker-password=password

Set up pod security policies

There is no change in pod security policy setup since Component Pack 6.5.0.1. To install, run this command:
helm upgrade k8s-psp component_pack_installation_folder/hybridcloud/helmbuilds/k8s-psp-*.tgz -i

Use –f instead of –set with Helm charts

Our examples folder is following the naming convention we are using throughout this topic. Feel free to check the examples for what we are rewriting for each chart.

This change makes it much cleaner, and is also the way our HCL-provided Ansible automation works. If you want to review or customize the examples, here's how:

  • Go to the Component Pack installation files for Helm chart configuration Knowledge Article on the HCL Software Support site, and download and unzip the folder cnx7-CP-examples.zip.
    Note: For the required Connections 7.0 update that the Component Pack 7.0.0.1 is part of, replace this zip even if you already downloaded it when you installed or upgraded to 7.0, as some settings have changed.
  • Copy the files to component_pack_installation_folder/hybridcloud/examples.
  • In the examples folder, open the subfolder that applies to your environment (either single or multiple domains).
  • Review the examples, or customize them by changing the values to the ones for your environment.
  • Continue with the steps that follow in this topic.

Set up persistent volumes and persistent volume claims on NFS

This command sets up both PVs and PVCs:
helm upgrade connections-volumes component_pack_installation_folder/hybridcloud/helmbuilds/connections-persistent-storage-nfs-*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/connections-volumes.yml
For how to troubleshoot PV and PVC setup, see theTroubleshooting Component Pack guide on the HCL software product documentation site.

Set up bootstrap charts

Bootstrap is one-time job. It creates secrets and certificates for various components, including Redis, MongoDB and ElasticSearch.

Be aware that simply rerunning/upgrading bootstrap also means recreating all those secrets and certificates, and requires in some cases redoing the steps which were dependent on it (like setting up certificates again for Metrics).

Starting with Component Pack 7, bootstrap will also create secrets and certificates for ElasticSearch 7.

To install or upgrade bootstrap, run:
helm del --purge bootstrap 
helm upgrade bootstrap component_pack_installation_folder/hybridcloud/helmbuilds/bootstrap*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/bootstrap.yml

Set up connections-env charts

This chart by default installs connections-env configmap.

Note: If you will be deploying Microsoft Teams integration, you can choose to enable it during initial connections-env setup or modify connections-env later. The value integrations.msteams.enabled=true is used to indicate that an additional integrations-msteams-env configmap and ms-teams-secret secret should be created, which are necessary for Teams integration to work. If you choose to set integrations.msteams.enabled=true at this time, see Set up Microsoft Teams integration before going further for an example upgrade command and list of additional values that must be provided to successfully complete the connections-env upgrade.

The configmap for connections-env contains all the variables needed for the Customizer and Orient Me to function properly. Note that Customizer always points to the IBM HTTP Server directly, whereas Orient Me requests point to the front door proxy.

To install or upgrade connections-env, run:
helm upgrade connections-env 
component_pack_installation_folder/hybridcloud/helmbuilds/connections-env-*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/connections-env.yml

Set up infrastructure charts

This will install the infrastructure for OrientMe and other apps, the most prominent being MongoDB and appreg services.

If this step fails, and if all pods don't come up, there is no point proceeding until this is fixed. To troubleshoot the Component Pack installation check out the Troubleshooting Component Pack document.

To install or upgrade it, run:
helm upgrade infrastructure component_pack_installation_folder/hybridcloud/helmbuilds/infrastructure-*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/infrastructure.yml

Set up Customizer

Customizer needs to be installed, customizations copied into its PV (living on your NFS:/pv-connections/customizations) and then enabled on Nginx:
  • Mount NFS:/pv-connections/customizations to the server where you have your Component Pack unpacked and from which you are managing installations
  • Copy all the files from component_pack_installations_folder/hybridcloud/support/customizations/* to NFS:/pv-connections/customizations
  • Copy component_pack_installations_folder/hybridcloud/support/ms-teams folder to NFS:/pv-connections/customizations
To install or upgrade it, run:
helm upgrade mw-proxy 
component_pack_installation_folder/hybridcloud/helmbuilds/mw-proxy-*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/customizer.yml
Setup your reverse proxy to forward some traffic to the customizer by sending it to KUBERNETES:30301. For Nginx, it would look like this:
location ~      ^/(files/customizer|files/app|communities/service/html|forums/html|search/web|homepage/web|social/home|mycontacts|wikis/home|blogs|news|activities/service/html|profiles/html|viewer)  { 

            proxy_pass http://cp1.internal.cnx-dev.net:30301; 

}

Customizer will not start serving any traffic until you start sending some, from whatever fronted reverse proxy you are using.

Learn more about configuring Customizer in Configuring the Customizer component.

Set up Elasticsearch charts

With Connections 7, ElasticSearch 7 is the default backend for OrientMe. It is also the default backend for search and Metrics.

Solr and Zookeeper are not used anymore, so feel free to clean them up if you didn't already.

Whether you are newly installing Elasticsearch or upgrading from Elasticsearch 5, install the new Elasticsearch 7 chart now by running:
helm upgrade elasticsearch7 
component_pack_installation_folder/hybridcloud/helmbuilds/elasticsearch7-*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/elasticsearch.yml
Note: Elasticsearch, because of the way it is set up starting with version 7, will not work if bootstrap didn't create its secrets and certificates beforehand.

Set up ingress

Starting with Connections 7, only the community Nginx Ingress controller is supported.

With community ingress, besides its being more flexibility with AWS and OpenShift, you also get out-of-the-box Prometheus exporters, which can come in handy if you decide to also set up monitoring.

To install or upgrade ingress, run:
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx 

helm repo update 

helm upgrade cnx-ingress -i ingress-nginx/ingress-nginx --namespace connections --set 
"controller.service.type=NodePort,controller.service.nodePorts.http=32080,controller.service.nodePorts.https=32443"
After installing the ingress controller, it is best if you apply the ingress rules. You can do that by running:
helm upgrade cnx-ingress-rules 
component_pack_installation_folder/hybridcloud/helmbuilds/cnx-ingress-*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/communityingress.yml
Note: The versions tested by HCL are 0.35 to 0.41 (the latest one as of January 2021).

Set up Microsoft Teams integration

The Microsoft Teams integration microservices rely on a configmap (integrations-msteams-env) and secret (ms-teams-secret) that are part of the overall connections-env deployment. They are not installed by the connections-env chart by default; the expectation is that they are enabled as needed by customers who use Microsoft Teams and wish to enable the use cases that these micro-services support.

To upgrade the connections-env deployment to enable the correct settings for Microsoft Teams, three specific pieces of information are required which should have been created and noted while performing the steps in Configuring an Azure app to support the Microsoft Teams app.

The items of information needed for this setup are:
  • Teams tenant ID
  • Bot (app) ID
  • Bot (app) password (secret)
With this information, to upgrade the connections-env and create the configmap and secret, run:
helm upgrade connections-env component_pack_installation_folder/hybridcloud/helmbuilds/connections-env-*.tgz --reuse-values --set integrations.msteams.enabled=true,integrations.msteams.tenant.id="your_tenant_id",integrations.msteams.client.id="your_bot_id",integrations.msteams.client.secret="your_bot_secret",integrations.msteams.auth.schema="3",integrations.msgraph.client.id="not_used",integrations.msgraph.client.secret="not_used",integrations.msgraph.redirect.uri="not_used",integrations.msteams.share.ui.files.api="/files/basic/api",integrations.msteams.redirect.uri="not_used",integrations.msgraph.secret.name="not_used",integrations.msgraph.auth.endpoint="not_used",integrations.msgraph.meta.endpoint="not_used",integrations.msgraph.authorize.endpoint="not_used",integrations.msgraph.token.endpoint="not_used",integrations.msteams.share.service.endpoint="my.connections.server.com",imagePullSecretName="myregkey"

Once the configmap and secret are created, continue to install the microservices that rely on them for configuration.

Run the following command:
helm upgrade teams 
component_pack_installation_folder/hybridcloud/helmbuilds/teams-*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/teams.yml

Once the microservices are installed and running, add the following rules to your httpd.conf on your IBM HTTP Server and restart the server.

#teams-tab-ui
ProxyPass "/teams-tab" "http://master_node_host_name:32080/teams-tab" 
ProxyPassReverse "/teams-tab" "http://master_node_host_name:32080/teams-tab"    
# teams-tab-api 
ProxyPass "/teams-tab/api" "http://master_node_host_name:32080/teams-tab/api" 
ProxyPassReverse "/teams-tab/api" "http://master_node_host_name:32080/teams-tab/api"
# teams-share-service 
ProxyPass "/teams-share-service" "http://master_node_host_name:32080/teams-share-service" 
ProxyPassReverse "/teams-share-service" "http://master_node_host_name:32080/teams-share-service"
# teams-share-ui 
ProxyPass "/teams-share-ui" "http://master_node_host_name:32080/teams-share-ui" 
ProxyPassReverse "/teams-share-ui" "http://master_node_host_name:32080/teams-share-ui"
# Teams SameSite Fix
# Add SameSite property to all server-side set-cookie response headers
Header edit Set-Cookie ^(.*)$ "$1; SameSite=None;Secure"
# Fix for Embedded Experiences content loading in Teams Tab iframe
<Location /connections/opensocial/gadgets/ifr>
Header unset Content-Security-Policy
Header always set Content-Security-Policy "frame-ancestors 'self' teams.microsoft.com *.teams.microsoft.com"
</Location>

The proxy pass statements map URI to the ingress controller service to route requests to the appropriate Microsoft Teams-related micro-services. Given tightening security of more recent versions of browser, especially Chrome (or Chromium-based browsers) and the use of embedded iFrames by Microsoft Teams, passing cookies correctly between the environments requires the SameSite=None and Secure property.

Lastly, and again for security reasons, you must change the x-frame-options header to support the way that Microsoft Teams uses an iFrame to embed application content in the tabbed pages. Since Connections also uses an iFrame to display embedded experiences content, this becomes an iFrame within an iFrame. The embedded experiences content cannot be displayed if SAMEORIGIN is used because the Teams UI and Embedded Experiences content do not share a common origin host. Using ALLOW-FROM permits the header to tell the browser that it is allowed to render content in the iFrame when processing the /connections/opensocial/gadgets/ifr request from an alternative host.

Set up Tailored Experience features for communities

A replacement strategy is being used to install or upgrade the Tailored Experience features; therefore it's important to note that you must add --force to the end of the command.

To install or upgrade Tailored Experience, run:
helm upgrade tailored-exp 
component_pack_installation_folder/hybridcloud/helmbuilds/tailored-exp-*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/tailoredexperience.yml --force
Once this is all set, add the following rules to your httpd.conf on your IBM HTTP servers and restart the service:
# proxy rules for admin-portal
ProxyPass "/cnxadmin" "http://cp1.internal.cnx-dev.net:32080/cnxadmin"  
ProxyPassReverse "/cnxadmin" "http://cp1.internal.cnx-dev.net:32080/cnxadmin"
# proxy rules for community-template-service
ProxyPass "/comm-template" "http://cp1.internal.cnx-dev.net:32080/comm-template/templates" 
ProxyPassReverse "/comm-template" "http://cp1.internal.cnx-dev.net:32080/comm-template/templates"
# proxy rules for te-creation-wizard
ProxyPass "/te-creation-wizard/" "http://cp1.internal.cnx-dev.net:32080/te-creation-wizard/" 
ProxyPassReverse "/te-creation-wizard/" "http://cp1.internal.cnx-dev.net:32080/te-creation-wizard/"
For post-installation tasks required to deploy the community creation wizard and templates, see Configuring the community creation wizard and Assigning administrators to template management roles.
Note: The Tailored Experience is not supported on the Microsoft SQL Server backend.
.

Set up Orient Me

With Connections 7, the default and only backend for Orient Me is ElasticSearch 7.

The prerequisites to set up and run Orient Me are:
  • Infrastructure charts need to be already installed and all pods scheduled.
  • connections-env configmap needs to be already present.
  • ElasticSearch 7 needs to be installed and running.
  • After you install Orient Me, you need to run profiles migration. In this step, we are migrating users from PeopleDB to MongoDB, which is used by Orient Me.
  • You need to set rewrite rules in httpd.conf on your IBM HTTP Server to enable sending requests to it from Connections.
To install or start the upgrade for Orient Me, run:
helm upgrade orientme 
component_pack_installation_folder/hybridcloud/helmbuilds/orientme-*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/orientme.yml
To migrate profiles, run this:
kubectl exec -n connections -it $(kubectl get pods -n connections | grep people-migrate | awk '{print $1}') -- sh -c "npm run start migrate"

If you followed examples and the order of installation, this should work out of the box. If you want to do some customizations, or if you are later changing the database, you can SSSH into people-migrate pod and see the configuration that was precreated for you during the installation/upgrade of Component Pack in /usr/src/app/migrationConfig.

And finally, add the rewrites to your httpd.conf on the IBM HTTP Server, and then restart the service:
# OrientMe Config 
ProxyPreserveHost On 
ProxyPass "/social" "http://cp1.internal.cnx-dev.net:32080/social" 
ProxyPassReverse "/social" "http://cp1.internal.cnx-dev.net:32080/social" 
ProxyPass "/itm" "http://cp1.internal.cnx-dev.net:32080/itm" 
ProxyPassReverse "/itm" "http://cp1.internal.cnx-dev.net:32080/itm" 
ProxyPass "/community_suggestions/api/recommend/communities" "http://cp1.internal.cnx-dev.net:32080/community_suggestions/api/recommend/communities" 
ProxyPassReverse "/community_suggestions/api/recommend/communities" "http://cp1.internal.cnx-dev.net:32080/community_suggestions/api/recommend/communities" 
ProxyPass "/appreg" "http://cp1.internal.cnx-dev.net:32080/appreg/" 
ProxyPassReverse "/appreg" "http://cp1.internal.cnx-dev.net:32080/appreg/" 
ProxyPass "/appregistry" "http://cp1.internal.cnx-dev.net:32080/appregistry" 
ProxyPassReverse "/appregistry" "http://cp1.internal.cnx-dev.net:32080/appregistry"

Learn more about configuring Orient Me in Configuring the Orient Me component.

Set up Activities Plus

Prerequisites for installing Activities Plus are:
To install or upgrade it, run:
helm upgrade kudos-boards-cp 
component_pack_installation_folder/hybridcloud/helmbuilds/kudos-boards-cp-2.*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/kudosboards.yml
Once this is all set, add the following rules to your httpd.conf on your IBM HTTP servers and restart the service:
# proxy rules for activities plus 
RewriteRule ^/activities/service/html/(.*)$ /boards/activities/service/html/$1 [R] 
ProxyPass "/boards" "http://cp1.internal.cnx-dev.net:32080/boards" 
ProxyPassReverse "/boards" "http://cp1.internal.cnx-dev.net:32080/boards" 
ProxyPass "/api-boards" "http://cp1.internal.cnx-dev.net:32080/api-boards" 
ProxyPassReverse "/api-boards" http://cp1.internal.cnx-dev.net:32080/api-boards"

Starting with version 7, be sure that you have websockets enabled on your front proxy server.

If you are using Nginx, the configuration would look like this:
location /api-boards/ { 

                    proxy_pass https://connections1.internal.cnx-dev.net; 

                    proxy_http_version 1.1; 

                    proxy_set_header Upgrade $http_upgrade; 

                    proxy_set_header Connection "upgrade"; 

                }

Find more about Activities Plus in the section Integrating with Activities Plus.

Set up Connections Add-in for Microsoft Outlook

Prerequisites for installing HCLConnections Add-in for Microsoft Outlook is:
To install or upgrade the Connections Outlook Add-in, run:
helm upgrade connections-outlook-desktop 
component_pack_installation_folder/hybridcloud/helmbuilds/connections-outlook-desktop-*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/outlook-addin.yml
Once this is all set, add the following rules to httpd.conf for your IBM HTTP servers and restart the service:
# proxy rules for outlook add-in
Redirect "/outlook-addin" "/outlook-addin/" 
ProxyPass "/outlook-addin/" "http://cp1.internal.cnx-dev.net:31810/" 
ProxyPassReverse "/outlook-addin/" "http://cp1.internal.cnx-dev.net:31810/"

Finally, update the add-in docker environment variables.

These are located in the outlook-addin.yaml file. These are passed into the Outlook add-in docker instance on startup:

  • What must be overriden:
    • CONNECTIONS_URL - URL of your Connections environment without a trailing slash (eg https://my.connections.server.com). The same URL has to be used when generating secret in the first step.
    • CONNECTIONS_CLIENT_SECRET - Client secret generated by Connections when registering OAuth provider in the first step.
    • CONNECTIONS_CLIENT_ID - Client ID (aka. app ID) used when registering OAuth provider in Connections in the first step (default: hcl-cnx-office-addin)
  • What may be overriden:
    • CONTEXT_ROOT - The path to where the Outlook add-in is being served, relative to the CONNECTIONS_URL. Do NOT start or end with `/. (default: outlook-addin)
    • SUPPORT_URL - URL that a user can go to for support (help). (default: https://help.hcltechsw.com/connections/v7/connectors/enduser/c_ms_plugins_add_in_outlook.html)
    • CONNECTIONS_NAME – A custom name for the add-in..(default: 'HCL Connections')
    • EWS_HOSTNAME – The hostname for Exchange Web Services. Default: 'outlook.office365.com'
  • Take care about ingresses listed there. You should point to both frontend domain and internal domains, if both are used. Otherwise, only point to the one that is used in your case.

Enable Metrics with Elasticsearch

Component Pack for HCL Connections 7 comes with Elasticsearch 7 enabled by default.

If you are doing clean install, do all the tasks under Configuring the Elasticsearch Metrics component.

If you are on HCL Connections 6.5.0.1 or earler, and using ElasticSearch 5, there are two options:

Enable Microsoft Teams integration

See Setting up the Connections app for the Microsoft Teams client in the Integrating with Other Products section of this documentaion.

Enable Connections Add-in for Microsoft Outlook

See Making the Connections Add-in for Outlook available to users.