WildFly 17.x

The instructions are the same as for Wildly 14.x below.

WildFly 14.x

The instructions are the same as for Wildly 10.x below.

WildFly 10.x

The instructions are the same as for JBoss AS 7.x below.

Some documentation that can be useful:

• how WildFly 10.x Classloader works

Troubleshooting

Weld Deployment Error

WildFly does automatic implicit CDI deployment when it finds some CDI beans in JARs. We need to prevent this since XWiki doesn't use CDI and there can be some third-party deps we use that have some CDI annotations.

Note that we fixed this by providing a META-INF/jboss-all.xml file telling WildFly to not do CDI bean scanning in XWiki 8.3M2+. However we found a problem with it and removed it in XWiki 10.8RC1+. In the end, it was found that this file was needed after all and put back in XWiki 10.11.9/11.3.2/11.6RC1+...

If you're using a version of XWiki that doesn't provide this jboss-all.xml then create one in the META-INF directory inside the XWiki WAR, with the following content:

JBoss AS 7.x

• Download and install the JBoss Application Server
• Deploy the XWiki WAR either by using the JBoss AS Admin (recommended) or by deploying on the filesystem. Read the JBoss AS documentation to learn how to do this.
• If you have class loader issues read how JBoss AS7 Classloader works

Example using Standalone Deployment

• Copy the xwiki expanded WAR directory in JBOSSHOME/standalone/deployments/xwiki.war
• Do a touch JBOSSHOME/standalone/deployments/xwiki.war.dodeploy
• Start JBoss standalone: run ./standalone.sh from JBOSSHOME/bin/

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:

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

JBoss AS 4.0.x

• Download and install the "JBoss Application Server". It's usually as simple as unzipping it in a directory. Let's call this directory $JBOSS_HOME
• (optional) By default JBoss runs on port 8080. If you want to modify the port on which JBoss is running, edit $JBOSS_HOME/server/<mode>/deploy/jbossweb-tomcat55.sar/server.xml. Search for 8080 and replace it with the port value you wish to use. Similarly change the port in $JBOSS_HOME/server/<mode>/deploy/http-invoker.sar/META-INF/jboss-service.xml to the value you like
• Copy and expand the XWiki WAR into a directory named xwiki.war/ (note that unlike most servlet containers JBoss wants the directory name to end with .war) in $JBOSS_HOME/server/<server configuration>/deploy where server configuration is the JBoss configuration you're using
• Edit $JBOSS_HOME/server/<mode>/deploy/jbossweb-tomcat55.sar/server.xml to set UTF-8 encoding:
  <Connector port="8080" ... URIEncoding="UTF-8"/>
  <Connector port="8009" ... URIEncoding="UTF-8"/>

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.

Log4j Error

• Edit $JBOSS_HOME/server/<server configuration>/jbossweb-tomcat55.sar/META-INF/jboss-service.xml file and replace:
  <attribute name="Java2ClassLoadingCompliance">false</attribute>
  <attribute name="UseJBossWebLoader">false</attribute>
  with:
  <attribute name="Java2ClassLoadingCompliance">true</attribute>
  <attribute name="UseJBossWebLoader">true</attribute>
  This is to avoid class loading issues for the Log4J library.

Using a JBoss DataSource

JBoss links about this topic:

• JBoss AS 7.1 Datasource Configuration
• DataSource configuration in AS 7
• JBoss AS 7.1.0.Final "Thunder" released - Java EE 6 Full Profile certified!
• How do I migrate my application from AS5 or AS6 to AS7
• Excited about JBoss AS 7.1 Part I: Deployable Datasources

Tutorial for JBoss AS 7.1

• Create a JBoss Module for your database driver. For example for HSQLDB, create the directory [ASROOT]/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>
• Create a data source file named -ds.xml (e.g. hsqldb-ds.xml). If you're using a standalone deployment, put it in [ASROOT]/standalone/deployments/ (you can also put it in your WEB-INF/ dir). Example of content:
  <?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>

Old Tutorial

• Uncomment the resource-ref section in XWiki's web.xml file. You should have:
  <resource-ref>
   <description>DB Connection</description>
   <res-ref-name>jdbc/XWikiDS</res-ref-name>
   <res-type>javax.sql.DataSource</res-type>
   <res-auth>Container</res-auth>
  </resource-ref>
• Create the following jboss-web.xml file in the deployed XWiki's WEB-INF/ directory:
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <!DOCTYPE jboss-web PUBLIC  "-//JBoss//DTD Web Application 2.3V2//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_3_2.dtd">
  <jboss-web>
   <resource-ref>
         <res-ref-name>jdbc/XWikiDS</res-ref-name>
         <jndi-name>java:jboss/datasources/XWikiDS</jndi-name>
    </resource-ref>
  </jboss-web>
• Modify XWiki's WEB-INF/hibernate.cfg.xml file to tell Hibernate to use the defined DataSource rather than a direct JDBC connection:
  ...
  <property name="connection.datasource">java:jboss/datasources/XWikiDS</property>
  ...

Issues related to JBoss