Wiki source code of Jetty Installation
Version 17.1 by Vincent Massol on 2023/12/26
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | There are several ways to run XWiki on Jetty: | ||
| 2 | * Using the [[Demo packaging (a.k.a Standalone packaging)>>Documentation.AdminGuide.Installation.InstallationStandalone.WebHome]] which bundles Jetty and provide an all-in-one zip, ready to use. | ||
| 3 | * Using the official [[Jetty docker image>>https://hub.docker.com/_/jetty]]. | ||
| 4 | * [[Downloading and instaling>>https://www.eclipse.org/jetty/download.html]] Jetty manually on your server. | ||
| 5 | |||
| 6 | If you go with the last 2 options, make sure to: | ||
| 7 | * Pick a [[supported version of Jetty>>dev:Community.SupportStrategy.ServletContainerSupportStrategy.WebHome]]. | ||
| 8 | * Follow the Jetty setup defined in the {{scm path="xwiki-platform-tools/xwiki-platform-tool-jetty/xwiki-platform-tool-jetty-resources/src/main/resources/jetty/modules/xwiki.mod"}}##xwiki.mod##{{/scm}} file used for the demo packaging. Note that the default setup used in the Jetty Docker image should work fine out of the box. | ||
| 9 | * Since XWiki 14, XWiki works OOB on Jetty 10+. If you're deploying on Jetty 9.4.x, you'll need to edit the ##WEB-INF/jetty-web.xml## file since it currently contains a setup valid for Jetty 10+ and it'll fail in Jetty 9.4. You'll need to add the calls to ##prependSystemClass## and ##prependServerClass##. For example (best is to edit your version so that you can get the latest changes in it):((( | ||
| 10 | {{code language="xml"}} | ||
| 11 | <Configure class="org.eclipse.jetty.webapp.WebAppContext"> | ||
| 12 | <!-- In order to avoid getting a "java.lang.IllegalStateException: Form too large" error when editing large page in | ||
| 13 | XWiki we need to tell Jetty to allow for large content since by default it only allows for 20K. We do this by | ||
| 14 | passing the "org.eclipse.jetty.server.Request.maxFormContentSize" attribute. | ||
| 15 | Note 1: Setting this value too high can leave your server vulnerable to denial of service attacks. | ||
| 16 | Note 2: We're setting it here instead of in Jetty's XML configuration files so that the XWiki WAR can be used | ||
| 17 | in any Jetty config and work out of the box. | ||
| 18 | --> | ||
| 19 | <Set name="maxFormContentSize">1000000</Set> | ||
| 20 | <!-- Increasing the maxFormKeys in order to be able to import correctly a full wiki (more than 1000 pages in 11.10). | ||
| 21 | The import should be fixed at a point to allow importing everything without creating a form with a field by page. | ||
| 22 | Once done this configuration can be removed. See https://jira.xwiki.org/browse/XWIKI-11597 for a follow up. --> | ||
| 23 | <Set name="maxFormKeys">2000</Set> | ||
| 24 | |||
| 25 | <!-- Tell jetty that javax.mail should be something that is invisible to the user, but if it's provided inside the | ||
| 26 | webapp use that instead (this is the case for XWiki). This is needed for work around issue | ||
| 27 | https://github.com/appropriate/docker-jetty/issues/108. Note that we don't have this problem in the XWiki | ||
| 28 | Standalone packaging since we create a custom distribution of Jetty and we don't include the Jetty "mail" | ||
| 29 | module. However we have the problem in our functional Docker-based tests where we use the official Jetty | ||
| 30 | image. --> | ||
| 31 | <!-- Note: In Jetty 10+ it's no longer necessary to have this hack. Once all the Jetty version we use are >= 10.0 | ||
| 32 | then we'll be able to remove this file. --> | ||
| 33 | <Call name="getSystemClasspathPattern"> | ||
| 34 | <Call name="add"> | ||
| 35 | <Arg>-javax.mail.</Arg> | ||
| 36 | </Call> | ||
| 37 | </Call> | ||
| 38 | <Call name="getServerClasspathPattern"> | ||
| 39 | <Call name="add"> | ||
| 40 | <Arg>javax.mail.</Arg> | ||
| 41 | </Call> | ||
| 42 | </Call> | ||
| 43 | |||
| 44 | </Configure> | ||
| 45 | {{/code}} | ||
| 46 | ))) | ||
| 47 | * Jetty has introduced a [[URI Compliance configuration>>https://www.eclipse.org/jetty/documentation/jetty-10/operations-guide/index.html#og-module-server-compliance]] (since 10.0.3+) which, for example, forbids having encoded ##%## characters (encoded as ##%25%##) in URL paths. However XWiki uses these and thus you need to tell Jetty to simply follow the URL RFCs without adding these extra checks. This can be done in several ways: | ||
| 48 | ** By editing ##server.ini## and adding the line: {{code language="none"}}jetty.httpConfig.uriCompliance=RFC3986{{/code}} | ||
| 49 | ** If you're using the Jetty Docker image, by passing {{code language="none"}}jetty.httpConfig.uriCompliance=RFC3986{{/code}} on the ##docker run## command line: {{code language="none"}}docker run ... jetty jetty.httpConfig.uriCompliance=RFC3986{{/code}}. | ||
| 50 | |||
| 51 | = Docker = | ||
| 52 | |||
| 53 | * Extract the [[XWiki WAR>>xwiki:Main.Download]] into a directory named ##xwiki##. Let's call this directory ##[XWIKI_HOME]##. | ||
| 54 | * Setup a permanent directory on your local machine and let's call it ##[XWIKI_PERMDIR]## | ||
| 55 | * Run the Jetty Docker image, for example: {{code language="none"}}docker run -v [XWIKI_HOME]:/var/lib/jetty/webapps/xwiki -v [XWIKI_PERMDIR]:/var/lib/jetty/xwiki-data -p 8080:8080 jetty:9-jre11 -Dxwiki.data.dir=/var/lib/jetty/xwiki-data{{/code}} | ||
| 56 | ** Note that you won't need the ##-Dxwiki.data.dir=/var/lib/jetty/xwiki-data## part if you have edited ##[XWIKI_HOME]/WEB-INF/xwiki.propeties## and set the ##environment.permanentDirectory## to point to ##/var/lib/jetty/xwiki-data##. The system property just overrides whatever is defined in ##environment.permanentDirectory##. | ||
| 57 | ** Also note that you'll need a database set up too. If you want to quickly test it, you can simply copy the the HSQLDB JAR into ##WEB-INF/lib##. | ||
| 58 | |||
| 59 | = Manual = | ||
| 60 | |||
| 61 | * Download and install [[Jetty>>https://www.eclipse.org/jetty/download.html]]. It's usually as simple as unzipping it in a directory. Let's call this directory ##[JETTY_HOME]##. | ||
| 62 | * Extract the [[XWiki WAR>>xwiki:Main.Download]] into a directory named ##xwiki## in ##[JETTY_HOME]/webapps/##. | ||
| 63 | * Open ##[JETTY_HOME]/webapps/xwiki/WEB-INF/xwiki.properties## files and [[configure a permanent directory>>Documentation.AdminGuide.Configuration||anchor="HConfiguringDirectories"]] | ||
| 64 | * (Optional) If you want to modify the port on which Jetty will run, edit ##[JETTY_HOME]/start.ini##. Search for ##8080##, replace it with the port value you wish to use and uncomment the corresponding property {{code language="none"}}jetty.http.port{{/code}}. | ||
| 65 | |||
| 66 | = Troubleshooting = | ||
| 67 | |||
| 68 | == Unable to parse form content == | ||
| 69 | |||
| 70 | In some cases you could obtain one of the following error messages: ##Unable to parse form content##. | ||
| 71 | |||
| 72 | More specifically: ##org.eclipse.jetty.http.BadMessageException: 400: Unable to parse form content##. | ||
| 73 | |||
| 74 | This can be related to a form containing too many parameters. In order to fix this issue, you can modify your ##jetty.xml## file as explained in [[Configuring form limits for the server>>https://www.eclipse.org/jetty/documentation/9.4.x/configuring-form-size.html#_configuring_form_limits_for_the_server]]. |
