Deploying a WAR on WebSphere Liberty

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. 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:

• Error rendering macro 'artifact-resource-macro'

  com.sun.jersey.api.client.ClientHandlerException: java.net.NoRouteToHostException: No route to host (Host unreachable)

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:

1. Make sure the magnolia-module-websphere jar file is your webapp's WEB-INF/lib directory.

2. Edit the web.xml file, and add the following Servletdefinition:

   <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 the Path 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 the magnolia.properties file, is the full path to the deployed app.

See also

• Getting started with Liberty
• Getting Liberty
• Installing Liberty
• Deploying applications in Liberty
• Open Liberty