Setting up a Magnolia bundle for local development

This page explains how to set up a Magnolia bundle on your local computer. The purpose of a local Magnolia instance is to try out new features locally first. We assume that you already have a local clone of the Git repository which is connected to your Magnolia subscription package. Magnolia automatically detects new files that you add to the light-modules folder of the local Git repository.

Before you start

Have a look at the prerequisites before you get started.

Make sure you are familiar with the following configuration information. If not specified otherwise, the paths shown follow Mac usage.

Path to the local Git repository

Note the path to your local Git repository.
Example: /Users/<username>/dev/repo/mgnl-cloud-packages/magnolia-docs

Path to the light-modules folder

Note your light-modules folder, which is a subfolder of the local Git repository.
Example: /Users/<username>/dev/repo/mgnl-cloud-packages/magnolia-docs/light-modules

Magnolia bundle installation directory

Note the Magnolia bundle installation directory. This is the directory in which you install the local development bundle. When choosing a name, remember:

  • You need write permission for the folder.

  • It cannot be a subdirectory of the local Git repository.

  • Do not use special characters (including spaces) in the folder name.

  • Example name: /Users/<username>/dev/mgnl-bundles

What is magnolia.resources.dir?

magnolia.resources.dir is a property defining the directory from which resources are loaded in a Magnolia instance. This directory is used for file-based resources such as light modules and for overriding classpath resources. The property is configured in WEB-INF/config/default/ and its default value is $magnolia.home/modules. To see the current value of the property, go to the Config Info tab in the About Magnolia app.

You can use symbolic links (symlinks or soft links) in the resources directory to include light modules located elsewhere on your system.

Set the magnolia.resources.filesystem.observation.excludedDirectories property to exclude directories from being observed for changes. (See the table in the Configuration management: Defining properties section.)

During setup you set the magnolia.resources.dir property to point to your light-modules folder. For example:


The property is set automatically if you install the bundle with Magnolia CLI jumpstart command. If you install the bundle manually, you also have to set the property manually.

Magnolia bundle

The Magnolia bundle for local development is bundled with a Tomcat application server containing the same apps and modules as those installed in the cloud-based Magnolia package.

Access to the Magnolia bundle requires credentials to Magnolia Nexus. If you haven’t subscribed to a Magnolia cloud package yet, we suggest you try out our magnolia-community-demo-bundle. It can be installed with Magnolia CLI and you don’t need a license for it.

Installing the local Magnolia bundle

There are two ways to install the bundle: using Magnolia CLI or manually.

Installing with Magnolia CLI

The installation of the bundle with Magnolia CLI is done via the jumpstart command. To be able to install the bundle, you must have Magnolia CLI and DX Core or Cloud credentials to access to the Magnolia Nexus repository. If you do not have credentials, use our free community edition for this tutorial instead.

Change to the directory where you want to install the bundle:

cd /Users/<username>/dev/mgnl-bundles

Execute the Magnolia CLI jumpstart command with the -p option pointing to the light-modules directory of the local Git repository.

mgnl jumpstart -p /Users/<username>/dev/repo/mgnl-cloud-packages/magnolia-docs/light-modules

You are prompted to choose a Magnolia bundle, choose:

  • magnolia-dx-core-webapp if you have already subscribed to Magnolia Cloud and have received credentials.

  • magnolia-community-webapp if you do not have cloud credentials yet.

The jumpstart process may take some time because it includes a download. Note that the jumpstart command automatically sets the magnolia.resources.dir property. Once the setup operation is complete, you should see a message similar to this one:

info Magnolia has been successfully setup for light development!
info You can now open a new terminal tab or window and start it up with the CLI command 'mgnl start'
info Magnolia will be ready after a few seconds at localhost:8080/magnoliaAuthor. Username and password is superuser

The following files and folders are created:

 ├── apache-tomcat/
 │ ├── bin/
 │ ├── conf/
 │ ├── lib/
 │ ├── logs/
 │ ├── temp/
 │ └── webapps/
 ├── downloads/
 └── light-modules

Remember the path to the bin directory. Later on you will start the bundle from this directory.

Example path: /Users/<username>/dev/mgnl-bundles/apache-tomcat/bin.

Installing the bundle manually

Download and unzip the bundle

Download the bundle manually. Here is a link to the latest version: {magnolia-latest-version}

Move the zip file to the installation directory and unzip it. The following structure is created:
└── magnolia-<x.y.z.>/
    ├── add-ons/
    │ └── magnolia-templating-samples-<x.y.z.>/
    └── apache-tomcat-<x.y.z.>/
        ├── bin/
        ├── conf/
        ├── lib/
        ├── logs/
        ├── temp/
        └── webapps/

Remember the path to the bin directory. Later on you will start the bundle from this directory.

Example path: /Users/<user-name>/dev/mgnl-bundles/magnolia-<x.y.z.>/apache-tomcat-<x.y.z.>/bin

Set the magnolia.resources.dir property

Edit the file. The file is located in magnolia-<x.y.z.>/apache-tomcat-<x.y.z.>/webapps/magnoliaAuthor/WEB-INF/config/default/ Find the line with the magnolia.resources.dir property and change it to:


Starting and stopping the bundle

When you have finished configuring the bundle, start it up.

Starting and stopping with Magnolia CLI

Magnolia CLI looks in the current working directory or parent directories for the nearest folder with a name that starts with apache-tomcat.

Open a shell and execute:

mgnl start

The command executes the start script and also tails the log of the Tomcat server.

To stop Magnolia, use CTRL-C.

For further information, refer to the Magnolia CLI documentation.

Starting and stopping the bundle with the magnolia_control script

Open a shell and go to the bin directory of your Magnolia Tomcat bundle. If you have installed the bundle using Magnolia CLI jumpstart, execute the following command:

cd /Users/<username>/dev/mgnl-bundles/apache-tomcat/bin

If you have installed the bundle from a zip file, execute the following command:

cd /Users/<username>/dev/mgnl-bundles/magnolia-<x.x.z>/apache-tomcat-<x.x.z>/bin

The bin directory contains an executable script which can be used to start and stop the Tomcat server. Mac, Linux and Solaris users have to execute the file, Windows users have to execute the magnolia_control.bat file. Execute the script with the start option. To shut Magnolia down, use the stop option.

Mac, Linux and Solaris users

Execute the following command:

./ start

If you get a low max open files error, try executing the command with the --ignore-open-files-limit option:

./ start --ignore-open-files-limit

To stop Magnolia, execute:

./ stop

Windows users

Execute the following command:

magnolia_control.bat start

To stop Magnolia, execute:

magnolia_control.bat stop

Tailing the log file

If your shell knows the tail command, you may tail the log file to display a lot of helpful information during the development process. If you are still in the bin directory, execute:

  tail -f ../logs/catalina.out

To stop the tail, press CTRL + C.

Conclude the installation in your web browser

To finish the installation of the bundle, open the page http://localhost:8080/magnoliaAuthor/ in your web browser and follow the instructions shown. Before starting up the author instance, finish the installation also on the public instance by opening the page http://localhost:8080/magnoliaPublic/.

When using magnolia-community-webapp or dx-core-webapp, in your local public instance, the webapp magnoliaAuthor comes with a virtual URI mapping that redirects / to /.magnolia/admincentral.

In the cloud environment public instance, / redirects to /home.

Remove this redirect on your local installation or set it according to your needs.



Legacy Cloud



This widget lets you know where you are on the docs site.

You are currently perusing through the Magnolia Cloud docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules