Skip to content

Adding Huddo to an existing Huddo Boards install

If you already run Huddo Boards, this is the pathway to add Huddo (Ideas, Wikis, Discussions, Attachments) alongside it. Huddo reuses the platform services your Boards release already runs — user, provider and licence — so there is no second set of accounts, no second OAuth client, and no second login.

Upgrade Boards first

Both of the following are required before installing Huddo. The services talk over an RPC contract with no version handshake, so an older Boards release will fail at login rather than warn you.

Requirement Minimum
Helm chart huddo-boards-cp 2.3.4 or later (or huddo-boards 2.1.3 or later) — see Boards Helm Charts
Boards images global.imageTag of [RELEASE_DATE] or later — see Boards releases

The chart version matters because 2.3.4 added the optional SOCKET_CLUSTER_* bindings that let the Boards services discover Huddo's real-time server. The image date matters because the user, provider and licence images must carry the shared-login changes.


How it works

Installing Huddo in this mode deploys no user, provider or licence services. Instead the chart creates ExternalName Services that point Huddo's expected names at your existing Boards services:

Huddo expects Aliased to (huddo-boards-cp) Aliased to (huddo-boards)
huddo-user boards-user user
huddo-provider boards-provider provider
huddo-licence boards-licence licence

Consequences worth knowing up front:

  • One login. Users sign in through the Boards OAuth client and callback URL. You do not register a new client at your identity provider.
  • One licence key. The existing Boards key is reissued to cover the Huddo products — there is no separate Huddo licence.
  • One namespace. Huddo must be installed into the same namespace as the Boards release. ExternalName Services and the discovery ConfigMap do not cross namespaces.
  • Boards stays where it is. Huddo does not take over, move or redeploy your Boards services.

Step 1 — Upgrade Boards

Upgrade the Boards release to a chart and image tag that meet the minimums in the box above, then confirm the platform services are healthy:

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

Currently required: run the shared services at the Huddo release date

The current Huddo release needs changes to the user, licence and provider services that are not yet in a Boards release. Until they are, override those three image tags in your Boards release — see Huddo newer than Boards.


Step 2 — Have your licence key reissued

The Boards licence key must include the Huddo products (huddo.wikis, huddo.ideas). Contact support@huddo.com with your organisation details to have a new key issued, and set it as licence.env.LICENCE on the Boards release.

Users are refused access to Ideas and Wikis with a licensing error if this step is skipped.


Step 3 — Install Huddo

Use the chart that matches your Boards release, and follow its install guide for the full walkthrough — storage, OAuth, image access and the reverse proxy:

Your Boards release Install Huddo with Guide
huddo-boards-cp huddo-cp For HCL Connections
huddo-boards huddo For Kubernetes

Both charts support this mode, and each defaults its alias targets to the matching Boards service names, so no override is needed. Three things differ from a standalone install:

a) Turn off the shared services, so they alias to Boards instead of being deployed:

sharedServices:
  deploy: false

b) Leave Boards disabled in this release. It is off by default; the chart refuses to render if you enable it, because your existing release already provides Boards:

products:
  boards:
    enabled: false

c) Share the browser token key with Boards. Huddo keeps its token under localStorage huddo-token; Boards uses token. With one user service behind both, the tokens are interchangeable, so point Huddo at the Boards key and a login in either product serves both:

global:
  env:
    AUTH_STORAGE_KEY: token

d) Use the Boards S3 storage. Huddo needs no S3 service of its own: point it at the one your Boards release already uses, with its own huddo bucket alongside huddo-boards. The bucket is created on first start.

With huddo-cp, turn off its bundled SeaweedFS and point at the Boards one:

s3:
  enabled: false

global:
  env:
    S3_ENDPOINT: huddo-boards-cp-s3
    S3_PORT: '8333'
    S3_USE_SSL: 'false'
    S3_SECURE: 'false'
    S3_BUCKET: huddo
    S3_ACCESS_KEY: '[BOARDS_S3_ACCESS_KEY]'
    S3_SECRET_KEY: '[BOARDS_S3_SECRET_KEY]'

Copy the access and secret keys from s3.accessKey / s3.secretKey in your Boards release. You can then skip the S3 storage setup (NFS export or storage class) in the install guide.

With huddo, there is no bundled S3: set the same global.env.S3_* values your Boards release uses, keeping S3_BUCKET: huddo.

Boards must be on SeaweedFS

If your huddo-boards-cp release still serves files from MinIO, migrate it to SeaweedFS first. MinIO is deprecated and Huddo does not support it.

You can also skip the OAuth registration step in that guide — Huddo uses the Boards client. This includes Keycloak: configure it on the Boards release only.


Step 4 — Restart the Boards platform services

The Huddo release creates a huddo-socketcluster-env ConfigMap. Boards binds it with optional: true, so it is a dormant no-op until Huddo exists — and it is only picked up on the next pod start. Restart the three services — Boards deployments are named <release>-<service>, so for a release called huddo-boards-cp:

kubectl rollout restart deployment -n connections \
  huddo-boards-cp-user huddo-boards-cp-licence huddo-boards-cp-provider

Check the names for your release first if you are unsure:

kubectl get deployment -n connections -l release=huddo-boards-cp

Without this restart, login appears to succeed but the browser never receives its token.


Step 5 — Route /huddo on your proxy

Huddo is served from the /huddo path of your existing hostname. One location /huddo block covers every app and the WebSocket. For AI assistants, also forward the two root-level MCP OAuth discovery paths. See Reverse Proxy for the nginx snippet.

Your existing /boards and /api-boards blocks are unchanged.


Verify

  1. Check the Huddo pods are running:

    kubectl get pods -n connections -l release=huddo-cp
    
  2. Confirm the aliases resolve to the Boards services:

    kubectl get svc huddo-user huddo-provider huddo-licence -n connections
    

    Each should be of type ExternalName pointing at the matching Boards service.

  3. Browse to https://[YOUR_HOST]/huddo and sign in. You should land in Huddo without being asked to authorise a new application.


Troubleshooting

Symptom Cause
Login popup completes but the page never signs in The Boards user/licence/provider pods have not been restarted since Huddo was installed — see Step 4
Licensing error opening Ideas or Wikis The Boards licence key does not include huddo.wikis / huddo.ideas — see Step 2
helm upgrade fails naming products.boards.enabled Boards is enabled in the Huddo release as well as its own — set products.boards.enabled: false
Huddo pods cannot reach huddo-user Huddo was installed into a different namespace to Boards — the aliases do not cross namespaces
Login fails after upgrading only one of the two releases Boards images predate the shared-login changes — see the minimums at the top of this page
Errors from the shared services with Boards on its latest release The Huddo release is newer than the latest Boards release — see Huddo newer than Boards

AI assistants (MCP)

Huddo's MCP server signs users in through the shared user service, so its huddo-mcp OAuth client goes in your Boards values, in the same OAUTH_CLIENTS array as any boards-mcp entry. See AI Assistants (MCP).

Huddo newer than Boards

Huddo uses the user, licence and provider services from your Boards release. Normally the latest Boards release includes everything Huddo needs from them. Rarely, a Huddo release needs changes to these services that have not yet shipped in a Boards release. Then they are older than Huddo expects, even with Boards fully up to date.

If that happens, run them at the Huddo release date. Both charts deploy the same user, licence and provider images, so override just those three tags in your Boards release, leaving global.imageTag on the Boards release:

user:
  image:
    tag: '[HUDDO_RELEASE_DATE]'
licence:
  image:
    tag: '[HUDDO_RELEASE_DATE]'
provider:
  image:
    tag: '[HUDDO_RELEASE_DATE]'

Where [HUDDO_RELEASE_DATE] is the global.imageTag of your Huddo release. Run helm upgrade on the Boards release. This also restarts the three services.

Remove the overrides once a Boards release reaches that date, so the services follow global.imageTag again.