Deploy as a WAR in Wildfly 17 documentation for the dotCMS Content Management System


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 WildFly 17. Please click on the links below for more detail on each step.

1. Add JDBC drivers and ByteBuddy modules to WildFly

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

  • Clone the repository into a folder
  • Navigate to the folder where you cloned the appservers-config repo
  • Copy all subfolders in jboss/modules to the modules folder in the WildFly distribution, as follows: cp -a $APPSERVERS-CONFIG-REPO/docs/examples/jboss/modules/* $WILDFLY_HOME/modules/.
  • Clone the repository 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 folder in the Wildfly distribution.

2. Edit the Wildfly standalone configuration file

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


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

if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS="-Xms64m -Xmx512m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m"
   JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"
   echo "JAVA_OPTS already set in environment; overriding default settings with values: $JAVA_OPTS"

with the following:

if [ "x$JAVA_OPTS" = "x" ]; then

   if [ -n "$JBOSS_MODULES_SYSTEM_PKGS" ]; then

   JAVA_OPTS="-Xms64m -Xmx512m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m"
   JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"
   JAVA_OPTS="$JAVA_OPTS -javaagent:/Users/nollymar/Documents/workspace-dotcms/wildfly-17.0.1.Final/standalone/deployments/ROOT.war/WEB-INF/lib/byte-buddy-agent-1.6.12.jar"
   echo "JAVA_OPTS already set in environment; overriding default settings with values: $JAVA_OPTS"

Set the %WILDFLY_HOME% environment variable to point to the WildFly distribution directory. Edit %WILDFLY_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"

  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:%WILDFLY_HOME%\modules\net\bytebuddy\agent\main\byte-buddy-agent-1.6.12.jar"

3. Edit the $WILDFLY_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:9.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other" statistics-enabled="${wildfly.undertow.statistics-enabled:${wildfly.statistics-enabled:false}}">
  <buffer-cache name="default"/>
  <server name="default-server">
      <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
      <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
      <host name="default-host" alias="localhost">
          <location name="/" handler="welcome-content"/>
          <filter-ref name="server-header"/>
          <filter-ref name="x-powered-by-header"/>
  <servlet-container name="default">
      <file name="welcome-content" path="${jboss.home.dir}/standalone/deployments/ROOT.war"/>
      <response-header name="server-header" header-name="Server" header-value="WildFly/17"/>
      <response-header name="x-powered-by-header" header-name="X-Powered-By" header-value="Undertow/1"/>

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">
         <driver name="postgresql" module="com.dotcms.postgres">

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.

Also, update the default binding to use your datasource configuration (in case you do not have any other datasource configured):

<subsystem xmlns="urn:jboss:domain:ee:4.0">
            <context-service name="default" jndi-name="java:jboss/ee/concurrency/context/default" use-transaction-setup-provider="true"/>
            <managed-thread-factory name="default" jndi-name="java:jboss/ee/concurrency/factory/default" context-service="default"/>
            <managed-executor-service name="default" jndi-name="java:jboss/ee/concurrency/executor/default" context-service="default" hung-task-threshold="60000" keepalive-time="5000"/>
            <managed-scheduled-executor-service name="default" jndi-name="java:jboss/ee/concurrency/scheduler/default" context-service="default" hung-task-threshold="60000" keepalive-time="3000"/>
    <default-bindings context-service="java:jboss/ee/concurrency/context/default" datasource="java:/jdbc/dotCMSPool" managed-executor-service="java:jboss/ee/concurrency/executor/default" managed-scheduled-executor-service="java:jboss/ee/concurrency/scheduler/default" managed-thread-factory="java:jboss/ee/concurrency/factory/default"/>

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"/>

4. Deploy the exploded WAR file

unzip ROOT.war -d $WILDFLY_HOME/standalone/deployments/ROOT.war
cd $WILDFLY_HOME/standalone/deployments/
touch ROOT.war.dodeploy

A. In Windows Explorer, change to the WAR folder in the dotCMS distribution B. Rename ROOT.war to C. Right-click 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 WildFly distribution F. Right-click in the standalone\deployments folder in the WildFly 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:
    rm $WILDFLY_HOME/standalone/deployments/ROOT.war.deployed


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

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

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="" xmlns:xsi=""

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

          <module name="org.apache.commons.logging" />

7. Add or edit the admin user to WildFly

Run the WildFly add-user script:





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 WildFly server





9. How to turn on your custom log4j logging (Optional Step)

This step is very helpful for troubleshooting purposes.

A. Disable the default logging. Open the file $WILDFLY_HOME/standalone/configuration/standalone.xml and find the logging subsystem ("urn:jboss:domain:logging:7.0"). Add these two (2) lines at the beginning of the subsystem configuration:

<add-logging-api-dependencies value="false"/>
<use-deployment-logging-config value="false"/>

B. Configure log4.xml according to your needs