Page History
This page contains the information you should be aware of when you are upgrading to Magnolia 5.67.x from any previous and currently supported version, see the End-of-Life policy.
Before starting the upgrade, please read the release we recommend you read:
- Release notes for the version you are updating to
...
- as well as for all intermediate versions
- How to update
- Certified stack
If you are , the general upgrade procedure and the specific aspects. If migrating from Magnolia 4.4/4.5, please read read the migration documentation first. You can also contact us for migration support.
Table of Contents | ||||
---|---|---|---|---|
|
What to update
Anchor | ||||
---|---|---|---|---|
|
If you have an Enterprise license, add the new privacy modules that help you make your websites GDPR-compliant:.
Expand | ||||||
---|---|---|---|---|---|---|
| ||||||
|
Changes on add-on modules
Include Page | ||||
---|---|---|---|---|
|
Updated add on modules
With Magnolia 5.7 we also have updated the Backup module to version 2.3
...
. If you want to use the backup module, you must upgrade it to 2.3.
Anchor | ||||
---|---|---|---|---|
|
In Magnolia 5.7 we removed several add-on modules (not bundled). We recommend you remove them too.
This is the list of the add-on modules removed:
- magnolia-jndi-1.0.2
- magnolia-module-newsletter-bundle-2.2
- magnolia-module-webdav-2.1.3
- magnolia-templating-samples-5.4.1
See also
Jira | ||||||||
---|---|---|---|---|---|---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
You must remove the magnolia-module-webdav
module.
Jackrabbit 2.16 removed the HttpClient3 based WebDAV API and introduced a completely new WebDAV API.
You can do many common WebDAV tasks with light development. You can store web resources such as CSS and JS files, template scripts and many more items in a light module and edit them comfortably as local files with your favorite editor. When you are done with the changes, push and commit the files to Git and configure Magnolia to watch for changes in the remote Git directory. Magnolia will register changes in light modules instantly.
Anchor | ||||
---|---|---|---|---|
|
We have changed some names for field definitions. The name of a field definition is the node name if defined via JCR in the folder modules/some-module/fieldTypes
or the file name of a YAML based definition. Field definitions which have been defined via JCR and which we have renamed now are defined with YAML files. This was part of the initiative to reference fields by its "short" name with the property fieldType
(see Referencing fields).
If you have custom fields which reuse an existing Magnolia configuration via YAML include, YAML inherit, JCR extends or by decoration, your custom definition may be broken now if you reference to a field which has changed its name.
Expand | ||||||
---|---|---|---|---|---|---|
| ||||||
|
Use the Definitions app to check for problems.
Check the magnolia.properties
file
Between Magnolia 5.6.6 and Magnolia 5.7, the magnolia.properties
file has not changed.
Tip |
---|
When upgrading Magnolia, it is always worth comparing your |
Below are the latest versions of the magnolia.properties
files for the Magnolia 5.7.x series:
Artifact resource link | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Magnolia CE / Magnolia EE Standard *
Code Pro | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
*) Magnolia CE and Magnolia EE Standard use the same magnolia.properties
file.
Magnolia EE Pro
Code Pro | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
Apache Tomcat 9.0.8
If you use Apache Tomcat: we have upgraded to Apache Tomcat 9.0.8.
If you use another servlet container, check the certified stack for supported versions.
Anchor | ||||
---|---|---|---|---|
|
Jackrabbit 2.16.1
If you want to run Magnolia on Java 9 or 10, you must use Jackrabbit 2.16.1.
- jackrabbit-api-2.16.1
- jackrabbit-core-2.16.1
- jackrabbit-data-2.16.1
- jackrabbit-jcr-commons-2.16.1
- jackrabbit-spi-2.16.1
- jackrabbit-spi-commons-2.16.1
Vaadin 8.4.2
If you are migrating from Magnolia 5.5.x or lower, read the instructions for upgrading to Magnolia 5.6.x for custom modules and the widgetset.
- vaadin-compatibility-aceeditor-1.0
- vaadin-compatibility-ckeditor-1.0
- vaadin-compatibility-client-8.4.2
- vaadin-compatibility-context-menu-1.0
- vaadin-compatibility-expandingtextarea-1.0
- vaadin-compatibility-server-8.4.2
- vaadin-compatibility-shared-8.4.2
- vaadin-compatibility-themes-8.4.2
- vaadin-compatibility-tokenfield-1.0
- vaadin-server-8.4.2
- vaadin-shared-8.4.2
- validation-api-1.1.0.Final
Groovy 2.5
Include Page | ||||
---|---|---|---|---|
|
Other third-party libraries
- commons-lang3-3.7
- freemarker-2.3.38
- gson-2.2.2
- guice-4.2.0
- guice-multibindings-4.2.0
- jackson-databind-2.9.5
- jsoup-1.8.3
- mycila-guice-closeable-4.0
- mycila-guice-injection-4.0
- mycila-guice-jsr-4.0
- snakeyaml-1.21
We removed Apache Xerces (xercesImpl
) due to the fact that Java (since Java SE 7) already contains Java API for XML Processing (JAXP).
How to update
Recommendations
Update to the latest minor release version first before upgrading to the most recent major release.
A June 2018 example: a customer is considering an upgrade from 5.5.8 to 5.7. The correct upgrade sequence is: 5.5.8 →
→Artifact resource link rangeHigherVersion 5.6 groupId info.magnolia.bundle artifactId magnolia-bundle-parent label $version renderType display_only resourceType POM
→ 5.7.xArtifact resource link rangeHigherVersion 5.7 groupId info.magnolia.bundle artifactId magnolia-bundle-parent label $version renderType display_only resourceType POM - Update all external libraries required by the Magnolia release to which you intend to upgrade.
- Because the upgrade process takes time and is vulnerable to incidents, we recommend you minimize the risk by cleaning up your system, removing unused data, reindexing everything and doing a full backup first.
Tip |
---|
Once Magnolia is running, check the Definitions app for deprecated or problematic definitions. |
Updating manually
- 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. Also replace modules coming from the add-ons bundle (magnolia-enterprise-addons-bundle), in case you are using any of these.
Magnolia 5.7 updates numerous 3rd-party libraries, see Java 8, 9 and 10 runtime compatibility and library updates. - Remove any module JARs you had previously removed from your instances. Add any modules you might may have previously added.
We have removed several add-on modules. You must also remove some. See Remove outdated add-on modules. - Add new Magnolia modules. See Add the privacy modules.
- 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 customized your
magnolia.properties
files, compare the changes to the file in the new bundle. Properties may have been added and or removed. - Read Read the release notes for all intermediary intermediate versions for any additional update tasks.
- Restart the application server.
- Using In your browser, go to the Magnolia instances and run the Web web update.
Recommendations
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
Info title 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.
- Update all external libraries required by the Magnolia release to which you intend to upgrade.
- Carefully look for "change" or "changes for ..." sections in the release notes since.
- 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.
Adding the new privacy modules
If you have an Enterprise Pro license - add the new Privacy modules which helps you to adapt your websites compliant with the General Data Protection Regulation (GDPR).
Expand | ||||||
---|---|---|---|---|---|---|
| ||||||
|
The magnolia.properties file
When upgrading Magnolia - its is always worth to compare your magnolia.properties
file with the one coming from freshly released Magnolia bundles.
Here are the latest versions:
Magnolia CE:
..
Magnolia EE Standard:
..
Magnolia EE Pro:
..
WebDAV removal
Updating Maven managed webapps
In this section we assume that you use Maven to manage your (custom) webapp. How you do this depends on how you have organized your pom files.
Upgrading the versions of inherited BOM files
The most typical use case is that your custom webapp is based on one of Magnolias preconfigured webapps. The structure of the Maven project that manages your webapp may look like this:
Code Pro | ||
---|---|---|
| ||
custom-ee/
├── custom-ee-webapp
│ ├── pom.xml
│ └── src
└── pom.xml |
Line 3: custom-ee/custom-ee-webapp/pom.xml
is the pom file of your custom webapp.
Expand | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
|
Line 5: custom-ee/pom.xml
is the parent pom file of your custom webapp. This file manages the dependencies and their versions.
Expand | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
|
Note that the parent pom (custom-ee/pom.xml) manages all versions for Magnolia modules as well as for third-party libraries.
It imports info.magnolia.eebundle:magnolia-enterprise-bundle-parent
, which manages Magnolia Enterprise module versions and imports the following:
info.magnolia.bundle:magnolia-bundle-parent
- manages Magnolia CE module versions.info.magnolia.boms:magnolia-external-dependencies
- manages third-party library versions.
If the pom files for your custom webapp are organized as shown in this example, you only need to change one property. In the <properties>
section of your parent pom, change the version of the magnoliaBundleVersion
property:
Code Pro | ||||
---|---|---|---|---|
| ||||
<properties>
<magnoliaBundleVersion>5.7.1</magnoliaBundleVersion>
<foobarModuleVersion>1.2</foobarModuleVersion>
<javaVersion>1.8</javaVersion>
</properties> |
Line 2: Set the magnoliaBundleVersion
to your required version. That is all you need to change in the pom files of your webapp.
Checking the Maven dependency tree
Regardless of how your Maven project is organized, building the Maven dependency tree helps you analyze the versions of all the Magnolia modules and all the third-party libraries of your custom webapp.
Open a shell, go to the directory of your webapp and execute the Maven command for the dependency tree:
Code Block |
---|
cd /Users/jdoe/dev/repo/custom-mgnl-webapps/custom-ee/custom-ee-webapp
mvn dependency:tree |
...
Anchor | ||||
---|---|---|---|---|
|
Other issues
Tomcat 8 using BCEL may throw class format exception
Multiexcerpt include | ||||
---|---|---|---|---|
|
If you encounter other problems, check For other known issues please see the Known issues page.
Further reading
...
Virtual URI mappings not working if too many are configured
To mitigate an issue caused by having more than 500 configured virtual URI mappings in light modules, a WARN-level message is now logged when a DirectoryWatcher
overflow occurs (MAGNOLIA-7762). We recommend to keep the number of files in a single folder below 100 and to use folder hierarchies whenever possible. For the upcoming fix, see MAGNOLIA-7798.
...