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.
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.1.2 DX Core.
Versions prior to 5.6 should migrate to 5.6 first. 5.6 requires Vaadin 8 and log4j2 upgrades. See the Release notes.
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. See Module Quickstart.
If you already have a maven project then you can skip this step.
From the command line.
Update the webapp pom.
Build the project.
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.
The bundle contains a few modules that are not included in the Maven project.
Update the webapp pom to include any missing libraries.
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
- (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.1.2
Update the parent pom to use DX Core.
Update the webapp pom to use DX Core.
- (Optional) Upgrade to Tomcat 9.
With the classpath updated for 6.1.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. The instructions here.