Page tree
Skip to end of metadata
Go to start of metadata

You set up a local Magnolia instance to try out new features during the local development process. 

This page explains how to set up a Magnolia bundle on your computer for local development purposes. 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

magnolia.resources.dir property

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/magnolia.properties and has the default value $magnolia.home/modules. To see the current value of the property, go to the Config Info tab in the About Magnolia app.
(info) You can use symbolic links (a.k.a symlinks or soft links) in the resources directory to include light modules located elsewhere on your system.

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

magnolia.resources.dir=/Users/<username>/dev/repo/mgnl-cloud-packages/magnolia-docs/light-modules

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 Tomcat bundle

Ideally, 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. Unfortunately such a bundle does not exist yet. 

Please note that all of the existing bundles that come with Tomcat also include demo modules and most of them contain Travel Demo. Since you will be developing light-modules, you will not need the demo content modules included but these modules should not interfere with your module development. Just be aware that Travel Demo comes with a site definition.

We recommend using magnolia-community-demo-bundle . It can be installed with Magnolia CLI and you won't need a license for it. If you want to apply a different bundle, check the List of preconfigured Magnolia bundles.

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 use it, you must have Magnolia CLI installed (see Magnolia CLI Installation).

Change to the directory to 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

This 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:

mgnl-bundles/
 ├── apache-tomcat/ 
 │   ├── bin/ 
 │   ├── conf/ 
 │   ├── lib/ 
 │   ├── logs/ 
 │   ├── temp/ 
 │   └── webapps/ 
 └── magnolia.zip

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-community-demo-bundle. Move the zip file to the installation directory and unzip it. The following structure is created:

mgnl-bundles/
└── 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 magnolia.properties file. The file is located in magnolia-<x.y.z.>/apache-tomcat-<x.y.z.>/webapps/magnoliaAuthor/WEB-INF/config/default/magnolia.properties . Find the line with the magnolia.resources.dir property and change it to:

magnolia.resources.dir=/Users/<username>/dev/repo/mgnl-cloud-packages/magnolia-docs/light-modules

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 magnolia_control.sh, 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:

./magnolia_control.sh start

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

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

To stop Magnolia, execute:

./magnolia_control.sh 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/ .

Next: 

* Developing and testing