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/magnolia.properties 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:
magnolia.resources.dir=/Users/<username>/dev/repo/mgnl-cloud-packages/magnolia-docs/light-modulesThe 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-bundlesExecute 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-modulesYou are prompted to choose a Magnolia bundle, choose:
-
magnolia-dx-core-webappif you have already subscribed to Magnolia Cloud and have received credentials. -
magnolia-community-webappif 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 superuserThe following files and folders are created:
mgnl-bundles/
├── apache-tomcat/
│ ├── bin/
│ ├── conf/
│ ├── lib/
│ ├── logs/
│ ├── temp/
│ └── webapps/
├── downloads/
└── light-modulesRemember 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: 6.3.0
| 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-modulesStarting 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 startThe 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/binIf 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>/binThe 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 startIf 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-limitTo stop Magnolia, execute:
./magnolia_control.sh stopConclude 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.
Next: