Breaking changes and requirements
What an upgrade asks of a deployment: the changes that need a configuration edit, a new resource or a migration before or after the move. Each entry says who it is for, because the two audiences rarely overlap — an operator does not care that a CSS utility was renamed, and a plugin author does not deploy the database.
What a release brings is listed separately, under Upgrade Guide.
Only the releases still ahead of you
Anything older than 8.46 is treated as history. A deployment upgrading today moves from 7.10.6 to one of the LTS releases, so the breaking changes of 8.4 through 8.44 were relevant when deployments were actually moving through those versions. They remain in the project's CHANGELOG.
8.54 - Core utility layer moved to Tailwind v4 Developers
Tailwind CSS v4 emits a utility layer beside the existing Bootstrap and core.scss cascade. Plugins may use the safe-listed utility classes without adding Tailwind to their own build; see src/themes/tailwind.css.
Plugins using the old utility names have to migrate:
| Replace | With |
|---|---|
flex-grow | flex-1 |
border-none | border-0 |
rounded | rounded-md |
rounded-lg | rounded-xl |
rounded-t | rounded-t-md rounded-b-none |
Nothing here affects a deployment that does not ship its own plugin styles.
8.50 - Guided tours moved back into the core UI Operators
Guided tours no longer ship as a separate repository and container image - they are part of the core UI. A deployment that ran the separate image can stop doing so.
They are off by default. To keep them, set the feature toggle:
io.ox/core//features/guidedTours=true
The feature itself is described under Onboarding and devices.
8.49 - OX Count can be deployed centrally Operators
Only relevant where OX Count is part of the deployment. The App Suite-specific UI files moved back into the core UI, so the OX Count server can focus on collection and its own dashboards - which is what allows several App Suite deployments to share one central OX Count.
Migration steps:
# replace the old enable flag with the standard feature toggle
io.ox/core//features/count=true
Then remove the count-specific entry from the UI service's baseUrls configuration.
Settings that changed with it:
| Old | New |
|---|---|
io.ox/core//count/enabled | io.ox/core//features/count |
io.ox/core//count/disabled (dev/debug) | removed |
tracker/url, tracker/enabled | removed, both were deprecated |
count/delay | count/backgroundInterval (-1 disables background collection while still allowing explicit posts, such as NPS) |
8.46 - The UI container is a node.js service Operators
The former "home container" - a static nginx server delivering UI assets - has been replaced by a Fastify-based node.js service. Two consequences need planning:
- BIMI requires a database to cache records and logos, where the feature is enabled
- Memory limits must be reviewed. The nginx service only served static files; the node.js service needs more room, especially with BIMI on. The default is
256Mifor both request and limit, and the chart deploys two instances by default. For serving static files alone, one instance is enough.
A CPU request is still defined but no CPU limit is set, which is intentional - it lets the service absorb short bursts without being throttled. Where cluster policy requires one, 1 CPU is a common choice.
This is what introduced the Backend-for-Frontend pattern: UI-adjacent work no longer has to be routed through the Java middleware. BIMI is the first feature built on it, and the architecture notes describe the shape.
8.46 - JWT issuing moved from Switchboard to the core UI Operators
The core UI service now issues JWTs, taking the job over from Switchboard. The keys it needs, and how to generate them, are described under JSON Web Key Set; the settings on both sides are in the same authentication guide.
The CHANGELOG entry for this release links a migration guide on the older /8/ui/ documentation. That page has no such section here, so the configuration reference above is the current source.