You can deploy Magnolia to multiple environments using a single Web
application archive (WAR) file. The WAR file can contain several
configurations, each customizing the application to a particular target
environment. The appropriate configuration is applied automatically when
the WAR file is extracted on a servlet container.
You can see this mechanism in action in a standard Magnolia
installation. The standard installation deploys two webapps:
magnoliaAuthor is the authoring instance where content editors work
and magnoliaPublic is the public website. The two webapps are
identical. The name of the webapp determines which configuration is
applied at deployment time.
Since the webapp is named after the WAR file (magnoliaAuthor.war is
extracted to magnoliaAuthor) you can select a different configuration
by simply renaming the WAR.
This approach has the advantage that you only need to compile the webapp
once. It is not necessary to create separate WAR files for each target
environment.
Where to use
Here are some ideas where multiple configurations in a single WAR are
useful:
Author vs. Public. This is the standard example. One webapp is
configured as an author instance that takes authors and editors into the
AdminCentral UI while the other webapp is a public instance that
displays the published website.
Set different storage mechanisms. The embedded Derby database that
ships with Magnolia is OK for development and testing purposes but in
production you need enterprise-scale persistent storage. You can
configure different persistent storage for production servers, for
example a MySQL database. When the WAR file is deployed to a production
server the external database is used.
Bootstrap content to a test environment. Load some test user
accounts and content to a test environment through the bootstrap
mechanism. When you deploy the same webapp to production no test content
is deployed and the production environment stays clean.
Configure repositories. With a custom repository configuration you
can retrieve production users from a central repository or connect to a
shared DMS for corporate assets such as documents and images.
Context listener reads properties files
Magnolia’s main listener
MagnoliaServletContextListener
reads initialization parameters for each webapp from
magnolia.properties files. By default, the listener looks for
properties files in these locations:
These properties files are in the WEB-INF/config directory inside the
WAR. You can configure alternative file names and locations by setting
the magnolia.initialization.file context parameter in web.xml.
Multiple comma-separated paths are supported. The listener applies the
properties files in a last-to-first order, loading the files in reverse
of what you see in the list above.
Using variables
You can use variables to map a configuration to its target environment.
When the context listener finds a match it reads the corresponding
properties file and applies the properties.
${servername}
${servername} is the name of the server where the webapp is running.
Use lowercase. This variable is resolved to a fully qualified server
name obtained using InetAddress.getLocalHost().getHostName() which may
also contain the domain depending on your server configuration and
operating system. Optionally, you can set the
magnolia.unqualified.server.name context parameter to true in
web.xml if you prefer using an unqualified name. Now
server.domain.com will simply resolve to server.
${webapp} is the last token in the webapp path, for example
magnoliaPublic for a webapp deployed at
tomcat/webapps/magnoliaPublic.
${contextAttribute/property} and ${contextParam/property}
You can also use servlet context attributes and parameters to indicate
the location of configuration files. These variables will be replaced
with the corresponding attributes or parameters taken from servlet
context. This is useful for application servers such as IBM WebSphere
that have multiple instances running on the same server. Typical usage
in this case:
See your servlet container documentation regarding where to define
context parameters and attributes. For example
Tomcat
Context container reference.
Naming conventions
The short variable names are used only in web.xml when resolving. For
example, ${webapp} is a property that is used when resolving paths to
magnolia.properties files, that is when parsing the string containing
the list of said files in web.xml. The corresponding variable you can
use in the properties files is ${magnolia.webapp}. This variable
corresponds to the name of the folder into which Magnolia is deployed,
typically magnoliaAuthor on Tomcat. Similarly, ${servername} will correspond to ${magnolia.servername}. You also have
${magnolia.app.rootdir} which is the full path to the deployed app.
Path examples
Here are some path examples and webapps the properties apply to:
Default configuration that applies to all webapps.
WEB-INF/config/magnolia.propertiesCopy
Author instances that have the default webapp name magnoliaAuthor.
magnolia.properties file contains properties that are not configured
in the config repository. They are applied at deployment time before
repositories are initialized.
Here is a minimal example of a properties file:
# This is only used for the initial installation.
# Afterwards the configuration in the config repository is used.
# The value is saved in /server/admin
magnolia.bootstrap.authorInstance=falsehttps://docs.magnolia-cms.com/product-docs/6.2/Apps/Developing-a-custom-non-jcr-content-app.html#_final_assembly{
# Directories in which bootstrap files are searched
magnolia.bootstrap.dir=WEB-INF/bootstrap/public WEB-INF/bootstrap/common
Copy
Setting the magnolia.bootstrap.authorInstance property to false
defines this webapp as a public instance. The webapp is given its own
bootstrap directory in the magnolia.bootstrap.dir property.
Compile a WAR file, name it to match one of the webapps, and deploy
the WAR on a servlet container on the target server.
As the WAR is deployed on the container, the context listener applies
any properties that match the path constructed after applying all
variables; server name, webapp name and any context parameters and
attributes.
To test another deployment configuration, change the name of the WAR
file and deploy again. A configuration that matches the new name will
now be used.
You can follow the procedure above by compiling your own WAR file in an
integrated development environment (IDE) such as Eclipse. Or, if you
just want to try the multiple configuration mechanism, download the
standalone Magnolia WAR file
(Community
Edition, DX Core) and change the file
extension to .zip. Extract the zip, make your configuration changes in
the extracted files, zip them again and change the extension back to
.war. Now you can deploy the WAR to a servlet container. See
http://svn.magnolia-cms.com/svn/community/projects/ in SVN for more
examples.
Watch logs/magnolia-debug.log for notifications. The log tells you
which configuration files are loaded during deployment.
2010-08-13 16:13:12,245 DEBUG MagnoliaServletContextListener: servername is dev-mac.local, rootPath is /Applications/tomcat/webapps/devAuthor, webapp is devAuthor
2010-08-13 16:13:12,246 DEBUG MagnoliaServletContextListener: magnolia.initialization.file value in web.xml is: 'WEB-INF/config/${servername}/${webapp}/magnolia.properties, WEB-INF/config/default/magnolia.properties, WEB-INF/config/magnolia.properties'
2010-08-13 16:13:12,839 INFO PropertiesInitializer: Loading configuration at /Applications/tomcat/webapps/devAuthor/WEB-INF/config/default/magnolia.properties
2010-08-13 16:13:12,840 INFO PropertiesInitializer: Loading configuration at /Applications/tomcat/webapps/devAuthor/WEB-INF/config/dev-mac.local/devAuthor/magnolia.properties
Copy
Vaadin configuration changes for Magnolia 6.2.20 or later
Due to a Vaadin update in Magnolia 6.2.20, custom setups require a change in the web.xml configuration file (in a custom webapp’s WAR under the WEB-INF/ directory). In particular, you should add the following parameters.
<context-param><description>Vaadin production mode</description><param-name>productionMode</param-name>(1)<param-value>true</param-value>(2)</context-param><context-param><param-name>heartbeatInterval</param-name><param-value>90</param-value></context-param>Copy
1
Ensure the Vaadin productionMode parameter is present.
2
The value should be true.
If you do not set productionMode to true, you’ll receive errors when starting your custom webapp showing that it’s unable to validate your Vaadin subscription.