Upgrading to Magnolia 5.6.x

This page provides the most essential information you should be aware of when upgrading to Magnolia 5.6.x from any previous and currently supported version. Before commencing with 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 points listed below.

If you are you migrating from Magnolia 4.4/4.5, please have a look at the migration documentation first. You may also contact us for migration support.

General procedure

Please note depending on the number of versions in the version workspace, the upgrade to 5.6.x from any version below may take from 20 to 30 minutes since all of the versions have to migrate to a new structure.

To update Magnolia

Stop the application server.
Extract the new Magnolia bundle.
Replace JAR files in the WEB-INF/lib folder of your old Magnolia instances with new JARs from the bundle.
Remove any module JARs you had previously removed from your instances. Add any modules you might have added.
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.
If you customized magnolia.properties files, compare the changes to the file in the new bundle. Properties may have been added and removed.
Read release notes for all intermediary versions for any additional update tasks.
Restart the application server.
Using your browser, go to the Magnolia instances and run the Web update.

Recommendations

Update to your latest minor release version first before upgrade to recent major release. For example as of May 2017, a customer would like to upgrade from 5.4.1 to 5.5.4 (latest release at that time), then the correct sequence would be 5.4.8 → 5.4.12 → 5.5.4 instead of 5.4.8 → 5.5 → 5.5.3.
Carefully look for "change" or "changes for ..." sections in the Release notes since that changes is necessary in this specific case when you are updating from 5.4.1 solely.
Because upgrading process takes time and vulnerable to incidents, please minimize the risk by clean up your system, remove unused data, reindex everything and do a full backup first.

Specific points

BOM

2DO

Vaadin

Ugrading from Vaadin 7 to Vaadin 8

2DO

The widgetset in EE Pro

If you had EE Pro 5.4.x or previous and are installing EE Pro 5.6: Due to component personalization bringing in new features to the page editor, you must replace the widgetset in the magnolia.properties file. Either replace or add (depending on the update path):

magnolia.ui.vaadin.widgetset=info.magnolia.widgetset.MagnoliaProWidgetSet

Apache Derby vs H2

The default JCR persistency layer in Magnolia 5.6 is H2, 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

If you used a different database before upgrading to Magnolia 5.6, make sure you keep your magnolia.repositories.jackrabbit.config setting. For Apache Derby, for example this would be:

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

Using STK?

Standard Templating Kit (STK) was deprecated on September 15, 2017 and will reach end of life on December 31, 2018. The replacement for STK is Magnolia Templating Kit (MTK), first released with Magnolia 5.4 on July 3, 2015. MTK is quicker to learn than STK and requires fewer skills. MTK is aimed at the increasing number of front-end developers who looked for something leaner and less time-consuming. MTE is front-end framework agnostic, which means you can integrate it with any modern framework such as Bootstrap or Foundation.

With the the release of Magnolia 5.6 we will stop producing preconfigured bundles and webapps with the STK based demo. If you still rely on STK, see how to add STK to your bundle.

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>

log4j.xml

Add the log configuration for org.reflections

...
 <category name="org.apache.jackrabbit">
    <priority value="WARN" />
  </category>
 <!-- Reflections library spoils logs with hundreds of harmless warnings; tries to look into native libs but none of its DefaultUrlTypes can handle them. -->
  <category name="org.reflections">
    <priority value="ERROR" />
  </category>
  <category name="com">
    <priority value="WARN" />
  </category>
...

Known issues

Allocate more JVM memory

Magnolia 5.6 ee-bundle may require you to allocate more memory the Java Virtual Machine (JVM). If you see a java.lang.OutOfMemoryError in the startup log or the system stops responding during installation, increase the Java heap size. The default maximum heap size is 512M. Try a higher amount such as 1024M. We are working on uncovering the root cause for the increased memory need.

See: Java out of memory

The Show action in the Configuration app doesn't open the correct location

When selecting properties in a definition that are actually extended from another node in the config workspace, opening the definition in the Configuration app will not work correctly, as the underlying node/property doesn't exist. For example,

/.magnolia/admincentral#app:definitions-app:;app~site@subApps/browser/actions/addFolder/icon:treeview
points to config:/modules/site-app/apps/site/subApps/browser/actions/addFolder/icon .
but all the actions are inherited from /modules/ui-admincentral/apps/configuration/subApps/browser via extends.

Other issues

For other known issues please this this the Known issues page.

Page tree