Huddo for HCL Connections Component Pack¶

Info

The huddo-cp Helm chart deploys Huddo into an existing HCL Connections Component Pack (CP) cluster. It reuses the MongoDB database and Redis/valkey cache that Component Pack already provides, and adds a SeaweedFS S3 service for file storage.

Installing Huddo on plain Kubernetes instead? Use the huddo chart.

Already running Huddo Boards? Start with Adding Huddo to an existing Boards install — there are prerequisites to meet on the Boards release first.

What gets deployed¶

Service	Deployed	Notes
`core`	always	Main UI, serves `/huddo`
`attachments`, `attachments-indexer`, `discussions`, `notifications`, `editor`	always	Supporting services
`acl`	always	Access control layer
`socketcluster`	always	Real-time WebSocket server
`s3`	always	SeaweedFS file storage, service name `huddo-s3`
`ideas`	`products.ideas.enabled` (default `true`)	Huddo Ideas
`wikis`	`products.wikis.enabled` (default `true`)	Huddo Wikis
`spaces`	`products.spaces.enabled` (default `true`)	Huddo Spaces
`search`, `search-worker`, `opensearch`	`products.search.enabled` (default `true`)	Cross-app search
`drawio`	`global.drawio.enabled` (default `false`)	Diagram editor for Wikis
`user`, `provider`, `licence`	`sharedServices.deploy` (default `true`)	Set `false` when adding to an existing Boards install
`wikishift`	`wikishift.enabled` (default `false`)	Wikis migration utility
`boards-*`	`products.boards.enabled` (default `false`)	See Adding Huddo Boards
`activity-migration`	`activity-migration.enabled` (default `false`)	Connections Activities ➡️ Boards migration

Prerequisites¶

HCL Component Pack is installed and running
WebSphere environment with Web Server (or another reverse proxy)
kubectl is installed and configured
helm is installed
SMTP gateway for email notifications, if required
Access to our images in Quay.io

Install into the connections namespace

Huddo reads the connections-env ConfigMap, the mongo-secret x509 certificate and the cache secret that Component Pack creates. None of them cross namespaces, so the release must live in the same namespace as Component Pack — connections.

Every command on this page uses --namespace connections.

URLs¶

Huddo is served from a single /huddo path on your Connections host — for example https://connections.example.com/huddo. We refer to this as HUDDO_URL below.

The /huddo prefix is fixed

The published images are built with /huddo as the application base path, so it cannot be changed. The chart's default values ship bare paths (/, /ideas, /wikis), which will not work — set the /huddo paths shown in the config file on every service.

Individual services are routed under that prefix by the in-cluster Ingress, so a single location /huddo block on your front proxy is enough — see Reverse Proxy for the routing table and the nginx configuration.

Setup OAuth¶

Follow our instructions to register an HCL Connections OAuth client for Huddo.

The OAuth Callback URL for this configuration is https://[HUDDO_URL]/auth/connections/callback.

Other authentication providers (Domino, DX, Microsoft AD) are also supported — see Provider options.

Storage¶

S3¶

The chart deploys a SeaweedFS S3 service (huddo-s3) with the bucket huddo. Follow the S3 storage setup to prepare the NFS mount, or set s3.persistence.storageClassName if your cluster has a dynamic provisioner.

OpenSearch¶

Cross-app search deploys an OpenSearch cluster (huddo-opensearch) that needs a volume of its own, prepared the same way as the S3 mount. Create the export before the first deploy — the chart's init container sets ownership on it, but will not create it:

opensearch:
  persistence:
    nfs:
      server: '[NFS_SERVER_IP]'
      path: /pv-connections/huddo-opensearch

Set opensearch.persistence.storageClassName instead if your cluster has a dynamic provisioner, or products.search.enabled: false to leave search out of the release. See Search.

Mongo¶

Huddo uses the MongoDB database already deployed by Component Pack, authenticating with X.509 certificates. Connection details come from the connections-env ConfigMap and the mongo-secret certificate, both created by Component Pack — nothing to configure.

One step is required: authorising the certificate user for the Huddo databases.

Creating the MongoDB user¶

You must create a dedicated X.509 user in MongoDB's $external database. Connect to the primary node (it must not be a secondary).

First, find the primary:

kubectl exec -it mongo5-0 -c mongo5 -n connections -- mongosh \
  --tls \
  --tlsCertificateKeyFile /etc/ca/user_admin.pem \
  --tlsCAFile /etc/ca/internal-ca-chain.cert.pem \
  --host mongo5-0.mongo5.connections.svc.cluster.local \
  --authenticationMechanism=MONGODB-X509 \
  --authenticationDatabase '$external' \
  -u 'C=IE,ST=Ireland,L=Dublin,O=IBM,OU=Connections-Middleware-Clients,CN=admin,emailAddress=admin@mongodb' \
  --eval "rs.status().members.find(m => m.stateStr === 'PRIMARY').name"

Then reconnect replacing the --host with the primary hostname, and grant access to the kudos-boards user:

db.getSiblingDB("$external").runCommand({
  grantRolesToUser: "C=IE,ST=Ireland,L=Dublin,O=IBM,OU=Connections-Middleware-Clients,CN=kudos-boards,emailAddress=kudos-boards@mongodb",
  roles: [
    { role: "readWrite", db: "huddo-attachments" },
    { role: "readWrite", db: "huddo-discussions" },
    { role: "readWrite", db: "huddo-notifications" },
    { role: "readWrite", db: "huddo-ideas" },
    { role: "readWrite", db: "huddo-wikis" },
    { role: "readWrite", db: "huddo-user" },
    { role: "readWrite", db: "huddo-licence" },
    { role: "readWrite", db: "huddo-spaces" }
  ],
  writeConcern: { w: "majority", wtimeout: 5000 }
})

Validate the user was updated correctly:

db.getSiblingDB("$external").getUser("C=IE,ST=Ireland,L=Dublin,O=IBM,OU=Connections-Middleware-Clients,CN=kudos-boards,emailAddress=kudos-boards@mongodb")

Do not use the admin certificate in production

Setting global.env.MONGO_CERT_USER: admin reuses the Component Pack superuser and skips the grant above entirely. It gives every Huddo pod full read/write access to all Component Pack databases, not just Huddo's. Use it only on a throwaway development environment.

Enabling Huddo Boards in this release

Add { role: "readWrite", db: "boards-app" } and { role: "readWrite", db: "boards-notification" } to the roles above.

Licence Key¶

A licence key is required, obtained from https://store.huddo.com. Set it as licence.env.LICENCE in your config file. The key must include the products you deploy (huddo.wikis, huddo.ideas).

Secrets¶

Image pull secret — follow the image access guide, or let the chart create it for you with imageCredentials (see Secrets & certificates).

SocketCluster secret — a shared secret signs the real-time connections. Create it before installing; the config file reads it from Kubernetes rather than holding the value:

kubectl create secret generic socketcluster-secret \
  --from-literal=socketcluster-secret=$(openssl rand -base64 32) \
  -n connections

Configuration¶

Download our config file and update the values inside.

Treat this file as a secret

Once filled in it holds your OAuth client secret, JWT secret, licence key, S3 keys and SMTP password. Keep it out of source control, or pass the sensitive values with helm --set or from Kubernetes secrets via global.envArray — as the file already does for SOCKET_CLUSTER_SECRET.

Kubernetes variables:

Key	Description
`global.imageTag`	Image tag to deploy — see releases
`global.imagePullSecret`	Name of the image pull secret created above
`global.env.HUDDO_URI`	`https://[HUDDO_URL]` (e.g. `https://connections.example.com/huddo`)
`global.env.S3_ACCESS_KEY`	Random string, must match `s3.accessKey`
`global.env.S3_SECRET_KEY`	Random string, must match `s3.secretKey`
`<service>.ingress.hosts`	`[CONNECTIONS_HOST]` (no protocol, e.g. `connections.example.com`) on every service
`s3.accessKey` / `s3.secretKey`	S3 credentials — change from the chart defaults for production
`s3.persistence.nfs.server`	IP address of the NFS server (e.g. `192.168.10.20`), or use `s3.persistence.storageClassName`
`opensearch.persistence.nfs.server`	NFS server for the search index, or use `opensearch.persistence.storageClassName`
`global.drawio.enabled`	Optional: `true` to add the draw.io diagram editor to Wikis. Also set `drawio.ingress`
`user.env.CONNECTIONS_CLIENT_ID`	OAuth client id, usually `huddo`
`user.env.CONNECTIONS_CLIENT_SECRET`	OAuth client secret as configured in this step
`user.env.CONNECTIONS_URL`	HCL Connections URL, e.g. `https://connections.example.com`
`user.env.CONNECTIONS_ADMINS`	Emails or GUIDs of users to grant admin permissions. e.g. `'["admin@example.com", "PROF_GUID"]'`
`licence.env.LICENCE`	Licence key from the Huddo Store
`notifications.env.EMAIL_HOST`	SMTP gateway hostname

All other variables — including email delivery, authentication providers, internal CA bundles and pod annotations — are described here.

Install¶

The release name must be huddo-cp

The chart's default SOCKET_CLUSTER_HOST is huddo-cp-socketcluster-worker, derived from the release name. Use a different release name only if you also override global.env.SOCKET_CLUSTER_HOST.

The chart is in our Quay.io registry. Log in with the same account you use for our images. Take <CHART_VERSION> from the huddo-cp chart history — the last row is the current version. A server-side dry run first will catch most config problems:

helm registry login quay.io
helm upgrade huddo-cp oci://quay.io/huddo/huddo-cp --version <CHART_VERSION> \
  -i -f ./huddo-cp.yaml --namespace connections --dry-run=server

Then check the rollout:

kubectl get pods -n connections -l release=huddo-cp

Proxy Config¶

Add a single location /huddo block to your front proxy — it covers every app and the WebSocket. See Reverse Proxy for the configuration.

Adding Huddo Boards¶

Huddo Boards can run inside this release, sharing the same user, provider, licence, acl and socketcluster services rather than deploying its own:

products:
  boards:
    enabled: true

This deploys boards-core (/api-boards), boards-webfront (/boards), boards-app, boards-notification and boards-events. When enabled:

Set global.env.APP_URI to the Boards UI URL and global.env.API_GATEWAY to the Boards API URL (HUDDO_URI stays the Huddo URL), and global.env.URL_BOARDS so Boards appears in the Huddo app switcher.
Boards uses a separate bucket, huddo-boards, on the same huddo-s3 endpoint. The chart only provisions the huddo bucket — create the second one out of band (aws s3 mb s3://huddo-boards) or rely on SeaweedFS creating it on first write.
Grant the Mongo x509 user access to boards-app and boards-notification, as noted above.
Boards-specific variables are documented with Boards.
Add /boards and /api-boards location blocks to your front proxy.

Warning

This is for customers without an existing Boards deployment. If you already run Boards as its own release, follow Adding Huddo to an existing Boards install instead — the chart refuses to render with both products.boards.enabled: true and sharedServices.deploy: false.

Integrations¶

HCL Connections¶

Migrate Wikis data¶

Follow the WikiShift instructions to migrate HCL Connections Wikis into Huddo Wikis.

Add a redirect to your proxy so old Connections Wikis links resolve to the migrated pages — see Reverse Proxy.

Upgrading¶

Update global.imageTag to the new release and re-run the upgrade command. Images are date-tagged, so pods are recreated automatically.

If you deploy a floating tag, restart the deployments manually:

kubectl rollout restart deployment -n connections -l release=huddo-cp