An update from Magnolia 4.4 to 4.5.x is not as straightforward as a standard update. The changes done on different levels mean that you have to do more than a standard update. To help you in these tasks we defined a process to follow.

  • Understand what has changed in 4.5. Read 1. Prerequisites.
  • 2. Prepare and analyze. If you have a huge website we do not recommend doing the migration in development on it but rather to create a small migration website where you have only one page for each page template and one component for each component template. That is, assign each template only once.

You could also do an HTML export of this small website. It's a way to check if everything is migrated correctly, later you could compare this export with an export of the migrated website.


In order to complete these exercises you need:

  • Enterprise account. The training project has a dependency on magnolia-enterprise-webapp.
  • JDK 1.6
  • Eclipse with Git integration. The exercise material is based on Eclipse 3.7 Indigo.

You also need admin permissions to run terminal / shell scripts.

Checkout / clone from Git

  1. Go to http://git.magnolia-cms.com/gitweb/?p=training/update-training.git;a=summary
  2. Copy the https link to the update training repository:  https://git.magnolia-cms.com/git/training/update-training.git

You can find this information by navigating to the project you need and selecting the desired repository. This information will always be displayed on top of the repository summary page.

As you are starting development be sure to work on the master branch. Other branches can be checked out should you need to skip one of the exercises.

You will find in the master branch the migration project based on a magnolia 4.4 version as well as the tomcat bundle in the bundle directory. 

Set up Eclipse

Create an Eclipse workspace. This workspace should contain Tomcat that we will use in the next step.

Import your checked out Maven project

Set Eclipse preferences

  1. In Java > Installed JREs, edit the JVM installed.

    Add the Default VM Arguments -Xmx512m. In exceptional cases it may be necessary to add -XX:MaxPermSize=256m.

    In Server > Runtime Environments, add a new Apache Tomcat Server 7. Ensure that you are using version 7.42 or later.

Add Tomcat server

  1. Right-click in the server tab and select New > Server.
  2. Select Tomcat v7.0 Server and click Finish.
  3. Add the update-training-44-webapp, click Finish.

Configure Tomcat Server

  1. Configure the Tomcat server by double-clicking on it.
  2. Increase timeouts by factor of 10, starting from 45 to (e.g.) 450, and stopping from 15 to (e.g.) 150.
    (warning) On Mac OS X, the widgets show only one digit but the complete numbers can still be edited.)
  3. Important: Select the Serve modules without publishing option.

Start the Web application

Right-click on you Tomcat server and select Debug.

When you start your webapp for the first time you will have to enter an enterprise license as it is an enterprise project. 

The location of the training repository is stored in magnolia.properties under magnolia.repositories.home. You can change the location if you prefer another place for the repository.

Run the bundle

The bundle will be used for comparison during the migration process as you are working on the delta. The bundle is the clean start state of your original project. Compare your changes to the bundle to make sure that templates render correctly, all the content is displayed, the layout is correct etc. It is located in the git master under Bundle

The bundle only contains one author instance under the contextPath magnoliaAuthor. Tomcat 6.0.32 is included and the default port on this instance is 9090 in order to not conflict with the Eclipse instance. The AdminCentral link of the author instance is  http://localhost:9090/magnoliaAuthor/.magnolia/pages/adminCentral.html .

To run the bundle:

  1. Copy the supplied bundle from the git repo origin/bundle to a local folder.
  2. Open a terminal / shell and change to Tomcat's bin folder to start the server:
    • In Windows, type magnolia_control.bat start
    • In Mac/Unix, type ./magnolia_control.sh start
      (warning) This might take some time to start up.
      (info) In Mac/Unix: you can use the tail command to show the content of the server log. Out of the same bin folder type tail -f ../logs/catalina.out &. If you have a similar tool for Windows such as mtail  you can print out the content of  <tomcat-folder>/logs/catalina.out
  3. Open  http://localhost:9090/magnoliaAuthor  and run the installation
  4. Enter your license key as the bundle is based on an enterprise version of magnolia
  5. Log in with superuser credentials and verify that you have the same content as in your Eclipse installation.

Supporting documentation