Installing
For DXP 2024.Q1 to 2025.Q4. After installing, connect AI Hub in Configuration.
- Before you start: the connector user
- With Docker (recommended)
- Without Docker
- The OAuth applications
- Pages the widget needs
- Check the install
- Upgrade and remove
Before you start: the connector user
Create the connector’s service user first. In Control Panel → Users and Organizations, add a user with screen name aihub-connector and any email (for example aihub-connector@example.com) and a long random password nobody keeps. Give it no roles — remove any Liferay added by default other than User.
The OAuth client extension names this user as its application’s user. Nothing ever acts as it: the module issues user tokens with LocalOAuthClient and never uses the client-credentials grant (a client-credentials request with the application’s own credentials is refused). So the user is an identity for the OAuth application, not an account with access.
Create the user before deploying the client extension. If the client extension is deployed first, Liferay logs NoSuchUserException … screenName=aihub-connector and creates no OAuth application. Creating the user afterward and redeploying is not enough — the configuration hasn’t changed, so Liferay doesn’t re-create it. Restart Liferay after creating the user.
With Docker (recommended)
The installer image holds the module for all eight releases and its client extensions, and writes them into a Liferay deploy folder you mount. It is a public package on GitHub Container Registry — liferay-aihub-legacy-connector — so it pulls without authentication.
Create the aihub-connector user first (above), then:
docker run --rm \
-v /path/to/liferay/deploy:/deploy \
-e LIFERAY_RELEASE=2025.q1 \
-e LIFERAY_URL=https://liferay.example.com \
ghcr.io/liferay-community-apac/liferay-aihub-legacy-connector:latest install
This writes the module jar and the liferay-aihub-legacy-token client extension into the deploy folder; Liferay installs them from there (module Active, the OAuth application created with its two read scopes). For the broader cell scopes, add -e CELL_SCOPES=true to also write liferay-aihub-legacy-token-cell (see Configuration → The cell’s scopes).
Print the configuration template with:
docker run --rm ghcr.io/liferay-community-apac/liferay-aihub-legacy-connector:2.9.1 config
The installer validates its inputs: missing variables, an unknown release, a non-http(s) URL and a missing /deploy mount each stop it with a message.
Without Docker
Build and package for the instance’s release from the connector repository:
DXP_RELEASE=dxp-2025.q1.29-lts aihub-legacy-module/scripts/aihub-token-module.sh package
package writes a zip with the bundle, the liferay-aihub-legacy-token client extension (and the optional -cell), a configuration template, a README and SHA-256 checksums. Use the package built for the instance’s release.
Then:
- Deploy the OAuth client extension.
liferay-aihub-legacy-tokencreates the OAuth application that issues the user token, acting as theaihub-connectoruser, with two read scopes:Liferay.Headless.Admin.User.everything.read(who the user is) andLiferay.Portal.Search.REST.everything.read(AI Hub’s Liferay Search). Remove the second from itsclient-extension.yamlif AI Hub’s agents shouldn’t search this Liferay. - Install the module. Copy
com.lgsapac.aihub.legacy.token-<version>.jarinto$LIFERAY_HOME/osgi/modules/on every node, readable by the user Liferay runs as. Liferay starts it with no restart; in the Gogo shell,lb aihub.legacylists it Active. - Configure the tokens — see Configuration.
The OAuth applications
| Application | Deploy | User token scopes | When |
|---|---|---|---|
liferay-aihub-legacy-token |
Always (default) | User (read) + Search (read) | The read-only user token — proves who the user is and lets AI Hub’s search node search as them. |
liferay-aihub-legacy-token-cell |
Optional | Adds taxonomy, objects, bulk, batch | Only where AI Hub’s agents should act on this Liferay as the user. See Configuration → The cell’s scopes. |
Pages the widget needs
- Theme: the widget is added by Liferay’s bottom-of-page include (as Click to Chat’s is). Liferay’s themes and custom themes built from them keep it; a theme whose
portal_normal.ftldrops<@liferay_util["include"] page=bottom_include />gets no widget. - Content Security Policy: allow AI Hub’s host in
script-src,style-src,img-srcandfont-src(the widget’s files come from AI Hub). With the proxy on,connect-src 'self'is enough; with it off, add AI Hub’s host toconnect-srctoo.
Check the install
- The module is Active: Gogo
lb aihub.legacy. - Instance Settings → AI Hub shows AI Hub Tokens (Legacy Connector) and AI Hub Chat (Legacy Connector).
POST /o/ai-hub-cell/v1.0/authorization-tokensas a guest returns 403 (404 means it’s off or not configured).- Once Chat or the Assistant is on, from a signed-in page with header
x-csrf-token: Liferay.authTokenit returnsaccessToken,serviceURLanduserToken.
Upgrade and remove
- Upgrade (by hand): uninstall the bundle first (Gogo
lb aihub.legacy, thenuninstall <id>), delete its file fromosgi/modules, and copy the new one in. The installer image upgrades in place — installing a newer image over a running one replaces the jar under the same name and Liferay updates the same bundle. - Remove: uninstall the bundle and delete its file, delete the
.configfile, and undeploy theliferay-aihub-legacy-tokenclient extension (and-cell, if deployed). The AI Hub Chat settings stay in the database but do nothing without the bundle.
Do the Remove steps before upgrading the DXP to 2026.Q1 or later, which has Liferay’s own cell and Click to Chat AI Hub provider. If you forget, the connector detects the cell and deactivates itself, logging a warning to uninstall it.