Wiki source code of Installation

Version 137.2 by Vincent Massol on 2018/12/05

Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
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 (HSQL, MySQL, etc) but XWiki and the database need to be setup correctly.
6
7 If you're upgrading an existing XWiki install check the [[Upgrade instructions page>>Documentation.AdminGuide.Upgrade]].
8
9 Pick one of the [[installation methods>>#HInstallationMethods]] to begin installing XWiki.
10
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.
12
13 {{id name="Prerequisites"/}}
14
15 = Hardware and Software requirements =
16
17 * Java 1.8.0_101 or greater installed for XWiki >= 8.1 (Java 7 or greater for XWiki < 8.1, Java 6 or greater for XWiki versions < 6.0). {{warning}}For the moment we don't recommend running on Java 9+ since we're still testing it and fixing issues. If you really insist on Java 9+, make sure to use the latest released version of XWiki!{{/warning}}.
18 * A Servlet Container supporting Servlet 3.0.1 (Servlet 2.4 for XWiki versions < 7.0). Check the [[Servlet Containers officially supported by XWiki devs>>dev:Community.ServletContainerSupportStrategy.WebHome]].
19 * A Database and a JDBC 4 Driver for your database (JDBC 3 was required for XWiki versions < 7.0). Check the [[databases offically supported by XWiki devs>>dev:Community.DatabaseSupportStrategy]].
20 * A supported browser to access XWiki. Check the [[browsers offically supported by XWiki devs>>dev:Community.BrowserSupportStrategy]].
21 * Enough memory, check the [[Memory section>>Documentation.AdminGuide.Performances.WebHome#HMemory]] of the [[Performance Guide>>Documentation.AdminGuide.Performances.WebHome]].
22 * Enough [[CPU and RAM>>Documentation.AdminGuide.Performances.WebHome#HSizing]]
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]].
24
25 = Installation Methods =
26
27 For testing XWiki, we highly recommend one of the following installation method:
28
29 * [[Using XWiki in the cloud>>Hosted.WebHome]]: This is by far the simplest to try XWiki since you don't need to install anything.
30 * [[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. If you need to use it in a production basis, you may look at the other options.
31 * [[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.
32
33 For production installations, we recommend the following installation method:
34
35 * [[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.
36
37 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:
38
39 * [[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.
40
41 {{warning}}
42 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]].
43 {{/warning}}
44
45 = Other Installation Methods =
46
47 This section is about other, non-official ways of installing XWiki that have been contributed by the community.
48
49 {{warning}}
50 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.
51 {{/warning}}
52
53 * [[How to install XWiki on Debian 9>>https://linuxhostsupport.com/blog/how-to-install-xwiki-on-debian-9/]]
54 * [[Ansible playbook for installing XWiki>>https://github.com/rastandy/xwiki-ansible-playbook]]
55 * [[Using yaourt on Arch Linux>>https://github.com/xwiki-contrib/packaging-archlinux]]
56 * [[XWiki On OpenShift (Platform-as-a-Service)>>https://github.com/rkmallik/xwiki-example]]
57 * [[XWiki On Windows>>http://agoncalves.developpez.com/tutoriels/xwiki/creer-un-site-associatif/]] (French)
58 * [[XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL)>>http://www.howtoforge.com/xwiki-tomcat-mysql-debian-etch]] (English)
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)
61 * [[XWiki on OpenSUSE - Tomcat - MySQL)>>http://geistreicher-papierkorb.blogspot.com/2011/03/setting-up-xwiki-on-opensuse-with-mysql.html]] (English)
62 * [[XWiki On Archlinux - Tomcat - hsql or MySQL>>https://github.com/xwiki-contrib/packaging-archlinux]] (English)
63 * [[Install XWiki on an Ubuntu 16.04 VPS>>https://www.rosehosting.com/blog/install-xwiki-on-an-ubuntu-16-04-vps/]] (English)
64 * [[Install XWiki using Docker compose>>https://zwindler.fr/wordpress/2016/09/15/installer-xwiki-8-2-1-avec-docker-compose-en-2-lignes-de-commandes]] (French)
65 * [[How to Install XWiki on CentOS 7>>https://thishosting.rocks/how-to-build-your-own-wiki-with-xwiki-on-centos/]] (English)
66 * [[XWiki in Windows - PostgreSQL - Tomcat 9 - Waffle>>https://www.youtube.com/watch?v=QLqsvQ5y6cI]] (English, video)
67 * [[XWiki 10.9 with LDAP/SSO/MSSQL on Windows>>http://www.ohjeah.net/2018/11/09/xwiki-10-9-with-ldapssomssql-on-windows/]]
68
69 = Troubleshooting =
70
71 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.
72
73 == What to do with an empty XWiki? ==
74
75 == Running multiple instances of XWiki in the same container ==
76
77 If you get this error:
78
79 {{code}}
80 com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context
81 Wrapped Exception: Failed to get cache factory component
82 ...
83 Caused by:
84 org.infinispan.jmx.JmxDomainConflictException: Domain already registered org.xwiki.infinispan
85 {{/code}}
86
87 You need to edit ##WEB-INF/cache/infinispan/config.xml## for each instance of XWiki.
88
89 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.
90 1. For Infinispan version 7, add ##<jmx duplicate-domains="true"/>## element in ##<cache-container...## element.
91
92
93 == Running XWiki behind a proxy server ==
94
95 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.
96
97 In such cases, you can configure XWiki to use the proxy server.
98
99 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.
100 The main idea is to add a set of proxy-related properties to the system scope.
101
102 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:
103
104 {{code}}
105 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"
106 {{/code}}
107
108 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##:
109
110 {{code}}
111 XWIKI_OPTS="$XWIKI_OPTS -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777"
112 {{/code}}
113
114 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.
115
116 === Debugging proxy configuration issues ===
117
118 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:
119
120 {{code language="groovy"}}
121 {{groovy}}
122 println "== Environment Variables =="
123 System.getenv().each { name, value -> println "Name: {{{$name}}} = Value {{{$value}}}" }
124 println ""
125 println "== Java System Properties =="
126 System.getProperties().each { name, value -> println "Name: {{{$name}}} = Value {{{$value}}}" }
127 {{/groovy}}
128 {{/code}}
129
130 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:
131
132 {{code language="velocity"}}
133 == Test HTTP Access ==
134 Your XWiki server's IP is:
135 {{velocity}}
136 $xwiki.getURLContent("http://httpbin.org/ip")
137 {{/velocity}}
138
139 == Test HTTPS Access ==
140 Your XWiki server's IP is:
141 {{velocity}}
142 $xwiki.getURLContent("https://httpbin.org/ip")
143 {{/velocity}}
144 {{/code}}
145
146 == Unsupported major.minor version 51.0 ==
147
148 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.
149
150 {{include reference="Documentation.AdminGuide.Installation.InstallationConcludingSteps.WebHome" section="HInstallingwithoutinternetconnection"/}}
151
152 == Getting an error about SSL certificate ==
153
154 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).
155
156 {{code language="none"}}
157 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.
158 org.xwiki.extension.repository.search.SearchException: Failed to search extensions based on pattern []
159 at org.xwiki.extension.repository.xwiki.internal.XWikiExtensionRepository.search(XWikiExtensionRepository.java:434)
160 ...
161 Caused by: java.io.IOException: Failed to request [https://store.xwiki.com/xwiki/rest/repository/search?start=0&number=20&q=]
162 at org.xwiki.extension.repository.xwiki.internal.XWikiExtensionRepository.getRESTResource(XWikiExtensionRepository.java:246)
163 ...
164 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
165 at sun.security.ssl.Alerts.getSSLException(Alerts.java:192)
166 ...
167 Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
168 at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:387)
169 ...
170 Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
171 at sun.security.provider.certpath.SunCertPathBuilder.build(SunCertPathBuilder.java:145)
172 ...
173 {{/code}}
174
175 == "File path too long" on Windows when unzipping ==
176
177 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:
178
179 * 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##
180 * Install XWiki using the [[cygwin>>https://www.cygwin.com/]] environment that overcomes this limitation
181 * 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/]].
182 * As Windows Unarchiver cannot unzip files with long paths, [[7-Zip>>https://www.7-zip.org/]]can be used instead.

Get Connected