Configuration management

Properties

Property files are used for configuration during the startup sequence before the repository is available. These properties configure the instance for a particular use (such as a development or production environment) and set various system directories. Once the startup sequence is completed and the repository is available, the majority of configuration is done in the config workspace in the repository.

Properties are not stored in a single property file but come from multiple sources. These sources are processed or parsed in this order:

Source Location Path

1

Bean properties

magnolia-core.jar

/mgnl-beans.properties

2

Module properties

Module descriptor

 
<properties>
  <property>
    <name>defaultPublicURI</name>
    <value>redirect:/help.html</value>
  </property>
</properties>

3

Global file properties

web application

WEB-INF/config/magnolia.properties

4

Default file properties

web application

WEB-INF/config/default/magnolia.properties

5

Web application file properties

web application

WEB-INF/config/(webapp)/magnolia.properties

6

Server file properties

web application

WEB-INF/config/(servername)/magnolia.properties

7

Web application at server file properties

web application

WEB-INF/config/(servername)/(webapp)/magnolia.properties

8

System properties

JVM options (-Dx=y)

Existing properties will be overridden by available System properties.

Sources processed earlier may be overridden by sources processed later. The processing order and distribution of properties into several sources allows for flexible customization.

Some important properties set in the default magnolia.properties file:

# Repository configuration
magnolia.repositories.config = WEB-INF/config/default/repositories.xml
magnolia.repositories.home = ${magnolia.app.rootdir}/repositories
magnolia.repositories.jackrabbit.config = WEB-INF/config/repo-conf/jackrabbit-bundle-h2-search.xml

# Defining the instance as author instance
# Only used for the initial installation.
# Afterwards configuration in the config repository is used.
# The value is saved in /server/admin
magnolia.bootstrap.authorInstance=true

# Switch to false to enhance the performance of Javascript generation
magnolia.develop=false

# Set to true if bootstrapping/update should be performed automatically
magnolia.update.auto=false
magnolia.app.rootdir is set programmatically during Magnolia start-up. Its value depends on the servlet container and on the environment, for instance on a production Tomcat it would be something like /some-path/some-tomcat/webapps.

Profile-based configuration of property files

To resolve property files in Magnolia 6.2.2+, you can use MAGNOLIA_PROFILE to configure a profile as an environment variable or system property. A profile is a folder under /WEB-INF/config/ containing Magnolia property files. See info.magnolia.init.DefaultMagnoliaPropertiesResolver for more information.

Example configuration

In addition to being part of the default profile, magnolia-empty-webapp is distributed with the develop profile (see Bundles and webapps). To use this profile, set MAGNOLIA_PROFILE to develop so that the property files in the develop folder are read. This will set the following properties to the specified values:

  magnolia.resources.dir=${magnolia.home}/../../src/main/magnolia
  magnolia.repositories.home=${magnolia.home}/../../repositories
  magnolia.develop=true
  magnolia.ui.sticker.environment=${MAGNOLIA_PROFILE}
  magnolia.ui.sticker.color=red

If no profile value is specified, Magnolia will fall back to configuration based on the server name, webapp name and context path. If you set the value to a profile that does not exist, an error message will be logged and Magnolia will fail to start. Note that no such check is performed when the magnolia.initialization.file context attribute is set to a custom value.

Multiple configurations in a single web application archive

Default properties are common regardless of the server name or webapp name. Webapp specific properties are installed only if the webapp name matches. Correspondingly, server specific properties are only installed if the server name matches. For example, Magnolia ships with two webapps by default: magnoliaAuthor and magnoliaPublic.

It is possible to set a different persistence manager per environment. For example, on the development instance you could use the default embedded Derby database, whilst on production you could use a production-scale persistent storage such as a MySQL database.

See WAR file with multiple configurations for more on this topic.

The MySQL InnoDB storage engine is supported by Magnolia, the MyISAM engine is not. InnoDB is the default engine in MySQL 5.5 and higher.

Customization

The structure and the order of source execution allows you to provide sophisticated configurations and flexible customization. The default Magnolia configuration (delivered in the web application bundle) provides an example of how the mechanism works:

  • WEB-INF/config/default/magnolia.properties

  • WEB-INF/config/magnoliaAuthor/magnolia.properties

  • WEB-INF/config/magnoliaPublic/magnolia.properties

Magnolia provides a single web application which configures itself depending on the servlet context it is installed in. If your environment has multiple staging systems with differing configuration needs, you can apply different configurations by adding a server name to each of the listed paths.

For complex environments, the order of loading files can be defined in WEB-INF/web.xml as a context-param element:

<context-param>
   <param-name>magnolia.initialization.file</param-name>
      <param-value>
         WEB-INF/config/${servername}/${webapp}/magnolia.properties,
         WEB-INF/config/${servername}/magnolia.properties,
         WEB-INF/config/${webapp}/magnolia.properties,
         WEB-INF/config/default/magnolia.properties,
         WEB-INF/config/magnolia.properties
      </param-value>
</context-param>
The properties files you specify in`WEB-INF/web.xml` are evaluated in reverse order, from bottom to top. That means the first properties file in the list (in the example above, WEB-INF/config/${servername}/${webapp}/magnolia.properties) can override values defined in all the other files lower down in the list.

Modifying the magnolia.home property

The default configuration of the magnolia.home property is intended to make development easy.

For production deployments, you should change the value of the property to a different location, for example to /opt/magnolia1 on your filesystem.

Changing just the value of the magnolia.home property will not make your bundle production-ready instantly.

It is also recommended to change the persistence settings and few other things, such as configuration of repositories, workspaces, and ACLs.

Defining properties

Properties can be accessed through the info.magnolia.init.MagnoliaConfigurationProperties class.

Property Description

log4j.config

required

default is WEB-INF/config/default/log4j.xml

Name of a log4j config file. Can be a .properties or .xml file. The value can be:

  • a full path

  • a path relative to the webapp root

  • a file name which will be loaded from the classpath

magnolia.bootstrap.dir

required

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

Directory containing XML or YAML 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 or YAML files found in this folder. If you don’t want to let Magnolia initialize repositories automatically then remove this parameter.

magnolia.cache.startdir

Directory used for cached pages.

In the magnolia.properties file, the magnolia.cache.startdir property is preset to ${magnolia.home}/cache.

magnolia.content.bootstrap.createTasks

optional

default is always

Co-specifies a content bootstrapping strategy. The following values can be used:

  • always: A workflow task is always created to import a content item. No content is bootstrapped automatically.

  • onchange: Content is bootstrapped automatically if the path does not exist in JCR. If the path exists, a task is created.

  • never: No workflow task to import content is created. Content is bootstrapped at every startup and after every change.

magnolia.content.bootstrap.dir

optional

The directory to import file system files from with the Content Importer module.

If the path is not set, the module is stopped.

magnolia.content.bootstrap.onlyImportAtInstall

optional

default is false

Co-specifies a content bootstrapping strategy.

If set to true, content is bootstrapped only at installation, not at every instance startup.

magnolia.content.bootstrap.pattern

optional

default is *.{yaml,xml}

Specifies which filenames will be imported and observed in the content bootstrap directory defined by the magnolia.content.bootstrap.dir property.

magnolia.definitions.classpath

required if you deploy on a WebSphere, Liberty or JBoss application server

Value must be set to info.magnolia.

magnolia.exchange.history

required

default is ${magnolia.home}/history

History directory used for publishing.

magnolia.repositories.config

required

default is WEB-INF/config/default/repositories.xml

Repository configuration, points to an XML file.

magnolia.jcr.query.logging.thresholdMs

optional

default is no threshold / logging disabled

Magnolia logs each JCR query exceeding the threshold in milliseconds.

magnolia.repositories.jackrabbit.cluster.master

required if you have any clustered workspaces in your project

default is false

Identifies the instance as a cluster master node. During installation and update Magnolia bootstraps content only into master nodes. This ensures that other (replica) nodes installed later don’t override already bootstrapped content.

Example: Public instance A is defined as a cluster master node. The instance starts and creates a clustered forum workspace and bootstraps some content such as rules of conduct. Second public instance B is defined as a replica node. It starts moments later but does not bootstrap the same workspace again.

  • true defines the instance is a cluster master node. Content is bootstrapped into the repository.

  • false defines the instance as a cluster replica node. Content is not bootstrapped into the repository.

magnolia.upload.tmpdir

required

default is ${magnolia.home}/tmp

Temporary directory for uploaded files.

magnolia.author.key.location

optional

default is ${magnolia.home}/WEB-INF/config/default/magnolia-activation-keypair.properties

Location of private and public activation keys used for publishing.

magnolia.cipher.algorithm

optional

default is RSA/None/PKCS1Padding

Algorithm for data transfer encryption and decryption.

The default specifies RSA as the encryption/decryption algorithm; the block type and padding algorithm are taken from the default Bouncy Castle values.

Supported algorithms: https://www.bouncycastle.org/specifications.html

The same cipher must be set both in the public and author instances, either in the default magnolia.properties file or in the properties files for the different instances. We strongly recommend all instances be updated at the same time.

If you change the cipher, you lose any passwords created in the Password manager module, the LDAP Connector module, and potentially other places if you used it for data storage purposes in your custom code. You must therefore re-instantiate your passwords with the new ciphers.

Since 6.2.37, new Magnolia bundles use OAEPWithSHA3-256AndMGF1Padding by default.

magnolia.bootstrap.authorInstance

optional

default is true

Sets an instance as author (true) or public (false).

magnolia.bootstrap.samples

optional

default is true

Some modules contain optional sample content. They will check this property to decide if they should install the content.

magnolia.components.config.properties.excluded

optional

List of component class names to be excluded from component instantiation. Separate class names with white space (space, tab) or commas.

magnolia.develop

optional

default is false

magnolia.develop is a configuration property that can be set to true in the magnolia.properties file for development purposes, specifically to:

  • Enable info.magnolia.classpathwatch.ClasspathScanner, when developing via IDE and changing/deploying edited classpath-based resources.

  • Disable the cache for resources.

Set to false on production instances.

magnolia.home

optional

default is ${magnolia.app.rootdir}

Root of the webapp’s deployment directory.

See also Modifying the magnolia.home property above on this page.

magnolia.jsr250.enabled

optional

default is false

Enables support for JSR-250 annotations. Magnolia uses the @PostConstruct annotation in methods that need to be executed after dependency injection is done to perform any initialization. Enabling JSR-250 support impacts performance.

magnolia.logs.dir

optional

default is ${magnolia.home}/logs

Directory where logs are written.

magnolia.migration.persistReport

optional

default is false

Turns off migration report generation to speed up the migration process. Set to true to generate reports.

magnolia.repositories.home

optional

default is ${magnolia.home}/repositories

Repository home directory.

magnolia.repositories.jackrabbit.config

optional

default is WEB-INF/config/repo-conf/jackrabbit-bundle-derby-search.xml

Jackrabbit configuration file. See the repo-conf directory for configuration files for other persistence managers such as MySQL, PostgreSQL and Ingres.

magnolia.repositories.jackrabbit.cluster.config

optional

Jackrabbit configuration file for a clustered repository.

Always define the cluster.config and cluster.master properties together if any of your workspaces are clustered.

magnolia.resources.classpath.observation.pattern

optional

default is .*\\.(ftl|yaml)$

Pattern to define which resources should be observed by ClasspathScanner.

The default pattern above observes any file names that end in .ftl and .yaml.

magnolia.resources.dir

optional

default is ${magnolia.home}/modules

Defines the directory from which filesystem resources such as light modules are loaded in a Magnolia instance.

magnolia.resources.filesystem.observation.excludedDirectories

optional

default is META-INF,WEB-INF,cache,docroot,logs,repositories,tmp

List of excluded resource directories in FileSystemResourceOrigin.

For example, if you are using the node_modules directory when developing locally, you can use magnolia.resources.filesystem.observation.excludedDirectories=node_modules to prevent slow loading of pages.

magnolia.resources.classpath.observation.excludedPackages

optional

default is no excluded packages

List of resource packages that should be excluded by the resource filter of ClasspathScanner to increase performance.

Example value: com/ctc,com/github,com/google,com/healthmarketscience,com/jhlabs,com/nmote,com/vaadin,groovyjarjarantlr4,kotlin,okio,org/bouncycastle,org/drools,org/eclipse,org/jboss,org/kie.

magnolia.resources.watcher.sensitivity

optional

default is high

The sensitivity (speed) with which the changes of the resources in the magnolia.resources.dir are observed by the info.magnolia.dirwatch.DirectoryWatcherService.

Possible values: low, medium, high. For development purposes on OSX it is recommended to set the property to high.

magnolia.update.auto

optional

default is false

Set to true if bootstrapping and update should be performed automatically after installation. This means the system won’t wait for the user to start the update manually.

magnolia.utf8.enabled

optional

default is false

Activate UTF-8 support for pages.

The value must be the same on both the author and public instance. Publication between instances with a different UTF-8 setting is not supported.

magnolia.clusterid

optional

default is set in set in Jackrabbit configuration file

The ID of the JCR cluster instance.

When setting the value in magnolia.properties, it overrides the value set in the Jackrabbit configuration file; this allows using a single configuration file for all the cluster instances.

magnolia.ui.sticker.environment magnolia.ui.sticker.color

optional

The properties add a sticker to the Admincentral interface to provide a clear visual clue about the type of the environment and instance the user is currently interacting with.

Example configuration

magnolia.ui.sticker.environment=LIVE

magnolia.ui.sticker.color=green

On the author instance, the following sticker appears:

Live sticker

The instance name is taken from the ${magnolia.webapp} property, which corresponds to the name of the folder into which Magnolia is deployed.

For color values, use a CSS3 unit, see https://www.w3.org/TR/css-color-3/#colorunits. If no color is set, the color of the sticker defaults to rgb(35, 35, 35).

The instance info sticker was originally released with Magnolia 5.6.3 as the info.magnolia.ui.admincentral.sticker.StickerViewImpl class. With the release of Magnolia 6.1, the class changed to info.magnolia.admincentral.components.InstanceInfo. If you have a custom sticker implementation on Magnolia 6.2 or higher, make sure it is based on the InstanceInfo, otherwise your implementation will not be rendered in the UI.

magnolia.image.recognition.numberOfThreads

optional

default is 1

The number of parallel recognition threads for image recognition.

magnolia.yaml.maxAliasesForCollections

optional

default is 50

The number of aliases for getMaxAliasesForCollections to prevent a Billion Laughs Attack.
In addition to these examples you can define arbitrary properties (magnolia.home is one example).

Substitution

Properties can be used to prefixother path-like properties. For example, in magnolia.cache.startdir=${magnolia.home}/cache the property magnolia.cache.startdir is set by substituting the root directory with property magnolia.home. See WAR file with multiple configurations on how to use properties to target a deployment environment.

Environment variables

Added in Magnolia 6.2.9

You can have different configurations in one or more environments. If you want to do this, you must first set the magnolia.yaml.envsubst feature flag (JVM option) to true. You can then use following syntax in a YAML file which will parse the environment variable:

label: !env ${ENV} (1)
<url>: !env https://${ENV}.api.com/<endpoint>
1 Make sure you have a space after the !env annotation as shown above.
This will only work in plain YAML definitions, not YAML decorator files or YAML bootstrap files.

This feature only works via environment variables, not Java options or Magnolia properties.

Environment variables are created from your terminal or IDE. You’ll need to export the variable(s) like so:

export API_BASE_URL=https://example.com/

Extending configuration

You can extend a configuration by defining an extends property and setting its value to the source configuration you want it to inherit. The target configuration inherits everything from the source and adds its own exceptions. This can save time and effort as you only need to define exceptions explicitly. The mechanism is only available in the config repository.

In the example below, the sportstation site definition extends the travel`site definition. The definition inherits all configuration from the `travel configuration and adds its own domains, internationalization and URI-to-repository mappings, theme and templates. The extends property can point to the source configuration with an absolute or relative path.

Definition example

Overriding

Extending is additive by default, which means that configuration specified at the extending level is added to the inherited configuration. Setting the extends property to override changes this behavior. An override allows the extending node to completely remove the inherited content and replace it with its own content entries. In the example below, the travel site definition supports two locales, en (English) and de (German), whereas site travel-fr is targeted to French speakers only.

The French site extends travel. It inherits all configuration except the locales. An override under the locales node removes en and de. Only the French locale fr defined at this level is applied. This means that authors can enter only French content on the French site.

Locales node

Observation

Observation is a feature of the Java Content Repository that enables applications to register interest in events that describe changes to a workspace. The applications can then monitor and respond to those events. The observation mechanism dispatches events when a persistent change is made to the workspace. Magnolia uses observation heavily. For instance, observation is used to reload module configurations and to reload all objects provided by the FactoryUtil. To use observation you must at least specify the workspace, the path to the node which should be observed, and an event listener. The event listener’s onEvent() method is called whenever there are changes in the observed node.

Magnolia provides the info.magnolia.observation.WorkspaceEventListenerRegistration helper class to assist you in using observation for your project. info.magnolia.cms.util.ObservationUtil has been deprecated since Magnolia 5.4.6.

Node2Bean

Most configuration is stored in the config workspace. To transfer the repository stored configuration into a Java object, a mechanism called Node2Bean is used. Node2Bean populates a Java Bean from the content of a repository node including sub nodes. Note that configuration details are not restricted to the config node. The following table shows where the Node2Bean mechanism is currently used.

Where it is used What is configured

info.magnolia.cms.beans.config.ServerConfiguration

Basic server configuration: defaultBaseURL, defaultExtension, instanceUuid, etc.

defaultBaseURL is the default base URL of the server root. The property is used to create absolute links in emails or other external systems.

info.magnolia.cms.beans.config.VirtualURIManager

Mapping virtual URIs to pages.

info.magnolia.cms.filters.FilterManagerImpl

Filter chain

info.magnolia.cms.i18n.DefaultMessagesManager

Messages for localized labels and descriptions in the UI.

info.magnolia.commands.CommandsManager

Commands and command catalogs.

info.magnolia.module.ModuleManagerImpl

Module definitions

info.magnolia.objectfactory.ConfiguredComponentFactory

Builds a component configured in the repository.

info.magnolia.objectfactory.ObservedComponentFactory

info.magnolia.objectfactory.guice.GuiceConfiguredComponentProvider

Guice Provider that creates an object by reading it from the repository.

info.magnolia.rendering.renderer.registry.ConfiguredRendererProvider

RendererProvider that instantiates a renderer from a configuration node.

info.magnolia.rendering.template.registry.ConfiguredTemplateDefinitionProvider

TemplateDefinitionProvider that instantiates a template from a configuration node.
For developers, module configuration (ModuleManagerlmpl) using the module class is the most important current usage of Content2Bean.

Node2Bean in module instances

Module configuration data is transferred into a Bean from /modules/<module name>/config. The Bean class to build is defined in the module descriptor XML file.

<!DOCTYPE module SYSTEM "module.dtd">
  <module>
    <name>samples</name>
    <displayName>Magnolia Samples Module </displayName>
    <class>
      info.magnolia.module.samples.SamplesModule
    </class>

Components. If a path in the config workspace is given rather than a concrete class name, then Node2Bean is used to build the component instance.

# Map to a path in the config workspace
info.magnolia.cms.i18n.I18nContentSupport = /server/i18n/content

Additional items such as components, templates and virtual URI mappings are configured at module level.

Data types

Node2Bean analyzes the bean’s setter and adder methods using introspection and uses them if a suitable configuration value is available. With the adder methods (using the singular form of the node names), you can populate collections and maps. With this mechanism, Node2Bean can support all possible data types:

  • Simple data types like string, int, long, float, double, or boolean (to specify true, you can use true, TRUE, or 1) with the suitable setter method

  • Other data types matching the setter method’s signature

  • Collections with string values or other data types by specifying a class property

  • Maps with keys and values as strings or other data types by specifying a class property

All sub-elements are also built using Node2Bean.

Classes

The class used to instantiate an object through the Node2Bean mechanism is determined through reflection or by explicitly referencing a class in the class node data. By referencing a specific class, you can override Magnolia default configuration and implement your own caching behavior, security mechanism and so on.

A diagram of Node2Bean

Numbered items:

  1. config: Entry point of the transformation. In the module descriptor SampleConfig class is used. Set text and number properties.

  2. sub: Subbean. The class is determined using reflection if it is not explicitly defined.

  3. items: Collection. The corresponding add method is used to determine the class and populate the collection if existing.

  4. item2: Special item with its own class and additional properties.

  5. parameters: Collection of key-value pairs.

Simple data types

Values with simple data types must be defined as properties. Each property name must match its respective setter method.

Collections

To configure a collection you have to create a sub node and a suitable setter method:

  • All properties of the collection node will create simple String entries in the collection. The properties’ names are not used by Node2Bean, only the values.

  • All sub nodes of the collection node will be treated as objects of the type specified in the class property in the sub node. If no class attribute is specified, a Map will be created instead. The sub nodes’ names are not used by Node2Bean.

  • All sub nodes of the collection node will be treated as maps unless they have a .. The properties’ names and the sub nodes’ names are not used by Node2Bean.

Maps

The rules to populate a map are the same as with collections, except that the properties’ names and the sub nodes’ names are used as key values.

Example: cache configuration

The configuration creates an object of the type info.magnolia.module.cache.ContentCachingConfiguration. This class needs public setter or adder methods.

 public void setCachePolicy(CachePolicy cachePolicy);
    public void setFlushPolicy(FlushPolicy flushPolicy);
    public void setBrowserCachePolicy(BrowserCachePolicy browserCachePolicy);
    public void setExecutors(Map executors);
    public void addExecutor(String name, CachePolicyExecutor executor);

Note, that all necessary setters are available. For the executors node, there are setter and adder methods. As the adder is more specific, the setExecutors method will not be used.

Cache configuration management

This is what happens with setCachePolicy(CachePolicy cachePolicy):

setCachePolicy configuration management

Since there is a class property defined, let’s look at the info.magnolia.module.cache.cachepolicy.Default class that Node2Bean uses to create the new object.

public void setVoters(VoterSet voters);

Now, let’s have a look at the addExecutor(String name, CachePolicyExecutor executor) method in ContentCachingConfiguration:

addExecutor method applied

As this method has two arguments, the node name bypass is passed as the first argument and a Bypass object as the second argument. Because CachePolicyExecutor is an interface, the implementing class is specified.

Voters

Voters are used in Magnolia whenever configuration values are not assigned at startup but instead depend on rules. For example the cache module has to determine if a requested resource may be cached or not. The rules to determine values should be configurable. The rules are user-defined using voters which evaluate established criteria by determining true or false of each rule. Voters are currently used for:

  • Filter configuration: uses voters to determine whether a filter should be executed or bypassed.

  • Cache configuration: uses voters to determine whether a file should be cached or not.

The basic concept of voters uses Voter classes which calculate an int vote value, where positive (1, 2, 3, …) results are treated as yes or true'' and (0, -1, -2, …) results are treated as ``no or false. If you have a set of voters, then the result of a voting is the largest absolute result. If there are two voters with the same absolute result, then the one with the higher positive value will be taken.

Examples:

Vote results VoterSet result

-3, 0, 2

-3

-3, 0, 3

3

-3, 0, 4

4

For most of the real world voters only boolean results make sense. These boolean voters return 1'' for a true'' and 0 for a false result.

Voter examples

Voter Parameters Boolean Description

info.magnolia.voting.voters.AuthenticatedVoter

none

Yes

Checks if the current user is authenticated.

info.magnolia.voting.voters.ExtensionVoter

  • allow: comma separated lists of allowed extensions.

  • deny: comma separated lists of denied extensions.

Yes

  • Returns false if the extension is not a valid mimetype (as configured in config:/server/MIMEMapping.

  • Returns false if the allow list exists, but the extension is not in the allow list.

  • Returns false if the deny list exists and the extension is in the deny list.

  • Returns true in any other cases.
For further information, see the voters package summary.
Feedback

DX Core

×

Location

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

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules