How to upgrade from CE to DX Core

If you have already started your Magnolia project on Community Edition then it’s simple to upgrade that project to DX Core (aka Enterprise Edition). Doing so will require that you have a license available to run the all the modules you would like to install. Magnolia developer trial licenses can be requested here for a term of 30 days.

No matter how your project is currently built or maintained this tutorial will try and consolidate all possible approaches into a single best practice approach. In some cases you might have to adjust these instructions to suit your needs or deployment scenario. Enterprise customers (or potential customers) can always seek help from our Support channel by requesting the credentials from Sales. If you are considering moving a Community project the best place to start is by contacting out sales team.

Getting started

It really does not matter how you currently deploy Magnolia. All you really need is to have an understanding of what modules you currently have installed. Anything custom you have added will need some special considerations as you move your project.

As an example, let’s consider the scenario where I am currently running in production the travel website on Magnolia 5.6.8 CE. My target is to bring the project up to Magnolia 6.2 DX Core.

Versions prior to 5.6 should migrate to 5.6 first. 5.6 requires Vaadin 8 and log4j2 upgrades.

Maven project

In some cases users of Magnolia have downloaded our pre-assembled Tomcat bundles and used those as the basis for deployment. Adding modules manually to the libs folder prior to deployment. If this is how you currently deploy Magnolia then take this opportunity to begin using Maven to manage your war files instead.

I will start under the condition that I have downloaded a pre-assembled bundle and deployed my travel website. Since I was new to Magnolia I have also deployed under the default conditions of using H2 as my production database. Now would be a good time to change that so I am using something more appropriate like MySQL.

This means I need to complete the following steps.

Create a Maven project for 5.6.8 CE
Transfer the data from my H2 database to the new MySQL database

Use the archetype

If you are not familiar with Maven then I would suggest you see Maven setup and/or How to use Magnolia Maven archetypes. You don’t need to know a lot about Maven to be proficient. Just have it installed and configured so that you can use it at the command line to build the project.

This example is based on version 1.2.4 of magnolia-project-archetype .

The latest version is 1.3.

If you already have a Maven project, you can skip this step.

From the command line.

florida:Upgrade rgange$ mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeCatalog=https://nexus.magnolia-cms.com/repository/public/
[INFO] Scanning for projects...
...
...
...
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
1: https://nexus.magnolia-cms.com/repository/public/ -> info.magnolia.maven.archetypes:magnolia-theme-archetype (An archetype to create STK Theme modules)
2: https://nexus.magnolia-cms.com/repository/public/ -> info.magnolia.maven.archetypes:magnolia-project-archetype (An archetype to create a Magnolia project – a parent POM and a webapp)
3: https://nexus.magnolia-cms.com/repository/public/ -> info.magnolia.maven.archetypes:magnolia-module-archetype (An archetype to create basic Magnolia modules)
4: https://nexus.magnolia-cms.com/repository/public/ -> info.magnolia.maven.archetypes:magnolia-forge-module-archetype (An archetype to create a Magnolia module to be hosted on the Magnolia Forge)
5: https://nexus.magnolia-cms.com/repository/public/ -> info.magnolia.maven.archetypes:magnolia-blossom-module-archetype (An archetype to create Magnolia modules using Blossom)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 2
Choose info.magnolia.maven.archetypes:magnolia-project-archetype version:
1: 1.1.0
2: 1.2.0
3: 1.2.1
4: 1.2.2
5: 1.2.3
6: 1.2.4
7: 1.2.5
8: 1.2.6-SNAPSHOT
Choose a number: 8: 6
Define value for property 'groupId': : info.magnolia.webapps
Define value for property 'artifactId': : magnolia-cms
Define value for property 'version': 1.0-SNAPSHOT: : 5.6.8-SNAPSHOT
Define value for property 'package': info.magnolia.webapps: :
Define value for property 'magnolia-bundle-version': : 5.6.8
Define value for property 'project-name': magnolia-cms: :
Confirm properties configuration:
groupId: info.magnolia.webapps
artifactId: magnolia-cms
version: 5.6.8-SNAPSHOT
package: info.magnolia.webapps
magnolia-bundle-version: 5.6.8
project-name: magnolia-cms
 Y: : Y
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: magnolia-project-archetype:1.2.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: info.magnolia.webapps
[INFO] Parameter: artifactId, Value: magnolia-cms
[INFO] Parameter: version, Value: 5.6.8-SNAPSHOT
[INFO] Parameter: package, Value: info.magnolia.webapps
[INFO] Parameter: packageInPathFormat, Value: info/magnolia/webapps
[INFO] Parameter: magnolia-bundle-version, Value: 5.6.8
[INFO] Parameter: package, Value: info.magnolia.webapps
[INFO] Parameter: version, Value: 5.6.8-SNAPSHOT
[INFO] Parameter: groupId, Value: info.magnolia.webapps
[INFO] Parameter: project-name, Value: magnolia-cms
[INFO] Parameter: artifactId, Value: magnolia-cms
[INFO] Parent element not overwritten in /Users/rgange/Upgrade/magnolia-cms/magnolia-cms-webapp/pom.xml
[INFO] project created from Archetype in dir: /Users/rgange/Upgrade/magnolia-cms
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 52.829 s
[INFO] Finished at: 2019-09-27T11:33:56+02:00
[INFO] Final Memory: 14M/170M
[INFO] ------------------------------------------------------------------------
florida:Upgrade rgange$

Update the webapp pom.

<!-- option ii - magnolia-community-webapp -->
<!-- Dependencies versions are already imported by parent pom. Requires "Option A" in the parent pom. -->
<dependency>
  <groupId>info.magnolia.bundle</groupId>
  <artifactId>magnolia-community-webapp</artifactId>
  <type>war</type>
</dependency>
<dependency>
  <groupId>info.magnolia.bundle</groupId>
  <artifactId>magnolia-community-webapp</artifactId>
  <type>pom</type>
</dependency>

Build the project.
```
florida:magnolia-cms rgange$ mvn clean install
```
Result: How to upgrade from CE to DX Core: <ac:image[Attr ac:queryparams'' effects=border-simple,blur-border,Attr ac:width'' 400]>

How to upgrade from CE to DX Core: <ri:attachment[Attr ri:filename create-project.png]>

Check for differences in your libraries.

Print to a file the WEB-INF/lib folder of the bundle and compare that with a file from the Maven built project.

florida:lib rgange$ diff libs-maven.txt libs-bundle.txt
180a181
> magnolia-module-public-user-registration-2.7.jar
198a200
> magnolia-sample-app-5.6.7.jar
207a210,211
> magnolia-travel-demo-1.2.5.jar
> magnolia-travel-tours-1.2.5.jar
222a227
> mail-1.4.5.jar
253c258
< libs-maven.txt
---
> libs-bundle.txt

The bundle contains a few modules that are not included in the Maven project.

Update the webapp POM to include any missing libraries.

    <dependency>
      <groupId>info.magnolia.bundle</groupId>
      <artifactId>magnolia-community-webapp</artifactId>
      <type>war</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia.bundle</groupId>
      <artifactId>magnolia-community-webapp</artifactId>
      <type>pom</type>
    </dependency>

    <!-- Include the Travel Demo -->
    <!-- By including Travel Demo it brings in the PUR and mail modules -->
    <dependency>
      <groupId>info.magnolia.demo</groupId>
      <artifactId>magnolia-travel-demo</artifactId>
    </dependency>
    <dependency>
      <groupId>info.magnolia.demo</groupId>
      <artifactId>magnolia-travel-tours</artifactId>
    </dependency>

    <!-- Include the sample app -->
    <!-- This could also represent a custom module in your project -->
    <dependency>
      <groupId>info.magnolia.sample</groupId>
      <artifactId>magnolia-sample-app</artifactId>
    </dependency>

Upgrade to DX Core

In this scenario the original instance was using H2 embedded database. A simple copy of the repositories folder will be enough to move the data to the new Maven based setup. If you are using another database then make sure the correct repo-confg file is located under WEB-INF/config/repoconfg.

Repository configuration

(Optional) Copy the repositories folder from the bundle instance over to the location of the Maven instance. This optional step only applies to setups which use an embedded database like H2 or Derby.
Make sure you have the appropriate repository config file in your project. Also be sure the magnolia.properties file is configured to use the that repo config file.

Update the parent POM to use 6.2

<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>info.magnolia.webapps</groupId>
  <artifactId>magnolia-cms</artifactId>
  <name>magnolia-cms (parent pom)</name>

  <!-- Update here -->
  <version>6.2-SNAPSHOT</version>
  <!-- *********** -->
  <packaging>pom</packaging>

  <properties>

    <!-- Update here -->
    <magnoliaBundleVersion>6.2</magnoliaBundleVersion>
    <!-- *********** -->
    <javaVersion>1.8</javaVersion>
  </properties>

Update the parent POM to use DX Core.

<dependency>
  <groupId>info.magnolia.dx</groupId>
  <artifactId>magnolia-dx-core-parent</artifactId>
  <version>${magnoliaBundleVersion}</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

Update the webapp POM to use DX Core.

    <dependency>
      <groupId>info.magnolia.dx</groupId>
      <artifactId>magnolia-dx-core-webapp</artifactId>
      <type>war</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia.dx</groupId>
      <artifactId>magnolia-dx-core-webapp</artifactId>
      <type>pom</type>
    </dependency>

    <!-- Include the Travel Demo -->
    <!-- By including Travel Demo it brings in the PUR and mail modules -->
    <dependency>
      <groupId>info.magnolia.demo</groupId>
      <artifactId>magnolia-travel-demo</artifactId>
    </dependency>
    <dependency>
      <groupId>info.magnolia.demo</groupId>
      <artifactId>magnolia-travel-tours</artifactId>
    </dependency>

    <!-- Include the sample app -->
    <!-- This could also represent a custom module in your project -->
    <dependency>
      <groupId>info.magnolia.sample</groupId>
      <artifactId>magnolia-sample-app</artifactId>
    </dependency>

(Optional) Upgrade to Tomcat 9.

With the classpath updated for 6.2 DX Core and the repository copied over from the 5.6.8 CE start up the instance to trigger the upgrade.

No matter which database you use its best to make a copy to test the upgrade with. If you are using an external DB, such as MySQL, you will need to copy all tables as well repository folder.

Trigger the update by going to http://localhost:8080/magnolia-cms-webapp
Once the upgrade is completed apply the license via the registration form.

If the installation encounters a problem open a support ticket and attach the entire log file from the upgrade.

Migrate the data

The original project was using H2 database. This is an embedded database and typically not ideal in a production environment. Mostly because the application would need to share memory with the database. Here we will migrate the data from H2 and move it to a MySQL instance.

If you do not need to Migrate to a different database then you can skip this step.

Start the author instance using the database you wish to migrate data from. In this case its H2 database but it could be any database. The source database used does not matter.
Using the Magnolia Backup module, take a manual backup of the current instance.

The Backup module is not part of community edition. Community edition users can make use of the migration groovy script.
Restore the instance to the target MySQL database using the restore script provided by the Backup module. See the instructions.

How to upgrade from CE to DX Core

Getting started

Maven project

Use the archetype

Upgrade to DX Core

Migrate the data

Location

Main doc sections