HTML Wrap |
---|
clear | both |
---|
width | 275px |
---|
align | right |
---|
class | menu |
---|
|
Related topics: |
This page contains the information you should be aware of when you are upgrading to Magnolia 5.7.x from any previous and currently supported version.
Before starting the upgrade, we recommend you read:
If you are migrating from Magnolia 4.4/4.5, read the migration documentation first. You can also contact us for migration support.
What to update
Anchor |
---|
| adding-privacy-modules |
---|
| adding-privacy-modules |
---|
|
Add privacy modules
If you have an Enterprise license, add the new privacy modules that help you make your websites GDPR-compliant:.
Expand |
---|
title | Click to see how to install the Privacy modules |
---|
|
Multiexcerpt include |
---|
MultiExcerptName | installation |
---|
PageWithExcerpt | Privacy module |
---|
|
|
Anchor |
---|
| anc-outdated-addons |
---|
| anc-outdated-addons |
---|
|
Remove outdated add-on modules
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 |
---|
server | Magnolia - Issue tracker |
---|
columns | key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution |
---|
serverId | 500b06a6-e204-3125-b989-2d75b973d05f |
---|
key | MGNLEE-533 |
---|
|
.
WebDAV
You must remove the magnolia-module-webdav
module because Apache Jackrabbit 2.16 no longer supports WebDAV.
Anchor |
---|
| anc-check-custom-fields-based-on-magnolia-fields |
---|
| anc-check-custom-fields-based-on-magnolia-fields |
---|
|
Check custom fields extending or decorating Magnolia fields
We have changed a few names for field definitions. This was part of the initiative to reference fields by its "short" name with the property fieldType
(see Referencing fields). The name which may have changed is the node name if the field is defined via JCR in the folder modules/some-module/fieldTypes
or the file name of a YAML based definition.
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.
Here's a list of the field names which have been changed:
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 magnolia.properties file with the one from the newly released Magnolia bundles. |
Todo |
---|
- Remove the SNAPSHOT version on the artifact macro displaying the latest 5.7.x version
- fetch the proper version of the properties files based on the latest tagged version after the release.
|
Below are the latest versions of the magnolia.properties
files for the Magnolia 5.7 series:
Artifact resource link |
---|
groupId | info.magnolia.bundle |
---|
artifactId | magnolia-bundle-parent |
---|
label | $version |
---|
renderType | display_only |
---|
version | SNAPSHOT |
---|
resourceType | POM |
---|
|
Magnolia CE / Magnolia EE Standard *
Code Pro |
---|
profile | bitbucket-ee |
---|
language | text |
---|
title | ce/magnolia-empty-webapp/src/main/webapp/WEB-INF/config/default/magnolia.properties |
---|
collapse | true |
---|
url | https://git.magnolia-cms.com/projects/PLATFORM/repos/ce/raw/magnolia-empty-webapp/src/main/webapp/WEB-INF/config/default/magnolia.properties?at=master |
---|
|
|
*) Magnolia CE and Magnolia EE Standard use the same magnolia.properties
file.
Magnolia EE Pro
Code Pro |
---|
profile | bitbucket-ee |
---|
language | text |
---|
title | ee/magnolia-enterprise-pro-webapp/src/main/webapp/WEB-INF/config/default/magnolia.properties |
---|
collapse | true |
---|
url | https://git.magnolia-cms.com/projects/PLATFORM/repos/ee/raw/magnolia-enterprise-pro-webapp/src/main/webapp/WEB-INF/config/default/magnolia.properties?at=master |
---|
|
|
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 |
---|
| anc-library-updates |
---|
| anc-library-updates |
---|
|
Third-party libraries
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 |
---|
| _groovy 2.5 update for magnolia-groovy 2.7 |
---|
| _groovy 2.5 update for magnolia-groovy 2.7 |
---|
|
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
- xercesImpl-2.12
How to update
Recommendations
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.
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 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 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 your
magnolia.properties
files, compare the changes to the file in the new bundle. Properties may have been added or removed. - Read the release notes for all intermediate versions for any additional update tasks.
- Restart the application server.
- In your browser, go to the Magnolia instances and run the web update.
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 |
---|
title | Click to see an example |
---|
|
Code Pro |
---|
language | xml |
---|
title | custom-ee/custom-ee-webapp/pom.xml |
---|
linenumbers | true |
---|
| <?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.example</groupId>
<artifactId>custom-ee</artifactId>
<version>1.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>custom-ee-webapp</artifactId>
<name>custom-ee: webapp</name>
<packaging>war</packaging>
<dependencies>
<dependency>
<groupId>info.magnolia.eebundle</groupId>
<artifactId>magnolia-enterprise-pro-webapp</artifactId>
<type>war</type>
</dependency>
<dependency>
<groupId>info.magnolia.eebundle</groupId>
<artifactId>magnolia-enterprise-pro-webapp</artifactId>
<type>pom</type>
</dependency>
<!-- More custom modules here -->
<dependency>
<groupId>com.example</groupId>
<artifactId>foobar-module</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<!-- exclude jars copied "physically" from the webapp overlay - so we only get those resolved by Maven's dependency management -->
<dependentWarExcludes>WEB-INF/lib/*.jar</dependentWarExcludes>
</configuration>
</plugin>
</plugins>
</build>
</project> |
|
Line 5: custom-ee/pom.xml
is the parent pom file of your custom webapp. This file manages the dependencies and their versions.
Expand |
---|
title | Click to see an example |
---|
|
Code Pro |
---|
language | xml |
---|
title | custom-ee/pom.xml |
---|
linenumbers | true |
---|
| <?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>custom-ee</artifactId>
<name>custom-ee (parent pom)</name>
<version>1.0-SNAPSHOT</version>
<packaging>pom</packaging>
<properties>
<magnoliaBundleVersion>5.6.6</magnoliaBundleVersion>
<foobarModuleVersion>1.2</foobarModuleVersion>
<javaVersion>1.8</javaVersion>
</properties>
<!-- Fill the following in, so you can use the release plugin -->
<scm>
<connection/>
<developerConnection/>
<url/>
</scm>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>info.magnolia.eebundle</groupId>
<artifactId>magnolia-enterprise-bundle-parent</artifactId>
<version>${magnoliaBundleVersion}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<!-- More dependencies for your custom modules here -->
<dependency>
<groupId>com.example</groupId>
<artifactId>foobar-module</artifactId>
<version>${foobarModuleVersion}</version>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.7.0</version>
<configuration>
<source>${javaVersion}</source>
<target>${javaVersion}</target>
</configuration>
</plugin>
</plugins>
<!-- default resources configuration which will filter your module descriptors -->
<resources>
<resource>
<directory>src/main/resources</directory>
<includes>
<include>**/*</include>
</includes>
</resource>
<resource>
<filtering>true</filtering>
<directory>src/main/resources</directory>
<includes>
<include>META-INF/magnolia/*</include>
</includes>
</resource>
</resources>
</build>
<repositories>
<repository>
<id>magnolia.public</id>
<url>https://nexus.magnolia-cms.com/content/groups/public</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
<repository>
<id>magnolia.enterprise.releases</id>
<url>https://nexus.magnolia-cms.com/content/repositories/magnolia.enterprise.releases</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>vaadin-addons</id>
<url>https://maven.vaadin.com/vaadin-addons</url>
</repository>
</repositories>
<modules>
<module>custom-ee-webapp</module>
</modules>
</project> |
|
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 |
---|
language | xml |
---|
linenumbers | true |
---|
|
<properties>
<magnoliaBundleVersion>5.7</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 |
---|
| anc-known-issues |
---|
| anc-known-issues |
---|
|
Known issues
Multiexcerpt include |
---|
MultiExcerptName | issue |
---|
PageWithExcerpt | _known issue with tomcat 8.5x JAVA EE and BCEL |
---|
|
If you encounter other problems, check the Known issues page.