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

Deploy as a WAR in JBoss EAP 6

Before following these steps that are specific to this application server, please review the documentation on deploying dotCMS as a .WAR.

1. Deploy JDBC drivers and jamm jar from the dotCMS distribution to the JBoss distribution.

The JDBC drivers and jamm jar are located in the dotCMS distribution under the docs folder (docs/examples/jboss/). These are used for the -javaagent vm option (see step 2, below).

Linux:
cp -a $DISTRIBUTION/docs/examples/jboss/modules/* $JBOSS_HOME/modules/system/layers/base/.
Windows:

A. In Windows Explorer, navigate to the docs\examples\jboss\modules folder in the dotCMS distribution.

B. Copy all subfolders in docs\examples\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,org.github.jamm"
   else
      JBOSS_MODULES_SYSTEM_PKGS="org.github.jamm"
   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:$JBOSS_HOME/modules/system/layers/base/org/github/jamm/main/dot.jamm-0.2.5_2.jar"
else
   echo "JAVA_OPTS already set in environment; overriding default settings with values: $JAVA_OPTS"
fi
Windows:

A. Set the %JBOSS_HOME% environment variable to point to the JBoss distribution directory.

B. Edit %JBOSS_HOME%\bin\standalone.conf.bat and replace the line shown here:

set "JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman"

with the following:

if not "x%JBOSS_MODULES_SYSTEM_PKGS%" == "x" (
  set "JBOSS_MODULES_SYSTEM_PKGS=%JBOSS_MODULES_SYSTEM_PKGS%,org.jboss.byteman,org.github.jamm"
)

if "x%JBOSS_MODULES_SYSTEM_PKGS%" == "x" (
  set JBOSS_MODULES_SYSTEM_PKGS=org.jboss.byteman,org.github.jamm
)
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\org\github\jamm\main\dot.jamm-0.2.5_2.jar"

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

A. Set enable-welcome-root to false to prevent the welcome functionality running in the root context.

   <virtual-server name="default-host" enable-welcome-root="false">
      <alias name="localhost"/>
      <alias name="example.com"/>
   </virtual-server>

B. Update the drivers section to include dotCMSh2 driver.

   <drivers>
      <driver name="h2" module="com.h2database.h2">
         <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
      </driver>
      <driver name="dotCMSh2" module="com.dotcms.h2">
         <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
      </driver>
   </drivers>

4. Add the admin user to JBoss.

Run the JBoss add-user script:

Linux:
bin/add-user.sh
Windows:
bin\add-user.bat

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

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

5. Start the JBoss server.

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

6. Add the dotCMS datasource.

A. Open the Data Sources configuration in the JBoss management console.

http://localhost:9990/console/App.html#datasources

B. Click the Add button, and add a data source with the following parameters:

  • Name = dotCMSPool
  • jndi name = java:/jdbc/dotCMSPool
    • Click the Next button.
  • Select the dotCMSh2 driver.
    • Click the Next button.
  • Connection url = jdbc:h2:h2_dotcms_data;MVCC=TRUE
  • Username: sa
  • Password: sa
    • Click the Done button.*
  • Click on dotCMSPool in the list and click the Enable button.
  • Click the Confirm button.

7. Add a Mail session

A. Open the Mail session configuration in the JBoss management console.

http://localhost:9990/console/App.html#mail

B. Click the Add button, and add a mail session with the following parameter:

  • jndi name = java:/mail/MailSession
  • Click the Save button.

8. Deploy the exploded WAR file

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

A. In Windows Explorer, change to the WAR folder in the dotCMS distribution. B. Rename dotcms.war to dotcms.war.zip. C. Right-click dotcms.war.zip and select Extract All….

  • Click the Extract button in the dialog box. D. Move or copy the dotcms.war folder to the standalone\deployments folder in the JBoss distribution. E. Right-click in the standalone\deployments folder in the JBoss distribution and select New ==> Text File.

  • Rename the file to dotcms.war.dodeploy.

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

Un-deploying the WAR

To un-deploy the exploded WAR:

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

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

Using a Database Other than H2

The steps above are complete when deploying dotCMS with the H2 database. If you wish to use a different database, you will need to modify steps 3B and 6B above to configure the appropriate database instead of the H2 database.

In addition, the WEB-INF\jboss-deployment-structure.xml file in the exploded WAR folder references the h2 database module by default. When using a database other than H2, you must modify the jboss-deployment-structure.xml file as needed for your database.

For more information on how to edit the jboss-deployment-structure.xml file, please see the JBoss forums and the JBoss documentation.

Special Note Regarding dotCMS 3.2.4

You may encounter errors when deploying dotCMS 3.2.4 as a WAR in JBoss EAP 6. To correct these errors, replace the WEB-INF\jboss-deployment-structure.xml in the exploded dotCMS 3.2.4 WAR with the same file from the exploded dotCMS 3.3 WAR.