Upgrading from Magnolia 6.2 to 6.4

Upgrade to the latest patch of your current Magnolia version (for example, if on 6.2.x, go to the latest 6.2.x before starting the 6.2→6.4 upgrade).

Clean and optimize your Magnolia instance: remove unused modules/data, reindex JCR.

Back up your system.

Test the backup and the ability to restore or roll back.

Verify that your Java environment is 17 (or newer, as certified by Magnolia 6.4).

Review the certified stack again for server, servlet container (Tomcat 10/11), and database support.

If you have custom code, add the rewrite-maven-plugin to your pom.xml file to automate the migration from javax to jakarta packages. This step effectively alters your code.

Update the parent pom.xml in your webapp. Set <magnoliaBundleVersion> to 6.4.0.

If you use extension modules, either update their versions individually or use the latest extensions BOM compatible with 6.4.

Replace javax.* dependencies with their Jakarta EE 10 equivalents in all modules.

Compare your magnolia.properties file to the current defaults for 6.4 and merge in any required new properties. See the Magnolia CE and DX Core base files.

If using custom Docker images, update to use base images certified for Magnolia 6.4.

Update all publishing receiver and external configuration sources as required. Since 6.3, Magnolia uses MicroProfile Config, adding state-of-the-art flexibility for external instance configuration. Magnolia expects MicroProfile-managed publishing receiver configs for instance clustering.

magnolia.publishing.receivers[0].name=magnoliaPublic
magnolia.publishing.receivers[0].url=http://{host}:{port}/magnoliaPublic (1)
magnolia.publishing.receivers[0].enabled=true

If you use AI Accelerator or Cloudinary External DAM, obtain your new 6.4 license and set it in your instances before launching Magnolia for the first time.

If you configured IP security, update your filter configuration to use MicroProfile config. Magnolia 6.4 no longer bootstraps ipSecurity by default. Either remove the filter manually or migrate the configuration to MicroProfile; otherwise, logs will contain repeated warnings. See IP security.

magnolia.server.ipSecurityRules[0].ip=*
magnolia.server.ipSecurityRules[0].methods[0]=GET
magnolia.server.ipSecurityRules[0].methods[1]=POST
magnolia.server.ipSecurityRules[0].methods[2]=DELETE
magnolia.server.ipSecurityRules[0].methods[3]=PATCH
magnolia.server.ipSecurityRules[1].ip=127.0.0.1
magnolia.server.ipSecurityRules[1].methods[0]=GET
magnolia.server.ipSecurityRules[1].methods[1]=POST
magnolia.server.ipSecurityRules[1].methods[2]=DELETE
magnolia.server.ipSecurityRules[1].methods[3]=PATCH

If you have custom Java-based REST endpoints, update them to use the REST 3.0+ packages, such as:

Global Search replaces Find Bar and is managed in the periscope-core module.

The forms in your project are likely eligible for the New UI Forms. If you use JavaScript fields from the JavaScript UI module together with the New UI Forms, add the dependency below and remove the legacy implementationClass.

Remove old compatibility modules (categorization, diff, workflow compatibility, etc.).

If you use CKEditor 4 customizations, we recommend you migrate to CKEditor 5. New UI forms require CKEditor 5, which is the default in Magnolia 6.4.

If you use SSO 3.1 or earlier, you must migrate configurations per the model introduced in 4.0.0. This includes compatibility adjustments, mandatory configuration changes, removal of certain classes, optional enhancements like JCR-based fallback login, and considerations for users of the SSO Login Extension module. For specific actions and modifications needed to ensure a smooth upgrade, see Upgrading to SSO 4.0.0. Once these steps are followed, you can upgrade to Magnolia 6.4-compatible version SSO 5.0.

If you use Hybrid Assets incubator, the functionality offered by the incubator module is replaced by DAM 5.0 and later. If you used the incubator module, you can optionally use the migration scripts to move your assets to the new implementation.

If you use DAM Focal incubator (dam-focal): In 6.2 and 6.3, DAM Focal was provided as an incubator module. In 6.4, it is promoted to a DX Core extension with a new module name image-focal. The Magnolia 6.4-compatible version of this extension is 2.0. To upgrade, uninstall the dam-focal incubator module and update dependency management to use the image-focal extension version 2.0.x. Existing focal point data is preserved when switching modules.

If you use Live Copy, Dynamic Forms, or other incubator modules that configured a custom I18nAuthoringSupport in JCR, you must provide it via your module descriptor from 6.3 on. Deprecated methods have been removed and default implementations consolidated. Configure your class as a regular component mapping instead of an observed JCR component.

<component>
  <type>info.magnolia.ui.api.i18n.I18NAuthoringSupport</type>
  <implementation>com.custom.i18n.CustomI18nAuthoringSupport</implementation>
  <scope>singleton</scope>
</component>

If you use Content Editor module, migrate all v1 definitions to v2 and update multilanguage stories as needed.

If you use CTSX DeepL Translator incubator, move the translation provider configuration from /modules/content-translation-support-ext-deepl/config/Deepl to /modules/content-translation-support-ext-deepl/config/translationProviders/Deepl.

Start Magnolia 6.4 in a non-production (staging) environment.

Review and update group and role assignments: Magnolia roles and groups changed in 6.3 and later. Magnolia 6.3 introduced a unified role naming convention <module>-<privilege> (for example, pages-publisher, admincentral-editor). Review and update your user groups and roles to align with the new scheme.

Update all site/multisite configurations. Since Magnolia 6.3, multisite definitions work like any other definition type: they’re collected in a conventional registry, support YAML definitions natively, and are displayed in the Definitions app. YAML is now required for new features, and decorations of legacy JCR multisite configurations are no longer supported.

Review configuration decorations. All YAML decorations must have config in the filename. Make sure that your decorating configuration files have config in the filename, for example, /rest-services/decorations/cache/config.contentCaching.yaml.

Update App Launcher layout.

Review app workbench and search configuration. In-app search and filters are now enabled by default in browser subapps. If your custom apps rely on column-level filterComponent definitions or have custom data providers, update them to use the new workbench-level filters structure and update your custom data provider implementation to support the unified search behavior.

For custom deletion actions in apps: Magnolia 6.4 standardizes deletion dialogs and confirmation steps. For most users, no configuration changes are needed and the existing actions and dialogs are automatically updated. If you have extended default actions, you may have to revalidate behavior. This automatic replacement doesn’t apply to the following apps: Campaign Publisher, Configuration, Cookies, External DAM, JCR, Security, and Tags.

Update your delivery endpoint definitions. Ensure each endpoint uses the correct $type (jcrDeliveryEndpoint_v2 or jcrPagesDeliveryEndpoint_v2) and note the new defaults for the following properties: depthInReferencedNode = 1 and maxLimit = 100.

Magnolia 6.4 brings a New UI (based on React) to the forms in content apps, automatically. Most form features are supported in the New UI. If a feature isn’t supported, the form falls back to the Vaadin UI. Because of this, typically all forms work. You don’t need to make any changes to your forms.

Use the Definitions app, Problems tab, and logs to audit for unsupported, deprecated, or un-migrated configs/modules.

Run a full regression and smoke test according to your test plan (core features, content management, user logins/roles, publishing, custom integrations, REST endpoints, asset upload/download, etc.).