Reverse Proxy¶
Huddo is served from the /huddo path of a single hostname, and the in-cluster Ingress does the fine-grained routing between apps. That means one location /huddo block on your front proxy covers everything — every app and the WebSocket — plus two root-level paths for the MCP server's OAuth discovery.
This configuration is the same for every deployment: Component Pack, standalone Kubernetes, and adding Huddo to an existing Boards install.
| Path | Routed by the Ingress to |
|---|---|
/huddo |
core |
/huddo/ideas |
ideas |
/huddo/wikis |
wikis |
/huddo/attachments |
attachments |
/huddo/discussions |
discussions |
/huddo/notifications |
notifications |
/huddo/editor |
editor |
/huddo/spaces |
spaces |
/huddo/links |
links |
/huddo/search |
search |
/huddo/drawio |
drawio, when enabled |
/huddo/socketcluster |
socketcluster |
nginx¶
The map switches Connection to upgrade only for WebSocket requests, so the same block serves both https and wss.
Add the map in the http {} context, alongside the other proxy_* defaults:
Warning
nginx refuses to start if map is placed inside a server {} or location {} block.
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
Then add the location block to your listen 443 server block:
location /huddo {
proxy_ssl_server_name on;
proxy_pass http://[KUBERNETES_HOST]:[INGRESS_PORT]/huddo;
proxy_redirect off;
proxy_pass_request_headers on;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
Where:
[KUBERNETES_HOST]is the hostname/IP of the master in your cluster[INGRESS_PORT]is the port of your Traefik ingress controller (e.g.32080)
Dedicated hostname¶
If Huddo has the hostname to itself rather than sharing it with HCL Connections, redirect the root to /huddo so users landing on the bare domain reach the app:
location = / {
return 302 https://$host/huddo;
}
The /huddo prefix is built into the images and cannot be removed, even on a dedicated hostname.
MCP OAuth discovery¶
The MCP server at /huddo/mcp publishes two OAuth discovery documents at the host root, outside /huddo. AI assistants fetch them before signing in, so forward them to the same ingress:
location /.well-known/oauth-authorization-server/huddo {
proxy_pass http://[KUBERNETES_HOST]:[INGRESS_PORT];
proxy_set_header Host $host;
}
location /.well-known/oauth-protected-resource/huddo/mcp {
proxy_pass http://[KUBERNETES_HOST]:[INGRESS_PORT];
proxy_set_header Host $host;
}
proxy_pass has no path, so nginx forwards the full original path, which is what the ingress routes. Boards' discovery documents (/.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource, with no suffix) are separate paths and unaffected.
Alongside Huddo Boards¶
If Boards runs on the same hostname, its /boards and /api-boards blocks are unchanged — the Huddo block does not overlap them. Longest-prefix matching keeps the three separate.
Other proxies¶
Any reverse proxy works. Whatever you use must:
- forward
/huddoto the Ingress without stripping the prefix — the apps are built with/huddoas their base path - preserve the original
Hostheader, so the apps generate correct absolute URLs - support the WebSocket upgrade on
/huddo/editorand/huddo/socketcluster(on Apache httpd this needsmod_proxy_wstunnel) - allow a long read timeout, so idle WebSocket connections are not dropped
- append the client address to
X-Forwarded-For, so Links can place clicks (Apache httpd'smod_proxydoes this by default)
For the wider HCL Connections proxy setup, the Boards httpd guide covers the same ground for an IHS/httpd front end.
Redirecting old Wikis links¶
If you have migrated HCL Connections Wikis, add this redirect so existing links resolve to the migrated pages:
location ~ ^/wikis/home/?(.*)$ {
rewrite ^/wikis/home/?(.*)$ /huddo/wikis/migrated/$1 redirect;
}
Once HCL Connections Wikis is switched off, also redirect attachment downloads to the migrated files:
location ~ ^/wikis/(form|basic)/(anonymous/)?api/(wiki|library)/[^/]+/(page|document)/[^/]+/attachment/([0-9a-fA-F-]+)/media {
return 302 /huddo/wikis/migrated/connections/attachment/$5;
}
This covers the download links on a page's Attachments tab, images and links inside page bodies, and the links the Wikis API returns. Do not add it while Connections Wikis is still running: it would take over Connections' own attachment downloads. An attachment that was not migrated, or that the reader cannot see, shows a "not found" page.
Old Confluence links¶
If you have migrated Confluence, point the old Confluence host at Huddo once Confluence is switched off, and rewrite every path onto /huddo/wikis/migrated/confluence/:
server {
listen 443 ssl;
server_name confluence.example.com; # the old Confluence host
# ssl_certificate / ssl_certificate_key for that host
# Confluence served under a context path (e.g. /confluence)? Strip it:
# rewrite ^/confluence/(.*)$ https://[HUDDO_HOST]/huddo/wikis/migrated/confluence/$1 redirect;
rewrite ^/(.*)$ https://[HUDDO_HOST]/huddo/wikis/migrated/confluence/$1 redirect;
}
nginx keeps the query string, which some Confluence links depend on. These forms resolve to the migrated page or file:
| Old link | Resolves by |
|---|---|
/display/KEY/Page+Title |
space key and title |
/display/KEY |
space key, to the migrated wiki |
/spaces/KEY/pages/12345/Page+Title |
page id |
/pages/viewpage.action?pageId=12345 |
page id |
/pages/viewpage.action?spaceKey=KEY&title=Page+Title |
space key and title |
/x/AbCd (Share links) |
page id |
/download/attachments/12345/file.pdf |
page id and filename, to the migrated file |
/download/thumbnails/12345/image.png |
page id and filename, to the migrated file |
An #anchor on the link is kept. A page that was not migrated, whose title no longer matches, or that the reader cannot see opens its migrated wiki instead. A space that was not migrated, or whose wiki the reader cannot see, shows a "not migrated" message.
An attachment link opens the latest version of the migrated file, whatever ?version= it carries. If the reader cannot see the file's page, it opens the migrated wiki instead. An attachment that was not migrated shows the "not migrated" message.