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

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. 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.
2. 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.
3. 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

Vaadin 8 and your custom modules

If upgrading from a pre-5.6 Magnolia version to the 5.6 branch, please follow the steps below to make sure that your custom modules are compatible with the UI in this branch. The first Magnolia release in this branch uses Vaadin 8.1.5 (see Vaadin 8.1.5 release notes and API docs).

1. Check whether and which of your modules contain Vaadin implementations.
2. If they do, get the https://github.com/vaadin/framework8-migration-tool .
   1. Install it locally and run like a Java jar afterwards.
   2. The script automatically changes the imports of the affected classes and thus – in the majority of cases – will make your module(s) compatible with Vaadin 8.
3. As stated on https://vaadin.com/docs/framework/migration/migrating-to-vaadin8.html, some dependencies have to be added in order to use compatible classes from Vaadin 7 (such as TextField .)
   

   Change the vaadin-server dependency from 

   <dependency>
   <groupId>com.vaadin</groupId>
   <artifactId>vaadin-server</artifactId>
   <version>7.7.6</version>
   </dependency>

   to 

   <dependency>
   <groupId>com.vaadin</groupId>
   <artifactId>vaadin-compatibility-server</artifactId>
   <version>8.0.0</version>
   </dependency>

   The full list of compatibility packages available for Framework 8:
   • vaadin-compatibility-server
   • vaadin-compatibility-client
   • vaadin-compatibility-client-compiled
   • vaadin-compatibility-shared
   • vaadin-compatibility-themes

   To be able to use the new Vaadin 8 features, add also the following dependency:

   <dependency>
   <groupId>com.vaadin</groupId>
   <artifactId>vaadin-server</artifactId>
   <version>8.0.0</version>
   </dependency>

Vaadin widgetsets

MagnoliaProWidgetSet vs MagnoliaWidgetSet

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

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

magnolia.ui.vaadin.widgetset=info.magnolia.widgetset.MagnoliaWidgetSet

Vaadin7WidgetSet

Normally, you won't need to do this since you have a Magnolia running for you. However, in case you are demoing your module as a custom Vaadin application, then you have to include Vaadin7WidgetSet :

1. Either annotate the UI class as such with @Widgetset("com.vaadin.v7.Vaadin7WidgetSet") ,

2. or do it in your GW[i]T configuration file by adding <inherits name="com.vaadin.v7.Vaadin7WidgetSet" /> .

Centralized Dependency Management for third-party modules (BOM)

Following the release of Magnolia 5.5.7, Magnolia 5.6.x allows you optionally to 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.

To use a BOM in your project, include the following code snippet in the dependency management section of the parent poms and adjust the version number accordingly:

<dependencyManagement>
 <dependencies>
  <dependency>
   <groupId>info.magnolia.boms</groupId>
   <artifactId>magnolia-external-dependencies</artifactId>
   <version>5.6</version>
   <type>pom</type>
   <scope>import</scope>
  </dependency>
 </dependencies>
</dependencyManagement>

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

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 the Known issues page.

Further reading

• https://vaadin.com/docs/framework/migration/migrating-to-vaadin8.html
• https://vaadin.com/blog/upgrading-to-vaadin-framework-8-part-1-of-2-
  https://vaadin.com/blog/upgrading-to-vaadin-framework-8-part-2-of-2-