Upgrading to Magnolia 5.7.x

This page contains the information you should be aware of when upgrading to Magnolia 5.6.x from any previous and currently supported version, see the End-of-Life policy.

Before starting the upgrade, please read the release notes for the version you are updating to and all intermediate versions, the general upgrade procedure and the specific aspects. If migrating from Magnolia 4.4/4.5, please read migration documentation first. You can also contact us for migration support. 

General procedure

1. Stop the application server.
2. Extract the new Magnolia bundle.
3. Replace JAR files in the WEB-INF/lib folder of your old Magnolia instances with new JARs from the bundle.
4. Remove any module JARs you had previously removed from your instances. Add any modules you might have added.
5. Optional: Delete all indexes to give them a little boost. Delete the index folder under each workspace directory: repositories/magnolia/workspaces/<workspace>/index. Indexes are recreated on startup, which might take a while depending on the size of your repository.
6. If you customized magnolia.properties files, compare the changes to the file in the new bundle. Properties may have been added and removed.
7. Read release notes for all intermediary versions for any additional update tasks.
8. Restart the application server.
9. Using your browser, go to the Magnolia instances and run the Web update.

Recommendations

1. Update to your latest minor release version first before upgrade to recent major release. A June 2018 example: a customer was considering an upgrade from 5.5.8 to 5.7. The correct sequence would have been: 5.5.8 → 5.5.10 → 5.6.6 → 5.7

   Why we go that way?

   Because when a customer reports issues when migrating from 5.4.6 to 5.5, for instance, then we will support a workaround/patch and later release the fix also in 5.4.7. The fix of the issue in 5.4.6 when migrating is usually located in version handlers. Then at some point, we drop 5.4.x because of an outdated technology stack (such as Java versions and security support from third-party libraries), upgrade to 5.5.x, and the process repeats. So going with the latest release of each major release will free you from the issues and bring you the improvements.

2. Update all external libraries required by the Magnolia release to which you intend to upgrade.
3. Carefully look for "change" or "changes for ..." sections in the release notes since.
4. Because the upgrade process takes time and is vulnerable to incidents, please minimize the risk by cleaning up your system, removing unused data, reindexing everything and doing a full backup first.

Specific aspects

Default JCR persistency layer in Magnolia 5.6

The default JCR persistency layer in Magnolia 5.6 is the H2 database, which is reflected in the following setting of the magnolia.repositories.jackrabbit.config property in the magnolia.properties file:

magnolia.repositories.jackrabbit.config=WEB-INF/config/repo-conf/jackrabbit-bundle-h2-search.xml

magnolia.repositories.jackrabbit.config=WEB-INF/config/repo-conf/jackrabbit-bundle-derby-search.xml n your magnolia.properties file.  

Centralized Dependency Management for third-party modules (BOM)

In Magnolia 5.6.x you can – optionally – define third-party dependencies in a different way. Previously, dependency management information about third-party modules was defined in the parent poms of magnolia.main and magnolia.ui. You may now use a software BOM (Bill of materials) project instead. The project can then be imported in all modules. This ensures that the versions of the third-party modules are the same.

The BOM feature was made available for the first time in Magnolia 5.5.7. For further information on how to use a BOM in your project, please see the BOM for third-party modules page.

The magnolia.properties file

Check your magnolia.properties file for the presence of the following lines which configure a directory for loading file system resources and the file types Magnolia should observe in the classpath and reload on-change:

magnolia.resources.dir=${magnolia.home}
magnolia.resources.classpath.observation.pattern=.*\\.(ftl|yaml)$

Jackrabbit configuration

In order to enable getting an HTML excerpt in a query result, you should update the configuration files of your Jackrabbit instances. Add the two <param/> directives within your <SearchIndex> block.

<SearchIndex>
  <!-- more params here -->

  <!-- needed to highlight the searched term -->
  <param name="supportHighlighting" value="true"/>
  <!-- custom provider for getting an HTML excerpt in a query result with rep:excerpt() -->
  <param name="excerptProviderClass" value="info.magnolia.jackrabbit.lucene.SearchHTMLExcerpt"/>
</SearchIndex>

ClientErrorInterceptor not available

Since ClientErrorInterceptor does not exist in RESTeasy 3, its capabilities were removed from our client implementation, the REST client module. If you have been relying on such objects, you have to handle it in a different way.

Refine parent pom - when updating to Magnolia 5.6.3 or higher

Please be aware that the version numbers for the Magnolia main and UI projects are not in sync with the version number of the bundles starting with release 5.6.3.

If you are updating from an earlier version:
Projects based on an older maven archetype may not build correctly starting with Magnolia 5.6.3 - because the version of the Magnolia main modules is not the same as the Magnolia bundle anymore. If you experience a problem, please update your project parent pom.

WebDAV removal

...

Known issues

Other issues

For other known issues please see the Known issues page.

Further reading

• Migration from Vaadin Framework 7 to Vaadin Framework 8
• Upgrading to Vaadin Framework 8 (Part 1 of 2) 
• Upgrading to Vaadin Framework 8 (Part 2 of 2)