Bootstrapping

This page explains the concept of Bootstrapping, bootstrap files and how to handle them.

The bootstrapping mechanism allows you to load initial JCR data into Magnolia automatically on installation. Bootstrap files can be selectively shared across all Magnolia instances. Bootstrap files typically contain configuration necessary to run modules or content (such as page, assets and others).

How bootstrapping works - overview

JCR data is exported as XML files from Magnolia's AdminCentral.
The exported XMLs are placed in the bootstrap folder of the module or webapp.
On installation, the bootstrapped data is automatically* imported by Magnolia and added to its corresponding JCR workspace.

*) Bootstrap files can also be imported or bootstrapped manually using the import actions in the JCR Browser and many other apps. However, the content of this page is limited to automatically importing bootstrap files and the term "bootstrapping" is used in this context only.

What is a bootstrap file?

A bootstrap file is an XML file representing JCR data created by an export action.

Bootstrap files can contain any type of data which can be stored in JCR - including both text and binary data - used as content or for configuration.

Bootstrap files are used to import the data during the start up of Magnolia - the import action adds the data from the bootstrap file to its corresponding JCR workspace.

Bootstrap file format

Exported bootstrap files are in XML format.

The XML structure reflects the hierarchical data stored in JCR.
The autogenerated name of the exported XML file reflects the path of the exported data in the <workspace>.<path to content>.xml format. For example website.travel.about.xml is the filename for the XML export of the travel/about page in the website workspace.
The filename determines where the content will be applied when bootstrapped into the JCR. For example config.modules.pages.xml is applied in the config workspace in the modules/pages folder.
Bootstrap files contain all JCR properties of every node (such as mgnl:created, mgnl:lastModified, mgnl:lastModifiedBy, jcr:createdBy, jcr:primaryType, etc.) which makes the XML files big and hard to read. This said, it is not advisable to manually edit bootstrap files, unless you really know what you are doing.

Creating a bootstrap file

Every JCR node in AdminCentral can be exported as XML. The export of a node is always inclusive of its subnodes.

Magnolia provides various possibilities to export JCR data as bootstrap files:

JCR Browser app
Export tool in the JCR Tools app
Many, but not all content apps. For instance Assets app, Pages app and Configuration app all provide dedicated export actions.

To create a bootstrap file:

In any app which can export JCR data, select a content node and click export.
Save the file. Do not change the autogenerated file name.
Place the file in the bootstrap folder of your module or webapp.

It is good practice to split up bootstrap files into smaller portions. This helps to ease both updating bootstrap files and to ensure that multiple developers can work on the same module without creating conflicts. (Resolving conflicts of bootstrap files when using revision control systems such as CVS, subversion or GIT can be hard.)

Using bootstrapping folders

Magnolia by default scans some dedicated folders during the start up. Add your bootstrap files to this folders to automate the import of the JCR data of these files. Bootstrap files can reside at a webapp or module level.

All bootstrap files are only imported once!

Webapp-based bootstrap files are imported during the first run of the webapp when the Magnolia instance gets installed.
Module-based bootstrap files are imported during the installation of the module.

If you want to import bootstrap files on every start up of the Magnolia instance or of a module, you must use custom installation tasks which are executed by the Module version handler or Module start up classes.

Bootsrapping on the webapp level

This option provides a way for front-end developers working with light modules to bootstrap content such as pages and assets without having to create a Maven module.

The bootstrap directories for webapp bootstrap files are set by the magnolia.bootstrap.dir property in the magnolia.properties file. See Configuration management for more.

By default the bootstrapping directories on the webapp level are:

Location
`WEB-INF/bootstrap/author`	Files will only be imported if the current context is an *author* context.
`WEB-INF/bootstrap/common`	Files will be imported on any context.

Bootstraps are loaded from this directory only the first time the WAR is installed in the container that is running for the first time.

The directory should contain XML files for initialization of a blank Magnolia instance. If no content is found in any of the repositories, they are initialized by importing the XML files found in this directory.

Bootsrapping on a module level

Bootstrapping on a module level works only:

With Magnolia Maven modules. Light modules do not yet provide a bootstrapping mechanism. (See Module structure for the difference between light modules and Maven modules.)
If your Module has a module version handler class.

There are two directories that you can add bootstrap files to in a Magnolia Maven module:

src/main/resources/mgnl-bootstrap/<magnolia-module-name>/
src/main/resources/mgnl-bootstrap-samples/<magnolia-module-name>/
- Bootstrap files within mgnl-bootstrap-samples are only imported, if the magnolia.bootstrap.samples property (which is set in the magnolia.properties file, see Configuration management) is true:
```
magnolia.bootstrap.samples=true
```

Example - Bootstrap files in the travel-demo module

Here are the configuration files bootstrapped on installation of the travel-demo module.

The files are in the directory /src/main/resources/mgnl-bootstrap/travel-demo.

File	Configuration node	Description
`config.modules.site.config.themes.travel-demo-theme.xml`	`/modules/site/config/themes/travel-demo-theme`	Theme configuration.
`config.modules.travel-demo.config.travel.xml`	`/modules/travel-demo/config/travel`	Templates, theme and i18n nodes of Site definition.
`config.server.filters.i18n.bypasses.xml`	`/server/filters/i18n/bypasses`	i18n content support filter bypass.
`config.modules.public-user-registration.config.configurations.travel.xml`	`/modules/public-user-registration/config/configurations/travel`	PUR module configuration.
`config.server.filters.securityCallback.clientCallbacks.travel-demo-pur.xml`	`/server/filters/securityCallback/clientCallbacks/travel-demo-pur`	Security callback for public user registration.

Bootstrapping content into cluster nodes

The magnolia.repositories.jackrabbit.cluster.master property can be used to identity an instance as a cluster master node. By default this property is set to false in magnolia.properties. When enabled Magnolia bootstraps content only into master nodes. This ensures that other (replica) nodes installed later don't override already bootstrapped content. See Configuration management for more.

Bootstrap configuration properties

The table below contains a list of configuration properties set in magnolia.properties that are relevant to bootstrapping.

magnolia.bootstrap.samples

optional, default is true

Installs sample bootstrap files located in /mgnl-bootstrap-samples/<module name> directory.

magnolia.bootstrap.dir

required , default is WEB-INF/bootstrap/author WEB-INF/bootstrap/common

Sets the directory for webapp bootstrap files.

magnolia.repositories.jackrabbit.cluster.master

required default is false

Identifies an instance as cluster master node.

Page tree