WildFly 27+

The instructions are mostly the same as for Wildly 24 below but:

• The package to download is "WildFly Distribution".
• Jakarta EE 8 (and so XWiki < 17) is not supported anymore.

WildFly 24+

• Download and install the Jakarta EE Full & Web Distribution (EE 8 for XWiki < 17, EE 9+ for XWiki > 17).
• Unzip the XWiki WAS in <wildfly>/standalone/deployments/xwiki.war.
• Create a <wildfly>/standalone/deployments/xwiki.war.dodeploy file.
• Start WildFly standalone: run <wildfly>/bin/standalone.sh (or standalone.bat on Windows)

You can customize various properties (for example, Java parameters like the memory and --add-opens) in <wildfly>/bin/standalone.conf.

See https://docs.wildfly.org/ for more details.

Troubleshooting

"More than the maximum number of request parameters" error

If you get the following error in the logs when trying to import a large XAR:

Servlet.service() for servlet action threw exception: java.lang.IllegalStateException: More than the maximum number of request parameters (GET plus POST) for a single request ([512]) were detected. Any parameters beyond this limit have been ignored. To change this limit, set the maxParameterCount attribute on the Connector.

You'll need to configure Tomcat in JBoss to support more than 512 form fields.

Classloading Isolation

The default JBoss behavior is that classes inside of the WEB-INF/classes and WEB-INF/lib directories of the WAR file are incorporated into the default shared class loader repository. This allows classes and resources to be shared between web applications. However this means that JARs provided by XWiki in WEB-INF/lib will get mixed with JARs provided by JBoss and if both application provide the same JAR but in a different version, class incompatibilities will occur. 

To solve this please read up on JBoss ClassLoading Configuration in order to configure JBoss not to use the unified class loader (set UseJBossWebLoader to false in META-INF/jboss-service.xml).

Alternatively you may try to remove the clashing JARs from XWiki's WEB-INF/lib hoping that the version provided by JBoss is compatible with XWiki's needs.

Using a WildFly/JBoss DataSource

Tutorial for JBoss AS 7.1+

• Create a JBoss Module for your database driver.
  • HSQLDB: create the directory [ROOT]/modules/org/hsqldb/main and put the HSQLDB Driver JAR (e.g. hsqldb-2.2.9.jar) in it and also create a module.xml in it and write the following code inside:

    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="org.hsqldb">
      <resources>
        <resource-root path="hsqldb-2.2.9.jar"/>
      </resources>
      <dependencies>
        <module name="javax.api"/>
      </dependencies>
    </module>

  • MySQL: create the directory [ROOT]/modules/com/mysql/main and put the MySQL Driver JAR (e.g. mysql-connector-java-5.1.48.jar) in it and also create a module.xml in it and write the following code inside:

    <?xml version="1.0" encoding="UTF-8"?>
    
    <module xmlns="urn:jboss:module:1.1" name="com.mysql">
      <resources>
        <resource-root path="mysql-connector-java-5.1.48.jar"/>
      </resources>
      <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
        <module name="javax.servlet.api" optional="true"/>
      </dependencies>
    </module>

• Edit the [ASROOT]/standalone/configuration/standalone.xml file to add a new <datasource> and a new <driver> sections (adjust the properties as needed):
  • MySQL. Example:

    <datasources>
      <datasource jta="true" jndi-name="java:jboss/datasources/XWikiDS" pool-name="XWikiDS" enabled="true" use-java-context="true" use-ccm="true">
        <connection-url>jdbc:mysql://localhost:3306/xwiki?useSSL=false</connection-url>
        <driver>mysql</driver>
        <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
        <pool>
          <min-pool-size>10</min-pool-size>
          <max-pool-size>100</max-pool-size>
          <prefill>true</prefill>
        </pool>
        <security>
          <user-name>xwiki</user-name>
          <password>xwiki</password>
        </security>
        <statement>
          <prepared-statement-cache-size>32</prepared-statement-cache-size>
          <share-prepared-statements>true</share-prepared-statements>
        </statement>
      </datasource>
    ...
    <drivers>
      <driver name="mysql" module="com.mysql">
        <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
      </driver>
    ...

  • Note that it's also possible to create a data source file named -ds.xml (e.g. hsqldb-ds.xml) in [ASROOT]/standalone/deployments/ (you can also put it in your WEB-INF/ dir). Example of content for HSQLDB:

    <?xml version="1.0" encoding="UTF-8"?>
    <datasources xmlns="http://www.jboss.org/ironjacamar/schema">
      <datasource jndi-name="java:jboss/datasources/XWikiDS" pool-name="XWikiDS" enabled="true" use-java-context="true">
        <connection-url>jdbc:hsqldb:file:[path to your hsqldb db file, e.g. /tmp/xwiki-data/database/xwiki_db];shutdown=true</connection-url>
        <driver>hsqldb</driver>
        <security>
          <user-name>sa</user-name>
          <password></password>
        </security>
      </datasource>
    </datasources>

    However it's not recommended because the deployment datasource feature should only be used in development environments, as the deployable datasources are considered as unmanaged datasource. Those are not recommended for production environments, because those can not be managed by the JBoss Management console or the management utilities like jboss-cli.sh. Hence such datasource cannot be managed like the managed dataSources which are configured inside the domain.xml or standalone*.xml files.

• Modify XWiki's WEB-INF/hibernate.cfg.xml file to tell Hibernate to use the defined DataSource rather than a direct JDBC connection:

  <!-- This needs to be commented out since we're not going to use the DBCP connection pool (we're going to use the Data Source connection pool) -->
  <!--property name="hibernate.connection.provider_class">com.xpn.xwiki.store.DBCPConnectionProvider</property-->
  ...
  <!-- Tells Hibernate to use the defined data source -->
  <property name="connection.datasource">java:jboss/datasources/XWikiDS</property>
    
  <!-- The following can be commented out since these are not needed as they are defined in the Data source definition -->
  <!--
    <property name="hibernate.connection.url">jdbc:hsqldb:file:${environment.permanentDirectory}/database/xwiki_db;shutdown=true</property>
    <property name="hibernate.connection.username">sa</property>
    <property name="hibernate.connection.password"></property>
    <property name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</property>
  -->
  ...

Issues related to JBoss/WildFly