Deploy as a WAR in JBoss EAP 7 - Documentation topics on: dotcms war,eap,ejb,j2ee,jboss,redhat,war,.

Deploy as a WAR in JBoss EAP 7

Note:

  • This document includes only installation steps specific to this application server.
  • Before following the steps below, please review and follow the general instructions in the WAR Installation documentation.

The following steps are required to install dotCMS on JBoss EAP 7. Please click on the links below for more detail on each step.

1. Add JDBC drivers and ByteBuddy modules to JBoss

The JDBC drivers and ByteBuddy jar can be found in the following GitHub repo: https://github.com/dotCMS/appservers-config. These are used for the -javaagent vm option (see step 2, below).

Linux:

A. Clone the repository https://github.com/dotCMS/appservers-config into a folder
B. Navigate to the folder where you cloned the appservers-config repo
C. Copy all subfolders in jboss/modules to the modules/system/layers/base folder in the JBoss distribution, as follows:

cp -a $APPSERVERS-CONFIG-REPO/docs/examples/jboss/modules/* $JBOSS_HOME/modules/system/layers/base/.
Windows:

A. Clone the repository https://github.com/dotCMS/appservers-config into a folder
B. In Windows Explorer, navigate to the folder where you cloned the appservers-config repo
C. Copy all subfolders in jboss\modules to the modules\system\layers\base folder in the JBoss distribution.

2. Edit the JBoss standalone configuration file

These changes set the javaagent option that allow dotCMS to use the java instrumentation.

Linux:

Edit $JBOSS_HOME/bin/standalone.conf and replace the section shown here:

if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS="-Xms1303m -Xmx1303m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true"
   JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"
else
   echo "JAVA_OPTS already set in environment; overriding default settings with values: $JAVA_OPTS"
fi

with the following:

if [ "x$JAVA_OPTS" = "x" ]; then
   if [ -n "$JBOSS_MODULES_SYSTEM_PKGS" ]; then
      JBOSS_MODULES_SYSTEM_PKGS="$JBOSS_MODULES_SYSTEM_PKGS,net.bytebuddy.agent"
   else
      JBOSS_MODULES_SYSTEM_PKGS="net.bytebuddy.agent"
   fi

   JAVA_OPTS="-Xms1303m -Xmx1303m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true"
   JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"
   JAVA_OPTS="$JAVA_OPTS -javaagent:$DOTCMS_HOME/WEB-INF/lib/byte-buddy-agent-1.6.12.jar"
else
   echo "JAVA_OPTS already set in environment; overriding default settings with values: $JAVA_OPTS"
fi
Windows:
  1. Set the %JBOSS_HOME% environment variable to point to the JBoss distribution directory.
  2. Edit %JBOSS_HOME%\bin\standalone.conf.bat and replace the line shown here:
set "JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=net.bytebuddy.agent"

with the following:

if not "x%JBOSS_MODULES_SYSTEM_PKGS%" == "x" (
  set "JBOSS_MODULES_SYSTEM_PKGS=%JBOSS_MODULES_SYSTEM_PKGS%,org.jboss.byteman,net.bytebuddy.agent"
)

if "x%JBOSS_MODULES_SYSTEM_PKGS%" == "x" (
  set JBOSS_MODULES_SYSTEM_PKGS=org.jboss.byteman,net.bytebuddy.agent
)
set "JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=%JBOSS_MODULES_SYSTEM_PKGS% -Djava.awt.headless=true"

set "JAVA_OPTS=%JAVA_OPTS% -javaagent:%JBOSS_HOME%\modules\system\layers\base\net\bytebuddy\agent\main\byte-buddy-agent-1.6.12.jar"

3. Edit the $JBOSS_HOME/standalone/configuration/standalone.xml file

A. Configure the server to deploy the dotCMS ROOT.war on context root, as follows:

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="server-header"/>
            <filter-ref name="x-powered-by-header"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
        <websockets/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/standalone/deployments/ROOT.war"/>
    </handlers>
    <filters>
        <response-header name="server-header" header-name="Server" header-value="JBoss-EAP/7"/>
        <response-header name="x-powered-by-header" header-name="X-Powered-By" header-value="Undertow/1"/>
    </filters>
</subsystem>

B. Update the datasources section to include your driver DB and set the details for your datasource connection. For example, for postgres a basic configuration would be:

<datasource jndi-name="java:/jdbc/dotCMSPool" pool-name="jdbc/dotCMSPool" enabled="true" use-java-context="true">
       <connection-url>jdbc:postgresql://localhost:5432/dotcms</connection-url>
       <driver>postgresql</driver>
       <security>
             <user-name>postgres</user-name>
             <password>postgres</password>
       </security>
</datasource>
<drivers>
       <driver name="postgresql" module="com.dotcms.postgres">
             <driver-class>org.postgresql.Driver</driver-class>
       </driver>
</drivers>

Note: consider to set the correct connection parameters (min/max connections allowed, transaction timeouts, etc) according to your environment needs. This example is used as a reference.

C. Modify the default mail session by java:/mail/MailSession

<subsystem xmlns="urn:jboss:domain:mail:2.0">
    <mail-session name="mail-smtp" jndi-name="java:/mail/MailSession">
        <smtp-server outbound-socket-binding-ref="mail-smtp"/>
    </mail-session>
</subsystem>

4. Deploy the exploded WAR file

Linux:
cd $DISTRIBUTION/WAR
unzip ROOT.war -d $JBOSS_HOME/standalone/deployments/ROOT.war
cd $JBOSS_HOME/standalone/deployments/
touch ROOT.war.dodeploy
Windows:

A. In Windows Explorer, change to the WAR folder in the dotCMS distribution
B. Rename ROOT.war to ROOT.war.zip
C. Right-click ROOT.war.zip and select “Extract All”
D. Click the Extract button in the dialog box
E. Move or copy the ROOT.war folder to the standalone\deployments folder in the JBoss distribution
F. Right-click in the standalone\deployments folder in the JBoss distribution and select New ==> Text File
G. Rename the file to ROOT.war.dodeploy
H. Click the Yes button to confirm changing the file extension

*Login to the dotCMS back-end and add an Enterprise license.

*Note: Running dotCMS as a WAR file is only supported in dotCMS Enterprise edition, so the dotCMS front-end will not run without an Enterprise license.

5. Un-deploying the WAR

To un-deploy the exploded WAR:

Linux:
rm $JBOSS_HOME/standalone/deployments/ROOT.war.deployed
Windows:

Remove the ROOT.war.deployed file in the JBoss standalone\deployments directory.

6. Create jboss-web.xml and jboss-deployment-structure.xml files under $JBOSS_HOME/standalone/deployments/ROOT.war/WEB-INF/lib

In the jboss-web.xml file you need to set the default context-root for the application, as follows:

<?xml version="1.0" encoding="UTF-8"?>
<jboss-web xmlns="http://www.jboss.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-web_5_1.xsd">
<context-root>/</context-root>
</jboss-web>

On the other hand, in the jboss-deployment-structure.xml you need to exclude the org.apache.commons.logging module that is used by JBoss by default, in order to avoid conflict with slf4j used by dotCMS.

<jboss-deployment-structure>
   <deployment>
      <exclusions>
          <module name="org.apache.commons.logging" />
      </exclusions>
   </deployment>
</jboss-deployment-structure>

7. Add or edit the admin user to JBoss

Run the JBoss add-user script:

Linux:

Linux:

bin/add-user.sh

Windows:

bin\add-user.bat

Then perform the following steps (on both Linux and Windows):

A. Select Management User (a).
B. UserName: admin
C. Type yes and press Enter to confirm
D. Password: [Enter a Password]
E. When prompted for groups, press Enter for no groups.
F. Type yes and press Enter to confirm.
G. When prompted “Is this user going to be used for one AS process to connect to another AS process?“, type no and press Enter.

8. Start the JBoss server

Linux:
bin/standalone.sh
Windows:
bin\standalone.bat