Wiki source code of Installation

Last modified by Thomas Mortagne on 2023/12/19

Hide last authors
Jean-Vincent Drean 48.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Ludovic Dubost 28.1 4
Vincent Massol 138.3 5 XWiki is a Java-based wiki and runs on a Servlet Container such as Tomcat, Jetty, JBoss, WebLogic, WebSphere, etc. It also uses a relational database to store its content. It can run on almost any database (MySQL, PostgreSQL, etc) but XWiki and the database need to be setup correctly.
Raffaello Pelagalli 13.1 6
Ecaterina Moraru (Valica) 107.4 7 If you're upgrading an existing XWiki install check the [[Upgrade instructions page>>Documentation.AdminGuide.Upgrade]].
Vincent Massol 31.5 8
Vincent Massol 126.1 9 Pick one of the [[installation methods>>#HInstallationMethods]] to begin installing XWiki.
Vincent Massol 31.5 10
Ecaterina Moraru (Valica) 107.4 11 Once you've finished the installation check the other topics in the [[Admin Guide>>Documentation.AdminGuide.WebHome]] for configuring and [[securing>>Documentation.AdminGuide.Security]] your wiki.
Vincent Massol 31.5 12
Vincent Massol 94.1 13 {{id name="Prerequisites"/}}
Thomas Mortagne 98.1 14
Vincent Massol 94.1 15 = Hardware and Software requirements =
Vincent Massol 75.2 16
Vincent Massol 147.1 17 * A [[supported Java version>>dev:Community.SupportStrategy.JavaSupportStrategy.WebHome]]. Note that a JRE is enough and you don't need a JDK.
Vincent Massol 141.2 18 * A Servlet Container supporting Servlet 3.1 (Servlet 3.0.1 for XWiki version < 12). Check the [[Servlet Containers officially supported by XWiki devs>>dev:Community.ServletContainerSupportStrategy.WebHome]].
Thomas Mortagne 141.1 19 * A Database and a JDBC 4.2 Driver for your database (JDBC 4 was required for XWiki versions < 11.5). Check the [[databases offically supported by XWiki devs>>dev:Community.DatabaseSupportStrategy]].
Vincent Massol 132.1 20 * A supported browser to access XWiki. Check the [[browsers offically supported by XWiki devs>>dev:Community.BrowserSupportStrategy]].
Vincent Massol 124.1 21 * Enough memory, check the [[Memory section>>Documentation.AdminGuide.Performances.WebHome#HMemory]] of the [[Performance Guide>>Documentation.AdminGuide.Performances.WebHome]].
Vincent Massol 131.2 22 * Enough [[CPU and RAM>>Documentation.AdminGuide.Performances.WebHome#HSizing]]
Vincent Massol 132.1 23 * Check the [[release notes>>xwiki:ReleaseNotes.WebHome]] for the version you're installing to see what browsers and databases have been tested for it, and to see specific requirements/installation steps. You can also check our [[general support strategy>>dev:Community.SupportStrategy]].
Vincent Massol 140.1 24 * If you're running XWiki on a server without a display, pass the following Java System Property to the JVM running your Servlet Container: ##-Djava.awt.headless=true##.
Vincent Massol 75.2 25
Guillaume Fenollar 69.1 26 = Installation Methods =
27
Vincent Massol 125.1 28 For testing XWiki, we highly recommend one of the following installation method:
29
Vincent Massol 126.1 30 * [[Using XWiki in the cloud>>Hosted.WebHome]]: This is by far the simplest to try XWiki since you don't need to install anything.
Vincent Massol 138.2 31 * [[Using a standalone distribution >>Documentation.AdminGuide.InstallationStandalone]]: Provides a built-in XWiki, with a portable database (HSQLDB) and a lightweight Java container (Jetty). This standalone distribution is not recommended in a production environment (check the [[DB limitations>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationHSQL.WebHome]]). If you need to use it in a production basis, you may look at the other options.
Vincent Massol 125.1 32 * [[Using an official XWiki Docker image>>https://hub.docker.com/_/xwiki/]]: Provides an easy solution to test XWiki, with a configuration very close to a production setup. You can also use this method in production if you're used to putting Docker images in production.
33
34 For production installations, we recommend the following installation method:
35
Ecaterina Moraru (Valica) 107.4 36 * [[Using .deb package (usable for production)>>Documentation.AdminGuide.InstallationViaAPT]]: Provides a .deb package that can be used on a Debian-based operating system. It can be installed with ##dpkg## or ##apt##; installation is thus automated.
Ludovic Dubost 28.1 37
Vincent Massol 125.1 38 Last, you could manually deploy XWiki as a WAR into the Servlet Container of your choice and on the Database of your choice, if the previous methods were not good enough for your needs. Beware that this requires some technical knowledge about Servlet Container and Databses:
39
40 * [[Using .war package (usable for production)>>Documentation.AdminGuide.InstallationWAR]]: Provides a Java application package that has to be installed in a Java container (such as Tomcat). This can be used on almost any operating system.
41
Vincent Massol 129.1 42 {{warning}}
43 Whatever the installation method, you should make sure to [[create the database indexes manually for indexes that are not created automatically>>Documentation.AdminGuide.Performances.Database Administration.WebHome]].
44 {{/warning}}
45
Vincent Massol 93.1 46 = Other Installation Methods =
Vincent Massol 89.1 47
Vincent Massol 93.1 48 This section is about other, non-official ways of installing XWiki that have been contributed by the community.
Vincent Massol 89.1 49
Vincent Massol 93.1 50 {{warning}}
51 Tutorials external to the xwiki.org site have not been validated for correctness by the XWiki Development Team and it's also possible that they are out of date or even not working.
52 {{/warning}}
53
Thomas Mortagne 154.1 54 * [[Install XWiki in Kubernetes>>https://extensions.xwiki.org/xwiki/bin/view/Extension/XWikiHelm/#HRequirements]]
Thomas Mortagne 153.1 55 * [[How to Install XWiki on Your Synology NAS>>https://mariushosting.com/how-to-install-xwiki-on-your-synology-nas/]]
Vincent Massol 131.1 56 * [[How to install XWiki on Debian 9>>https://linuxhostsupport.com/blog/how-to-install-xwiki-on-debian-9/]]
Thomas Mortagne 144.1 57 * [[Ansible playbook for installing XWiki>>https://github.com/rastandy/xwiki-ansible-playbook]]
Vincent Massol 93.1 58 * [[XWiki On OpenShift (Platform-as-a-Service)>>https://github.com/rkmallik/xwiki-example]]
Vincent Massol 95.2 59 * [[XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL)>>http://www.howtoforge.de/howto/xwiki-on-debian-4-etch-tomcat-mysql]] (German)
60 * [[XWiki On Windows - GlassFish - Oracle>>http://etvc.myxwiki.org/xwiki/bin/view/UNA/XWikiInstalation]] (Russian)
Vincent Massol 153.2 61 * [[Install XWiki using Docker compose>>https://blog.zwindler.fr/2016/09/15/installer-xwiki-8-2-1-avec-docker-compose-en-2-lignes-de-commandes/]] (French)
Thomas Mortagne 145.1 62 * [[XWiki in Windows - PostgreSQL - Tomcat 9 - Waffle>>https://www.youtube.com/watch?v=c2xUsnuDsBE]] (English, video)
Thomas Mortagne 134.1 63 * [[XWiki 10.9 with LDAP/SSO/MSSQL on Windows>>http://www.ohjeah.net/2018/11/09/xwiki-10-9-with-ldapssomssql-on-windows/]]
Vincent Massol 146.2 64 * [[XWiki Installation on AWS>>.XWiki Installation on AWS.WebHome]]
Sanchita Singh 145.2 65 ** [[Deployment using CDK code>>.XWiki Installation on AWS.Deployment Using CDK Code.WebHome]]
66 ** [[Deployment Using Cloudformation Template>>.XWiki Installation on AWS.Deployment Using Cloudformation Template.WebHome]]
Vincent Massol 93.1 67
Vincent Massol 138.1 68 = Accessing your wiki =
69
70 Once you've installed XWiki using one of the methods defined above, you can access it by pointing your web browser to {{code language="none"}}http://localhost:8080/xwiki{{/code}}.
71
Thomas Mortagne 150.1 72 = HTTP Proxy =
Thomas Mortagne 148.1 73
Thomas Mortagne 152.1 74 You now have a working XWiki instance but it's often a good idea to access it trough an HTTP proxy especially when you plan to access it through the standard HTTP/HTTPS port instead of 8080.
Thomas Mortagne 148.1 75
Thomas Mortagne 151.1 76 * [[Apache HTTPD>>Documentation.AdminGuide.Installation.ApacheHTTPD]]
77 * [[NginX>>Documentation.AdminGuide.Installation.NginX]]
Thomas Mortagne 148.1 78
Vincent Massol 31.5 79 = Troubleshooting =
Vincent Massol 1.125 80
Manuel Smeria 75.4 81 You can verify some basic settings of your XWiki installation (on Tomcat, MySQL) using the [[Admin Tools application>>extensions:Extension.Admin Tools Application]]. Keep in mind that some of these tools only work in a Linux environment.
Sergiu Dumitriu 74.1 82
Simon Urli 130.1 83 == What to do with an empty XWiki? ==
84
Sergiu Dumitriu 74.1 85 == Running multiple instances of XWiki in the same container ==
86
87 If you get this error:
88
89 {{code}}
90 com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context
91 Wrapped Exception: Failed to get cache factory component
92 ...
93 Caused by:
94 org.infinispan.jmx.JmxDomainConflictException: Domain already registered org.xwiki.infinispan
95 {{/code}}
96
Valdis Vitolins 110.1 97 You need to edit ##WEB-INF/cache/infinispan/config.xml## for each instance of XWiki.
Roman Muntyanu 74.2 98
Valdis Vitolins 111.1 99 1. For Infinispan up till version 6, change the ##jmxDomain## value (found under the ##globalJmxStatistics## tag) to have a unique name, or add ##allowDuplicateDomains="true"## attribute for ##globalJmxStatistics## element.
Valdis Vitolins 110.1 100 1. For Infinispan version 7, add ##<jmx duplicate-domains="true"/>## element in ##<cache-container...## element.
101
102
Adam Shand 119.1 103 == Running XWiki behind a proxy server ==
Thomas Mortagne 75.1 104
Adam Shand 119.1 105 The extension manager relies on remote repositories for finding and fetching available extensions. If your XWiki is installed in a network which requires accessing the internet through a proxy server, most likely searching for extensions will fail and log files will contain ##connection refused## exceptions.
Roman Muntyanu 74.2 106
Adam Shand 119.1 107 In such cases, you can configure XWiki to use the proxy server.
Roman Muntyanu 74.2 108
Manuel Smeria 75.4 109 XWiki uses default Java proxy configuration through Apache httpclient. See the [[Java Networking and Proxies documentation>>http://docs.oracle.com/javase/6/docs/technotes/guides/net/proxies.html]] for more details.
Adam Shand 119.1 110 The main idea is to add a set of proxy-related properties to the system scope.
Roman Muntyanu 74.2 111
Adam Shand 119.1 112 For an installation using Tomcat 6 it could be done in the following way: modify ##/<tomcat-home>/bin/catalina.sh## and added proxies to the ##JAVA_OPTS## variable definition:
Roman Muntyanu 74.2 113
Eduard Moraru 100.3 114 {{code}}
Adam Shand 119.1 115 JAVA_OPTS="$JAVA_OPTS -Dappserver.home=$CATALINA_HOME -Dappserver.base=$CATALINA_HOME -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777 -Xmx512m -XX:MaxPermSize=196m $XWIKI_OPTS"
Eduard Moraru 100.3 116 {{/code}}
Vincent Massol 84.1 117
Adam Shand 120.1 118 For an installation of the HSQLDB demo package you could do it by adding something like this to ##/xwiki-platform-distribution-flavor-jetty-hsqldb-x.y/start_xwiki.sh##:
Adam Shand 119.1 119
120 {{code}}
121 XWIKI_OPTS="$XWIKI_OPTS -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777"
122 {{/code}}
123
Thomas Mortagne 121.1 124 Note: If your proxy server only allows partial access to the internet you need to make sure that the sites ##store.xwiki.com##, ##extensions.xwiki.org## and ##nexus.xwiki.org## (note that one is .##com## and the others are ##.org##) can be accessed.
Adam Shand 119.1 125
Thomas Mortagne 143.1 126 If your proxy server require authentication you can use ##-Dhttps.proxyUser## and ##-Dhttps.proxyPassword## (and the http alteratives).
127
Eduard Moraru 135.1 128 === Debugging proxy configuration issues ===
129
130 If you are having trouble with debugging whether or not the proxy configuration you've just made is properly read by XWiki, you could drop the following groovy script in a new page on your XWiki instance and look for the values of the (proxy) properties you're trying to change:
131
132 {{code language="groovy"}}
133 {{groovy}}
134 println "== Environment Variables =="
135 System.getenv().each { name, value -> println "Name: {{{$name}}} = Value {{{$value}}}" }
136 println ""
137 println "== Java System Properties =="
138 System.getProperties().each { name, value -> println "Name: {{{$name}}} = Value {{{$value}}}" }
139 {{/groovy}}
140 {{/code}}
141
142 Additionally, you could also include this test content that actually tests if your XWiki instance is able to access the Internet (using the "httpbin" service; you can use anything else, including google.com), for both HTTP and HTTPs:
143
144 {{code language="velocity"}}
145 == Test HTTP Access ==
146 Your XWiki server's IP is:
147 {{velocity}}
148 $xwiki.getURLContent("http://httpbin.org/ip")
149 {{/velocity}}
150
151 == Test HTTPS Access ==
152 Your XWiki server's IP is:
153 {{velocity}}
154 $xwiki.getURLContent("https://httpbin.org/ip")
155 {{/velocity}}
156 {{/code}}
157
Vincent Massol 84.1 158 == Unsupported major.minor version 51.0 ==
159
160 This is because starting with version 6.0, XWiki requires Java 7 and you're using Java 6. You need to upgrade your Java version.
161
Thomas Mortagne 116.1 162 {{include reference="Documentation.AdminGuide.Installation.InstallationConcludingSteps.WebHome" section="HInstallingwithoutinternetconnection"/}}
Vincent Massol 85.1 163
Thomas Mortagne 98.1 164 == Getting an error about SSL certificate ==
165
Vincent Massol 99.4 166 If you get an error in the log telling you that it fail to access some some https website it usually means you have a too old version of Java 8 (older that update 101) and you should upgrade it (does not need to be upgraded to next major version of Java, just make sure you have at least Java 8 update 101).
Thomas Mortagne 98.1 167
168 {{code language="none"}}
169 2017-03-14 20:40:17,494 [http://dwswiki10:8080/xwiki/bin/admin/XWiki/XWikiPreferences?editor=globaladmin&section=XWiki.AddExtensions] ERROR aultExtensionRepositoryManager - Failed to search on repository [store.xwiki.com:xwiki:https://store.xwiki.com/xwiki/rest] with query [org.xwiki.extension.repository.search.ExtensionQuery@78b5e254]. Ignore and go to next repository.
170 org.xwiki.extension.repository.search.SearchException: Failed to search extensions based on pattern []
171 at org.xwiki.extension.repository.xwiki.internal.XWikiExtensionRepository.search(XWikiExtensionRepository.java:434)
Thomas Mortagne 99.1 172 ...
Thomas Mortagne 98.1 173 Caused by: java.io.IOException: Failed to request [https://store.xwiki.com/xwiki/rest/repository/search?start=0&number=20&q=]
174 at org.xwiki.extension.repository.xwiki.internal.XWikiExtensionRepository.getRESTResource(XWikiExtensionRepository.java:246)
Thomas Mortagne 99.1 175 ...
Thomas Mortagne 98.1 176 Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
177 at sun.security.ssl.Alerts.getSSLException(Alerts.java:192)
Thomas Mortagne 99.1 178 ...
Thomas Mortagne 98.1 179 Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
180 at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:387)
Thomas Mortagne 99.1 181 ...
Thomas Mortagne 98.1 182 Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
183 at sun.security.provider.certpath.SunCertPathBuilder.build(SunCertPathBuilder.java:145)
Thomas Mortagne 99.1 184 ...
Thomas Mortagne 98.1 185 {{/code}}
Eduard Moraru 100.2 186
187 == "File path too long" on Windows when unzipping ==
188
Eduard Moraru 100.3 189 The Windows Operating System imposes a [[file path limit to around 260 characters>>https://msdn.microsoft.com/en-us/library/aa365247(VS.85).aspx#maxpath]]. XWiki's zip file can, in some cases, reach paths as long a 182 characters, or even longer. To avoid such errors you could do one of the following:
Thomas Mortagne 101.1 190
Eduard Moraru 100.2 191 * Install in a folder that is as close to the root of the drive as possible and uses a small name, e.g. ##C:\xwiki##
192 * Install XWiki using the [[cygwin>>https://www.cygwin.com/]] environment that overcomes this limitation
193 * Starting with Windows 10, you can set or create the ##EnableLongPaths## with a value of ##1## in the in the ##HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem## Windows Registry in order to activate support for long paths. More details and step-by-step instructions are available in various online tutorials such as [[this one>>https://www.howtogeek.com/266621/how-to-make-windows-10-accept-file-paths-over-260-characters/]].
Vincent Massol 137.2 194 * As Windows Unarchiver cannot unzip files with long paths, [[7-Zip>>https://www.7-zip.org/]]can be used instead.

Get Connected