Wiki source code of JBoss/WildFly Installation
Last modified by Thomas Mortagne on 2025/02/19
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
17.1 | 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} |
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
 |
1.5 | 4 | |
| |
31.1 | 5 | = WildFly 27+ = |
| 6 | |||
 |
32.1 | 7 | XWiki before 17.0.0 doesn't work with WildFly 27+ since it only works in a Jakarta EE 8 (##javax.servlet##) environment. |
| |
31.1 | 8 | |
| 9 | = WildFly 26.x = | ||
| 10 | |||
| 11 | The instructions are the same as for Wildly 17.x below. | ||
| 12 | |||
| |
27.2 | 13 | = WildFly 17.x = |
| 14 | |||
| 15 | The instructions are the same as for Wildly 14.x below. | ||
| 16 | |||
| |
27.1 | 17 | = WildFly 14.x = |
| 18 | |||
| 19 | The instructions are the same as for Wildly 10.x below. | ||
| 20 | |||
| |
22.3 | 21 | = WildFly 10.x = |
| 22 | |||
| 23 | The instructions are the same as for JBoss AS 7.x below. | ||
| 24 | |||
| |
23.1 | 25 | Some documentation that can be useful: |
| |
26.1 | 26 | |
| |
23.1 | 27 | * [[how WildFly 10.x Classloader works>>https://docs.jboss.org/author/display/WFLY10/Class+Loading+in+WildFly]] |
| 28 | |||
| |
24.1 | 29 | == Troubleshooting == |
| 30 | |||
| 31 | === Weld Deployment Error === | ||
| 32 | |||
| |
27.2 | 33 | 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. |
| |
24.1 | 34 | |
| |
27.2 | 35 | Note that we [[fixed this>>https://jira.xwiki.org/browse/XWIKI-13678]] 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>>https://jira.xwiki.org/browse/XWIKI-15566]] in XWiki 10.8RC1+. In the end, it was found that [[this file was needed after all>>https://jira.xwiki.org/browse/XWIKI-16577]] and put back in XWiki 10.11.9/11.3.2/11.6RC1+... |
| |
27.1 | 36 | |
| |
27.2 | 37 | 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: |
| 38 | |||
| |
27.1 | 39 | {{code language="xml"}} |
| 40 | <?xml version="1.0" encoding="UTF-8"?> | ||
| 41 | |||
| 42 | <!-- | ||
| 43 | * | ||
| 44 | * See the NOTICE file distributed with this work for additional | ||
| 45 | * information regarding copyright ownership. | ||
| 46 | * | ||
| 47 | * This is free software; you can redistribute it and/or modify it | ||
| 48 | * under the terms of the GNU Lesser General Public License as | ||
| 49 | * published by the Free Software Foundation; either version 2.1 of | ||
| 50 | * the License, or (at your option) any later version. | ||
| 51 | * | ||
| 52 | * This software is distributed in the hope that it will be useful, | ||
| 53 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 54 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
| 55 | * Lesser General Public License for more details. | ||
| 56 | * | ||
| 57 | * You should have received a copy of the GNU Lesser General Public | ||
| 58 | * License along with this software; if not, write to the Free | ||
| 59 | * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA | ||
| 60 | * 02110-1301 USA, or see the FSF site: http://www.fsf.org. | ||
| 61 | * | ||
| 62 | --> | ||
| 63 | |||
| 64 | <!-- Required to tell WildFly to not do CDI bean parsing and try to do implicit deployment of them since XWiki doesn't | ||
| 65 | use CDI --> | ||
| 66 | <jboss xmlns="urn:jboss:1.0"> | ||
| 67 | <weld xmlns="urn:jboss:weld:1.0" require-bean-descriptor="true"/> | ||
| 68 | </jboss> | ||
| 69 | {{/code}} | ||
| 70 | |||
| |
17.1 | 71 | = JBoss AS 7.x = |
| 72 | |||
 |
20.2 | 73 | * Download and install the [[JBoss Application Server>>http://www.jboss.org/jbossas/]] |
| |
22.1 | 74 | * Deploy the XWiki WAR either by using the JBoss AS Admin (recommended) or by deploying on the filesystem. Read the [[JBoss AS documentation>>https://docs.jboss.org/author/display/AS71/Documentation]] to learn how to do this. |
| |
18.1 | 75 | * If you have class loader issues read [[how JBoss AS7 Classloader works>>https://docs.jboss.org/author/display/AS71/Developer+Guide#DeveloperGuide-ClassloadinginJBossAS7]] |
| |
17.1 | 76 | |
| |
22.1 | 77 | == Example using Standalone Deployment == |
| 78 | |||
| |
32.1 | 79 | Let's assume that ##$AS## points to the root of the WildFly distribution. |
| |
22.1 | 80 | |
| |
32.1 | 81 | * Copy the xwiki expanded WAR directory in ##$AS/standalone/deployments/xwiki.war## |
| 82 | * Do a ##touch $AS/standalone/deployments/xwiki.war.dodeploy## | ||
| 83 | * Start WildFly standalone: run ##./standalone.sh## from ##$AS/bin/## | ||
| |
30.2 | 84 | |
| |
19.1 | 85 | == Troubleshooting == |
| 86 | |||
| 87 | === "More than the maximum number of request parameters" error === | ||
| 88 | |||
| 89 | If you get the following error in the logs when trying to import a large XAR: | ||
| 90 | |||
| 91 | {{code}} | ||
| 92 | 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. | ||
| 93 | {{/code}} | ||
| 94 | |||
| |
20.2 | 95 | You'll need to [[configure Tomcat in JBoss to support more than 512 form fields>>https://community.jboss.org/thread/177942]]. |
| |
19.1 | 96 | |
| |
17.1 | 97 | = JBoss AS 4.0.x = |
| 98 | |||
| |
20.2 | 99 | * 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## |
| 100 | * (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 | ||
| 101 | * 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 | ||
| |
16.1 | 102 | * Edit ##$JBOSS_HOME/server/<mode>/deploy/jbossweb-tomcat55.sar/server.xml## to set UTF-8 encoding:((( |
| 103 | {{code}} | ||
| 104 | <Connector port="8080" ... URIEncoding="UTF-8"/> | ||
| 105 | <Connector port="8009" ... URIEncoding="UTF-8"/> | ||
| 106 | {{/code}} | ||
| 107 | ))) | ||
| |
5.1 | 108 | |
| |
17.1 | 109 | == Classloading Isolation == |
| |
14.1 | 110 | |
| |
15.1 | 111 | 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. |
| |
14.1 | 112 | |
| |
20.2 | 113 | To solve this please read up on [[JBoss ClassLoading Configuration>>https://community.jboss.org/wiki/ClassLoadingConfiguration]] in order to configure JBoss not to use the unified class loader (set ##UseJBossWebLoader## to ##false## in ##META-INF/jboss-service.xml##). |
| |
15.1 | 114 | |
| 115 | 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. | ||
| 116 | |||
| |
17.1 | 117 | == Log4j Error == |
| |
5.1 | 118 | |
 |
20.3 | 119 | {{warning}} |
| 120 | It was reported that with XWiki 1.6 and JBoss 4.0.4, using these settings would generate an error with hibernate. Everything seems to work fine without these settings including classloading of log4j. | ||
| 121 | {{/warning}} | ||
| |
5.1 | 122 | |
| |
32.1 | 123 | * ((( |
| 124 | Edit ##$JBOSS_HOME/server/<server configuration>/jbossweb-tomcat55.sar/META-INF/jboss-service.xml## file and replace: | ||
| 125 | |||
| 126 | ((( | ||
| |
7.1 | 127 | {{code}} |
| |
4.1 | 128 | <attribute name="Java2ClassLoadingCompliance">false</attribute> |
| 129 | <attribute name="UseJBossWebLoader">false</attribute> | ||
| |
7.1 | 130 | {{/code}} |
| |
32.1 | 131 | )))with: |
| 132 | |||
| 133 | ((( | ||
| |
7.1 | 134 | {{code}} |
| |
4.1 | 135 | <attribute name="Java2ClassLoadingCompliance">true</attribute> |
| 136 | <attribute name="UseJBossWebLoader">true</attribute> | ||
| |
7.1 | 137 | {{/code}} |
| |
26.1 | 138 | )))This is to avoid class loading issues for the Log4J library. |
| |
32.1 | 139 | ))) |
| |
1.6 | 140 | |
| |
28.1 | 141 | = Using a WildFly/JBoss DataSource = |
| |
1.26 | 142 | |
| |
28.1 | 143 | == Tutorial for JBoss AS 7.1+ == |
| |
20.3 | 144 | |
| |
28.1 | 145 | * Create a JBoss Module for your database driver. |
| 146 | ** **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:((( | ||
| |
32.1 | 147 | {{code language="xml"}} |
| |
20.1 | 148 | <?xml version="1.0" encoding="UTF-8"?> |
| 149 | <module xmlns="urn:jboss:module:1.0" name="org.hsqldb"> | ||
| 150 | <resources> | ||
| 151 | <resource-root path="hsqldb-2.2.9.jar"/> | ||
| 152 | </resources> | ||
| 153 | <dependencies> | ||
| 154 | <module name="javax.api"/> | ||
| 155 | </dependencies> | ||
| 156 | </module> | ||
| 157 | {{/code}} | ||
| 158 | ))) | ||
| |
28.1 | 159 | ** **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:((( |
| |
32.1 | 160 | {{code language="xml"}} |
| |
28.1 | 161 | <?xml version="1.0" encoding="UTF-8"?> |
| 162 | |||
| 163 | <module xmlns="urn:jboss:module:1.1" name="com.mysql"> | ||
| 164 | <resources> | ||
| 165 | <resource-root path="mysql-connector-java-5.1.48.jar"/> | ||
| 166 | </resources> | ||
| 167 | <dependencies> | ||
| 168 | <module name="javax.api"/> | ||
| 169 | <module name="javax.transaction.api"/> | ||
| 170 | <module name="javax.servlet.api" optional="true"/> | ||
| 171 | </dependencies> | ||
| 172 | </module> | ||
| 173 | {{/code}} | ||
| 174 | ))) | ||
| 175 | * Edit the ##[ASROOT]/standalone/configuration/standalone.xml## file to add a new ##<datasource>## and a new ##<driver>## sections (adjust the properties as needed): | ||
| 176 | ** **MySQL**. Example:((( | ||
| |
32.1 | 177 | {{code language="xml"}} |
| |
28.1 | 178 | <datasources> |
| 179 | <datasource jta="true" jndi-name="java:jboss/datasources/XWikiDS" pool-name="XWikiDS" enabled="true" use-java-context="true" use-ccm="true"> | ||
| 180 | <connection-url>jdbc:mysql://localhost:3306/xwiki?useSSL=false</connection-url> | ||
| 181 | <driver>mysql</driver> | ||
| 182 | <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation> | ||
| 183 | <pool> | ||
| 184 | <min-pool-size>10</min-pool-size> | ||
| 185 | <max-pool-size>100</max-pool-size> | ||
| 186 | <prefill>true</prefill> | ||
| 187 | </pool> | ||
| 188 | <security> | ||
| 189 | <user-name>xwiki</user-name> | ||
| 190 | <password>xwiki</password> | ||
| 191 | </security> | ||
| 192 | <statement> | ||
| 193 | <prepared-statement-cache-size>32</prepared-statement-cache-size> | ||
| 194 | <share-prepared-statements>true</share-prepared-statements> | ||
| 195 | </statement> | ||
| 196 | </datasource> | ||
| 197 | ... | ||
| 198 | <drivers> | ||
| 199 | <driver name="mysql" module="com.mysql"> | ||
| 200 | <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class> | ||
| 201 | </driver> | ||
| 202 | ... | ||
| 203 | {{/code}} | ||
| 204 | ))) | ||
| 205 | ** 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:((( | ||
| |
20.1 | 206 | {{code}} |
| 207 | <?xml version="1.0" encoding="UTF-8"?> | ||
| 208 | <datasources xmlns="http://www.jboss.org/ironjacamar/schema"> | ||
| 209 | <datasource jndi-name="java:jboss/datasources/XWikiDS" pool-name="XWikiDS" enabled="true" use-java-context="true"> | ||
| 210 | <connection-url>jdbc:hsqldb:file:[path to your hsqldb db file, e.g. /tmp/xwiki-data/database/xwiki_db];shutdown=true</connection-url> | ||
| 211 | <driver>hsqldb</driver> | ||
| 212 | <security> | ||
| 213 | <user-name>sa</user-name> | ||
| 214 | <password></password> | ||
| 215 | </security> | ||
| 216 | </datasource> | ||
| 217 | </datasources> | ||
| 218 | {{/code}} | ||
| |
28.1 | 219 | |
| 220 | 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. | ||
| |
20.1 | 221 | ))) |
| |
28.1 | 222 | * Modify XWiki's ##WEB-INF/hibernate.cfg.xml## file to tell Hibernate to use the defined DataSource rather than a direct JDBC connection:((( |
| 223 | {{code}} | ||
| |
29.1 | 224 | <!-- 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) --> |
| |
28.1 | 225 | <!--property name="hibernate.connection.provider_class">com.xpn.xwiki.store.DBCPConnectionProvider</property--> |
| 226 | ... | ||
| 227 | <!-- Tells Hibernate to use the defined data source --> | ||
| 228 | <property name="connection.datasource">java:jboss/datasources/XWikiDS</property> | ||
| 229 | |||
| 230 | <!-- The following can be commented out since these are not needed as they are defined in the Data source definition --> | ||
| 231 | <!-- | ||
| 232 | <property name="hibernate.connection.url">jdbc:hsqldb:file:${environment.permanentDirectory}/database/xwiki_db;shutdown=true</property> | ||
| 233 | <property name="hibernate.connection.username">sa</property> | ||
| 234 | <property name="hibernate.connection.password"></property> | ||
| 235 | <property name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</property> | ||
| 236 | --> | ||
| 237 | ... | ||
| 238 | {{/code}} | ||
| 239 | ))) | ||
| |
20.1 | 240 | |
| |
28.1 | 241 | == Tutorial for older versions == |
| |
20.1 | 242 | |
| |
20.2 | 243 | * Uncomment the ##resource-ref## section in XWiki's ##web.xml## file. You should have:((( |
| |
20.1 | 244 | {{code}} |
| 245 | <resource-ref> | ||
| 246 | <description>DB Connection</description> | ||
| 247 | <res-ref-name>jdbc/XWikiDS</res-ref-name> | ||
| 248 | <res-type>javax.sql.DataSource</res-type> | ||
| 249 | <res-auth>Container</res-auth> | ||
| 250 | </resource-ref> | ||
| 251 | {{/code}} | ||
| 252 | ))) | ||
| 253 | * Create the following ##jboss-web.xml## file in the deployed XWiki's ##WEB-INF/## directory:((( | ||
| 254 | {{code}} | ||
| 255 | <?xml version="1.0" encoding="ISO-8859-1"?> | ||
| 256 | <!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 2.3V2//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_3_2.dtd"> | ||
| 257 | <jboss-web> | ||
| 258 | <resource-ref> | ||
| 259 | <res-ref-name>jdbc/XWikiDS</res-ref-name> | ||
| 260 | <jndi-name>java:jboss/datasources/XWikiDS</jndi-name> | ||
| 261 | </resource-ref> | ||
| 262 | </jboss-web> | ||
| 263 | {{/code}} | ||
| 264 | ))) | ||
| 265 | * Modify XWiki's ##WEB-INF/hibernate.cfg.xml## file to tell Hibernate to use the defined DataSource rather than a direct JDBC connection:((( | ||
| 266 | {{code}} | ||
| |
28.1 | 267 | <!-- This needs to be commented out since we're not going to use XWiki's Data Source --> |
| 268 | <!--property name="hibernate.connection.provider_class">com.xpn.xwiki.store.DBCPConnectionProvider</property--> | ||
| |
20.1 | 269 | ... |
| |
28.1 | 270 | <!-- Tells Hibernate to use the defined data source --> |
| |
20.1 | 271 | <property name="connection.datasource">java:jboss/datasources/XWikiDS</property> |
| |
28.1 | 272 | |
| 273 | <!-- The following can be commented out since these are not needed as they are defined in the Data source definition --> | ||
| 274 | <!-- | ||
| 275 | <property name="hibernate.connection.url">jdbc:hsqldb:file:${environment.permanentDirectory}/database/xwiki_db;shutdown=true</property> | ||
| 276 | <property name="hibernate.connection.username">sa</property> | ||
| 277 | <property name="hibernate.connection.password"></property> | ||
| 278 | <property name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</property> | ||
| 279 | --> | ||
| |
20.1 | 280 | ... |
| 281 | {{/code}} | ||
| 282 | ))) | ||
| 283 | |||
| |
18.1 | 284 | = Issues related to JBoss = |
| 285 | |||
| |
25.1 | 286 | {{jira URL="https://jira.xwiki.org" source="jql"}} |
| |
18.1 | 287 | labels = jboss |
| 288 | {{/jira}} |
