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
As a Magnolia WAR file
You can deploy Magnolia to WebSphere Liberty as a WAR file.
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:
Deploying WebSphere Liberty manually
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.- Set the
magnolia.definitions.classpath
property inmagnolia.properties
toinfo.magnolia
.
Setting up JAAS Authentication for Magnolia
Create a JVM options file to point to the
jaas.config
file provided by Magnolia:-Djava.security.auth.login.config=${server.config.dir}apps/expanded/magnoliaAuthor.war/WEB-INF/config/jaas.config
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
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.
Known Issues
JSESSIONID Length
detected jsessionid with invalid length expected length of 23 found 28
See jsessionids do not match expected length are ignored and warning messages are logged.
Solution: Update
server.xml
<httpSession cookieName="admincentral"/>