Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
This page describes how to deploy Magnolia to IBM WebSphere Liberty, a fast and easy-to-use Java application server, built on the open source Open Liberty project. For details about deploying Magnolia on the "traditional" IBM WebSphere Application Server, please see the Deploying a WAR on IBM WebSphere page.
Installing
If you are installing your own custom webapp, make sure that it uses the magnolia-module-websphere
module in version 1.5
(or later). This version bypasses the JAAS configuration set by WebSphere Liberty and instead uses a JAAS configuration from java.security.auth.login.config
. The module in this version is part of Magnolia WebSphere WAR files since Magnolia 5.7.2 release.
As a Magnolia WAR file
You can deploy Magnolia to WebSphere Liberty as a WAR file. Get the latest version of the WAR file from our files.magnolia-cms.com server (access restrictions may apply).
As a custom webapp
If you are building and installing a custom webapp, you need the WebSphere compatibility module. Maven is the easiest way to it. Add the following to your webapp:
A pre-built jar is also available for download:
Adding the Spool servlet to web.xml
The Spool servlet must be registered for WebSphere Liberty. Follow these steps to add the servlet to the deployment descriptor (web.xml file) in your webapp:
- Make sure the
magnolia-module-websphere
jar file is your webapp'sWEB-INF/lib
directory. Edit the
web.xml
file, and add the followingServlet
definition:<servlet> <description>Spool servlet</description> <servlet-name>Spool</servlet-name> <servlet-class>info.magnolia.module.websphere.Spool</servlet-class> <init-param> <param-name>Path</param-name> <param-value>/docroot</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>Spool</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping>
Note that the
Servlet
must be mapped to serve/*
, but you can adapt thePath
parameter to allow it to serve other static resources from your webapp.
Server configuration
The following two subsections describe elements of WebSphere server configuration you could modify depending on your preferences. By default, the path and file name for the configuration root document file is <path_to_liberty>/wlp/usr/servers/<server_name>/server.xml
.
Deployment locations
dropins
directory
You can deploy Magnolia to WebSphere Liberty by dropping the magnoliaAuthor.war
and magnoliaPublic.war
files to the ${server.config.dir}/dropins
directory. Be aware that if you choose this deployment folder, the WAR files are automatically expanded into the
${server.config.dir}/apps/expanded
directory with each server start, causing any modification of your installation to be lost.
To avoid the automatic expansion at server starts, create subdirectories called magnoliaAuthor.war
and magnoliaPublic.war
in the application directory path and extract the archive there.
apps
directory
To keep any custom modification of the webapp or application-specific configuration across server restarts, unpack the WAR files to the apps
directory and define the paths to them in the server configuration, as is shown in the example configuration below on lines 11 and 12:
<server description="Magnolia server"> <!-- Enable features --> <featureManager> <feature>webProfile-8.0</feature> <feature>adminCenter-1.0</feature> <feature>transportSecurity-1.0</feature> <feature>appSecurity-2.0</feature> </featureManager> <webApplication location="/VM/wlp/usr/servers/magnolia/apps/magnoliaAuthor"/> <webApplication location="/VM/wlp/usr/servers/magnolia/apps/magnoliaPublic"/> <quickStartSecurity userName="admin" userPassword="adminpwd" /> <keyStore id="defaultKeyStore" password="Liberty" /> <!-- To access this server from a remote client add a host attribute to the following element, e.g. host="*" --> <httpEndpoint id="defaultHttpEndpoint" httpPort="9080" httpsPort="9443" /> <!-- Automatically expand WAR files and EAR files --> <applicationManager autoExpand="true"/> <applicationMonitor updateTrigger="disabled"/> </server>
Avoiding application restarts at updates
Irrespective of whether you deploy Magnolia in the dropins
directory or the location defined in the server.xml
file, the applications are restarted whenever you add, remove or modify any files within a deployed application, or you replace the whole application with an updated version. This is the default behavior but you can bypass it in two ways:
- By adding the
<applicationMonitor updateTrigger="disabled"/>
line to the configuration of the server, as is shown on line 26 above. - By setting the Magnolia
${magnolia.home}
property outside the webapp directory. The property's default value, which is set in themagnolia.properties
file, is the full path to the deployed app.