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 |
|
|
2 |
Module properties |
|
|
3 |
Global file properties |
web application |
|
4 |
Default file properties |
web application |
|
5 |
Web application file properties |
web application |
|
6 |
Server file properties |
web application |
|
7 |
Web application at server file properties |
web application |
|
8 |
System properties |
JVM options ( |
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 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 | ||
---|---|---|---|
|
required default is Name of a log4j config file. Can be a .properties or .xml file. The value can be:
|
||
|
required default is 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. |
||
|
Directory used for cached pages. In the |
||
|
optional default is Co-specifies a content bootstrapping strategy. The following values can be used:
|
||
|
optional The directory to import file system files from with the Content Importer module. If the path is not set, the module is stopped. |
||
|
optional default is Co-specifies a content bootstrapping strategy.
|
||
|
optional default is Specifies which filenames will be imported and observed in the content
bootstrap directory defined by the |
||
|
required if you deploy on a WebSphere, Liberty or JBoss application server Value must be set to |
||
|
required default is History directory used for publishing. |
||
|
required default is Repository configuration, points to an XML file. |
||
|
optional default is Magnolia logs each JCR query exceeding the threshold in milliseconds. |
||
|
required if you have any clustered workspaces in your project default is 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
|
||
|
required default is Temporary directory for uploaded files. |
||
|
optional default is Location of private and public activation keys used for publishing. |
||
optional default is 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
Since 6.2.37, new Magnolia bundles use |
|||
|
optional default is Sets an instance as author ( |
||
|
optional default is Some modules contain optional sample content. They will check this property to decide if they should install the content. |
||
|
optional List of component class names to be excluded from component instantiation. Separate class names with white space (space, tab) or commas. |
||
|
optional default is
Set to |
||
|
optional default is Root of the webapp’s deployment directory. See also Modifying the magnolia.home property above on this page. |
||
|
optional default is Enables support for JSR-250 annotations. Magnolia uses the
|
||
|
optional default is Directory where logs are written. |
||
|
optional default is Turns off migration report generation to speed up the migration process.
Set to |
||
|
optional default is Repository home directory. |
||
|
optional default is Jackrabbit
configuration file. See the |
||
|
optional Jackrabbit configuration file for a clustered repository.
|
||
|
optional default is Pattern to define which resources should be observed by
|
||
|
optional default is Defines the directory from which filesystem resources such as light modules are loaded in a Magnolia instance. |
||
|
optional default is List of excluded resource directories in FileSystemResourceOrigin.
|
||
|
optional default is no excluded packages List of resource packages that should be excluded by the resource filter of
|
||
|
optional default is The sensitivity (speed) with which the changes of the
resources in the Possible values: |
||
|
optional default is Set to |
||
|
optional default is Activate UTF-8 support for pages.
|
||
|
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. |
||
|
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.
On the author instance, the following sticker appears:
The instance name is taken from the
The instance info sticker was originally released with Magnolia 5.6.3 as
the |
||
|
|||
|
optional default is The number of aliases for |
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:
|
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.
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.
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:
|
||
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 |
|
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
, orboolean
(to specifytrue
, you can usetrue
,TRUE
, or1
) with the suitablesetter
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.
Numbered items:
-
config
: Entry point of the transformation. In the module descriptorSampleConfig
class is used. Settext
andnumber
properties. -
sub
: Subbean. The class is determined using reflection if it is not explicitly defined. -
items
: Collection. The correspondingadd
method is used to determine the class and populate the collection if existing. -
item2
: Special item with its own class and additional properties. -
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.
This is what happens with setCachePolicy(CachePolicy cachePolicy)
:
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
:
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
for a
true'' and
0false
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 |
|
Yes |
|
For further information, see the voters package summary.
|