Huddo for Kubernetes¶

Deploying Huddo into a standalone Kubernetes cluster with the huddo Helm chart.

Info

Running HCL Connections Component Pack? Use the huddo-cp chart instead — it reuses the MongoDB and cache that Component Pack already provides.

Already running Huddo Boards? Start with Adding Huddo to an existing Boards install.

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
`user`, `provider`, `licence`	`sharedServices.deploy` (default `true`)	Set `false` when adding to an existing Boards install
`socketcluster`	always	Real-time WebSocket server
`redis`	always	In-cluster cache, service `huddo-redis`
`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
`wikishift`	`wikishift.enabled` (default `false`)	Wikis migration utility
`boards-*`	`products.boards.enabled` (default `false`)	Huddo Boards in the same release

Unlike the Component Pack chart, this one deploys no database and no file storage — you supply a MongoDB and an S3-compatible endpoint.

Prerequisites¶

Kubernetes is installed and running, with Traefik as the ingress controller
kubectl is installed and configured
helm is installed
A MongoDB database (5.0 or later) — self-hosted or managed, e.g. MongoDB Atlas
An S3-compatible file store — e.g. AWS S3, Google Cloud Storage, MinIO or SeaweedFS
A reverse proxy / load balancer terminating TLS in front of the cluster, unless you resolve certificates in Kubernetes
SMTP gateway for email notifications, if required
Access to our images in Quay.io

URLs¶

Huddo is served from the /huddo path of a single hostname — for example https://huddo.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 — even on a dedicated hostname. 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 — see Reverse Proxy for the routing table and the nginx configuration.

If Huddo has the hostname to itself, redirect the root to /huddo on your proxy — see Reverse Proxy.

Namespace¶

kubectl create namespace huddo

OAuth¶

Huddo authenticates users against an external identity provider. Register an OAuth application with one (or more) of the following:

Provider	Registration / documentation	Callback URL
HCL Connections	instructions	`https://[HUDDO_URL]/auth/connections/callback`
HCL Domino	instructions	`https://[HUDDO_URL]/auth/domino/callback`
HCL DX	instructions	`https://[HUDDO_URL]/auth/dx/callback`
Microsoft AD	instructions	`https://[HUDDO_URL]/auth/msad/callback`

The matching configuration keys are listed under Provider options.

Database & Storage¶

Mongo¶

Supply the connection details in global.env. The chart creates one database per service (huddo-user, huddo-licence, huddo-attachments, huddo-discussions, huddo-notifications, huddo-ideas, huddo-wikis and huddo-spaces) on the host you give it, so the user needs readWrite on each.

global:
  env:
    MONGO_PROTOCOL: mongodb+srv # or `mongodb` for a plain host:port connection
    MONGO_HOST: cluster0.example.mongodb.net
    MONGO_USER: huddo
    MONGO_PASSWORD: '[MONGO_PASSWORD]'
    MONGO_PARAMS: retryWrites=true&w=majority
    # MONGO_REPLICA_SET_NAME: rs0   # self-hosted replica sets only

S3¶

Any S3-compatible endpoint works. Create the bucket before installing.

global:
  env:
    S3_ENDPOINT: s3.eu-central-1.amazonaws.com
    S3_PORT: '443'
    S3_SECURE: 'true'
    S3_USE_SSL: 'true'
    S3_BUCKET: huddo
    S3_ACCESS_KEY: '[S3_ACCESS_KEY]'
    S3_SECRET_KEY: '[S3_SECRET_KEY]'

Redis¶

Deployed by the chart as huddo-redis, no configuration required. The image is Valkey (docker.io/valkey/valkey:9-alpine), a Redis-compatible server; set redis.image and redis.imageTag to use another image. The cache keeps no data on disk. To use an existing cache instead, set redis.enabled: false and point global.env.REDIS_CACHE_HOST (and REDIS_CACHE_PORT / REDIS_CACHE_PASSWORD if needed) at it.

OpenSearch¶

Cross-app search deploys an OpenSearch cluster as huddo-opensearch, claiming a 20Gi volume from your default storage class. Set opensearch.persistence.storageClassName to claim from another, or opensearch.persistence.size to change the size.

To point search and search-worker at an OpenSearch cluster you already run, set search.env.OPENSEARCH_NODE and search-worker.env.OPENSEARCH_NODE. To leave search out of the release entirely, set products.search.enabled: false and clear global.env.SEARCH_HOST. See Search.

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 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 huddo

TLS certificate — only if you resolve certificates in Kubernetes rather than at your proxy:

kubectl create secret tls huddo-domain-secret \
  --key </path/to/keyfile> --cert </path/to/certificate> --namespace huddo

Then add a tls block to each service's ingress.

Configuration¶

Download our config file and update the values inside.

Treat this file as a secret

Once filled in it holds your MongoDB password, 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.

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://huddo.example.com/huddo`)
`global.env.MONGO_*`	MongoDB connection details, as above
`global.env.S3_*`	S3 endpoint and credentials, as above
`<service>.ingress.hosts`	`[HUDDO_HOST]` (no protocol, e.g. `huddo.example.com`) on every service
`user.env.JWT_SECRET`	Random string of at least 32 characters, used to sign sessions
`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

The chart's default SOCKET_CLUSTER_HOST is huddo-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 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 oci://quay.io/huddo/huddo --version <CHART_VERSION> \
  -i -f ./huddo.yaml --namespace huddo --dry-run=server

Then check the rollout:

kubectl get pods -n huddo -l release=huddo

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, including the root redirect when Huddo has the hostname to itself.

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 writes to a separate bucket, huddo-boards, on the same S3 endpoint — create it before installing.
Boards uses the boards-app and boards-notification databases; grant the Mongo user readWrite on both.
Boards-specific variables are documented with Boards.
Add /boards and /api-boards location blocks to your front proxy.

Customers who already run Huddo Boards as its own huddo-boards release should keep it separate and set sharedServices.deploy: false instead — see Adding Huddo to an existing Boards install. The chart refuses to render with both products.boards.enabled: true and sharedServices.deploy: false.

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 huddo -l release=huddo