Magnolia 6.1 reached extended end of life on June 2, 2020. Support for this branch is limited, see End-of-life policy.

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

This page explains how bootstrapping works in Maven modules. 

Bootstrap files are used to load content into the JCR. Bootstrap files can be shared across Magnolia instances and typically contain configuration necessary to run modules or content (such as pages, assets and others).

How bootstrapping in Maven modules works - overview

Here's an overview of how bootstrapping in Maven modules works:

  1. Export JCR data files from Magnolia's AdminCentral.
  2. The exported files are placed in the bootstrap folder of the module or webapp.
  3. 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.

Using bootstrapping folders

Magnolia by default scans some dedicated folders during 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.

Bootstrapping on the webapp level

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/commonFiles 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. 

Bootstrapping on a module level

Bootstrapping on a module level only works 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.

FileConfiguration nodeDescription
config.modules.site.config.themes.travel-demo-theme.xml/modules/site/config/themes/travel-demo-themeTheme configuration.
config.modules.travel-demo.config.travel.xml/modules/travel-demo/config/travelTemplates, theme and i18n nodes of Site definition.
config.server.filters.i18n.bypasses.xml/server/filters/i18n/bypassesi18n content support filter bypass.
config.modules.public-user-registration.config.configurations.travel.xml/modules/public-user-registration/config/configurations/travelPUR module configuration.
config.server.filters.securityCallback.clientCallbacks.travel-demo-pur.xml/server/filters/securityCallback/clientCallbacks/travel-demo-purSecurity 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.

  • No labels