Deploying a WAR on JBoss WildFly or EAP

This page describes how to deploy Magnolia as a WAR file on WildFly, formerly known as JBoss Application Server. The procedures described below have been checked for WildFly 11+. Magnolia 5.7 requires WildFly 11 or later for compatibility. This page was also verified with JBoss EAP 7.

Preliminaries

Configuring JAAS login

Magnolia uses the Java Authentication and Authorization Service (JAAS) to authenticate and authorize users. You have to configure the JAAS login modules for WildFly so that you can log into Magnolia:

1. Open $WILDFLY_HOME/standalone/configuration/standalone.xml .
2. Add the following login modules in the <subsystem xmlns="urn:jboss:domain:security:1.2> section:

<subsystem xmlns="urn:jboss:domain:security:1.2">
    <security-domains>
        <security-domain name="magnolia" cache-type="default">
           <authentication>
              <login-module code="info.magnolia.jaas.sp.jcr.JCRAuthenticationModule" flag = "requisite" />
              <login-module code="info.magnolia.jaas.sp.jcr.JCRAuthorizationModule" flag = "required" />
           </authentication>
        </security-domain>
        <security-domain name="Jackrabbit" cache-type="default">
           <authentication>
              <login-module code="org.apache.jackrabbit.core.security.SimpleLoginModule" flag = "required" />
           </authentication>
        </security-domain>
        <security-domain name="other" cache-type="default">
            <authentication>
                <login-module code="org.apache.jackrabbit.core.security.SimpleLoginModule" flag="required"/>
            </authentication>
        </security-domain>
    </security-domains>
</subsystem>

Magnolia Workflow

When using Magnolia's worklow modules you might experience class loading issue related to packages of org.jboss.weld.*. In this case create or edit jboss-deployment-structure.xml file in Magnolia's WEB-INF folder by adding the following code.

<?xml version="1.0"?>
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
    <deployment>
        <exclude-subsystems>
            <subsystem name="weld" />
        </exclude-subsystems>
    </deployment>
</jboss-deployment-structure>

Bouncy Castle

Magnolia uses the Bouncy Castle cryptography package to decode the license key and to secure the activation process. WildFly ships with a slightly older version of these libraries.

1. Find the BC module folder in $WILDFLY_HOME/modules/system/layers/base/org/bouncycastle/main.
     JBoss EAP $EAP_HOME/modules/system/layers/base/org/bouncycastle/main

2. Remove all the existing jar files.
3. Place the required Bouncy Castle JAR files in the folder:
   
   • Provider bcprov

   • PKIX bcpkix

   • OpenPGP/BCPG bcpg
   • SMIME bcmail

4. Edit the module.xml file in the same folder.

   module.xml

   <?xml version="1.0" encoding="UTF-8"?>
   <module xmlns="urn:jboss:module:1.1" name="org.bouncycastle">
     <resources>
       <resource-root path="bcprov-jdk15on-1.58.jar"/>
       <resource-root path="bcpkix-jdk15on-1.58.jar"/>
       <resource-root path="bcpg-jdk15on-1.58.jar"/>
       <resource-root path="bcmail-jdk15on-1.58.jar"/>
     </resources>
     <dependencies>
       <module name="javax.api" slot="main" export="true"/>
     </dependencies>
   </module>

5. Create or edit jboss-deployment-structure.xml file in Magnolia's WEB-INF folder by adding the following code.

   jboss-deployment-structure.xml

   <?xml version="1.0"?>
   <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
       <deployment>
           <dependencies>
             <module name="org.bouncycastle" slot="main" export="true" />
           </dependencies>
       </deployment>
   </jboss-deployment-structure>

Configuring Log4j

WildFly Application Server adds its own log4j logging configuration. If you want to use your own log4j logging configuration (or the one provided by Magnolia) in your deployment, exclude the default configuration first.

Create a new file jboss-deployment-structure.xml under the WEB-INF folder with this content:

<jboss-deployment-structure>
  <deployment>
    <exclusions>
      <module name="org.apache.log4j" />
      <module name="org.slf4j" />
    </exclusions>
  </deployment>
</jboss-deployment-structure>

Resteasy class loading issue

During a deployment the Resteasy libraries can cause a class loading issue when the RestClient module is used. You can get rid of the issue by excluding the following subsystems in the <deploymenŧ> element of the jboss-deployment-structure.xml file:

<exclude-subsystems>
 <subsystem name="jaxrs" />
 <subsystem name="resteasy" />
</exclude-subsystems>

Deployment options

Deploying a WAR

To deploy the downloaded Magnolia WAR file to WildFly:

1. Rename the Magnolia WAR file to magnoliaAuthor.war.
2. Make a copy of the file and rename it to magnoliaPublic.war .
3. Copy the files to $WILDFLY_HOME/standalone/deployments .

The application server will automatically pick up the files and deploy them.

magnolia.home=/somewhere_outside_of_wildfly_tmp_folder
magnolia.cache.startdir=${magnolia.home}/cache
magnolia.upload.tmpdir=${magnolia.home}/tmp
magnolia.exchange.history=${magnolia.home}/history
magnolia.repositories.home=${magnolia.home}/repositories
magnolia.logs.dir=${magnolia.home}/logs

Deploying extracted directories

To deploy an extracted directory:

1. Extract the Magnolia WAR file to the /magnoliaAuthor.war directory.
2. Extract the Magnolia WAR file also to the /magnoliaPublic.war directory.
3. Copy the directories to $WILDFLY_HOME/standalone/deployments.
4. Create empty files magnoliaAuthor.war.dodeploy and magnoliaPublic.war.dodeploy in the $WILDFLY_HOME/standalone/deployments directory.

The application server will pick up the extracted directories on startup and will deploy them.

Starting WildFly and accessing Magnolia

1. Restart WildFly.
2. Access Magnolia Author instance at http://localhost:8080/magnoliaAuthor/.
3. Access Magnolia Public instance at http://localhost:8080/magnoliaPublic/.

<subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1">
   <deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000" deployment-timeout="120"/>
</subsystem>

   JAVA_OPTS="-Xms64m -Xmx1024m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m -Djava.net.preferIPv4Stack=true"

Changing the context path

Without the WAR file placed under WEB-INF folder, the context path will be the web application's folder name by default.

1. Stop WildFly.
2. Create a jboss-web.xml file in WEB-INF folder of your Magnolia instance.

3. Add the following section in the file. Replace YourContextPath with your actual context path which can be / for a public instance, for example.

   <jboss-web>
      <context-root>/YourContextPath</context-root>
   </jboss-web>
   

   Restart WildFly. Your webapp should be available at http://localhost:8080/<YourContextPath>.

Learn more

Getting Started with WildFly

JBoss AS JNDI Datasource Setup