Published
Wiki source code of Correct the Installation Troubleshooting tree
Last modified by Eleni Cojocariu on 2026/08/19 15:42
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | Review of the [[Installation Troubleshooting>>doc:documentation.xs.admin.installation.troubleshooting.WebHome]] topic and its children against the [[Documentation Guide>>dev:Community.DocGuide.WebHome]], checking the pages against the platform sources and against the legacy page they came from (##Documentation.AdminGuide.Installation## at version 157.1, the last revision before the migration). | ||
| 2 | |||
| 3 | Three of the findings make a reader worse off than the error they arrived with. | ||
| 4 | |||
| 5 | == Wrong solutions == | ||
| 6 | |||
| 7 | * **Multiple Instances of XWiki in the Same Container** told the reader to add {{code language="none"}}<jmx duplicate-domains="true"/>{{/code}} to the Infinispan configuration. That attribute was removed in Infinispan 10: the shipped ##WEB-INF/cache/infinispan/config.xml## declares {{code language="none"}}urn:infinispan:config:15.2{{/code}} in 17.10.4 and in 18.7 alike, and the 15.2 schema's ##jmx## element accepts only ##domain##, ##enabled## and ##mbean-server-lookup##. An unknown attribute in a schema-validated configuration stops the cache container from starting. The file also already contains a ##jmx## element, so "add the element" was wrong in shape too. The Solution now edits its ##domain## attribute, which is what makes the domains unique. | ||
| 8 | * **SSL Certificate Error** blamed "versions of Java 8 older than update 101" and prescribed upgrading Java 8 to update 101. Java 8 has not been supported since XWiki 14.0, and XWiki 18 requires Java 21 or 25; the pasted stack trace was from 2017 and framed on ##sun.security.ssl.Alerts##, removed in JDK 11. The page now explains the truststore, names the two situations that actually produce a PKIX failure (a TLS-inspecting proxy, a self-signed internal certificate) and solves it with ##keytool##. | ||
| 9 | * **"File Path too Long" on Windows when Unzipping** named the registry value ##EnableLongPaths##. The value Windows reads is ##LongPathsEnabled##, so the documented fix did nothing. Its MSDN link also 301s to a page where the {{code language="none"}}#maxpath{{/code}} anchor no longer exists, and now points at the current Microsoft page. | ||
| 10 | |||
| 11 | == The legacy page dead-ended readers == | ||
| 12 | |||
| 13 | ##Documentation.AdminGuide.Installation## still contained {{code language="none"}}See [[]].{{/code}} under both "Getting an error about SSL certificate" and ""File path too long" on Windows when unzipping", rendering as {{code language="none"}}See Installation.{{/code}} with {{code language="none"}}href="#"{{/code}}. Both now point at the new pages. Its "Unsupported major.minor version 51.0" section still described Java 6 and 7 and had the offline-installation link stranded underneath it; the section is repointed at [[XWiki Startup Failure after a Required Java Upgrade>>doc:documentation.xs.admin.upgrade.troubleshooting.xwiki-startup-failure-java-upgrade.WebHome]], which documents that symptom on a supported version, and the offline link gets its own heading back. | ||
| 14 | |||
| 15 | == The proxy pages == | ||
| 16 | |||
| 17 | **XWiki behind a Proxy Server** carried two full configuration procedures inside its Solution section, nested in bullets, plus a "Tomcat 8+" that no supported XWiki runs on (a Servlet 5.0 container is required, and the distribution builds packages for Tomcat 10 and 11 only) and a Windows example that had lost the ##https## proxy properties the Linux one had. Those steps are now a How-to of their own, [[Configure XWiki to Use a Proxy Server>>doc:documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.configure-proxy.WebHome]], leaving the Explanation with the symptom, the cause and the route to the fix. The Java **6** networking-and-proxies link and the "alteratives" typo are gone. | ||
| 18 | |||
| 19 | **Debug Proxy Configuration** ended on "Save the Page and notice the information on the Page", with no result step, no screenshot, and it had dropped the legacy page's one piece of guidance about *what* to look at. Its connectivity test also called ##httpbin.org##, which was returning 503 and 504 while this was reviewed. It now verifies the thing the reader actually cares about, an extension search, in four steps with three screenshots captured on a local 18.4.3 instance. The legacy Groovy dump is kept as a FAQ entry, since reading the values from inside XWiki is still the only way to see what the runtime resolved rather than what the startup script passed; the entry says it takes programming rights, which a wiki administrator does not hold by default on a stock instance. | ||
| 20 | |||
| 21 | Its page name was ##debug##, which says nothing from a search result. It was **renamed** to ##debug-configuration## before this Change Request, with "Update links" and an automatic redirect: that repointed its two backlinks, including the FAQ xobject of the proxy page. | ||
| 22 | |||
| 23 | == Smaller corrections == | ||
| 24 | |||
| 25 | * The hub was titled "Installation Troubleshootings"; every sibling hub uses "… Troubleshooting". | ||
| 26 | * The hub's fourth bullet rendered a stray {{code language="none"}}>>{{/code}} inside the link label, from a {{code language="none"}}~>~>{{/code}} in the source. | ||
| 27 | * The hub routed only to its own four children. Its Related field now reaches the other installation-time troubleshooting hubs: Tomcat, Docker, Jetty form content, and Upgrade. | ||
| 28 | * The hub had lost the legacy qualifier that the Admin Tools application checks a **Tomcat and MySQL** installation. | ||
| 29 | * Each leaf's Related field listed all three siblings, which the parent's automatic More table already does. They now hold the pages that are genuinely related: Tomcat Troubleshooting from the Infinispan page, the proxy page from the SSL page, the standalone distribution from the unzipping page. | ||
| 30 | * {{code language="none"}}<jmx …/>{{/code}} and {{code language="none"}}<cache-container>{{/code}} were written as bare prose and rendered as plain text; they are in code macros now. | ||
| 31 | * The title "XWiki behind a Proxy Server" is now "XWiki Behind a Proxy Server", as on "Configure XWiki in Docker Behind a Reverse Proxy". | ||
| 32 | |||
| 33 | == One deliberate deviation == | ||
| 34 | |||
| 35 | **Configure XWiki to Use a Proxy Server** has no screenshot, including on its result step. Every one of its steps edits a startup script or reads a process command line, so there is no interface to capture; the result step shows the produced output instead, the way a Developer page does. Happy to add something if a reviewer would rather see it. | ||
| 36 | |||
| 37 | Two titles were left alone on purpose: the quoted error text in ""File Path too Long" on Windows **when** Unzipping" is kept verbatim, and five pages of the Exports tree link to it with that wording. |
