Installation

Last modified by Vincent Massol on 2024/09/10

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.

If you're upgrading an existing XWiki install check the Upgrade instructions page.

Pick one of the installation methods to begin installing XWiki.

Once you've finished the installation check the other topics in the Admin Guide for configuring and securing your wiki.

Hardware and Software requirements

Installation Methods

For testing XWiki, we highly recommend one of the following installation method:

  • Using XWiki in the cloud: This is by far the simplest to try XWiki since you don't need to install anything.
  • Using a standalone distribution : 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). If you need to use it in a production basis, you may look at the other options.
  • Using an official XWiki Docker image: Provides an easy solution to test XWiki, with a configuration very close to a production setup.

For production installations, we recommend the following installation method:

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 Databases:

Whatever the installation method, you should make sure to create the database indexes manually for indexes that are not created automatically.

Other Installation Methods

This section is about other, non-official ways of installing XWiki that have been contributed by the community.

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.

Accessing your wiki

Once you've installed XWiki using one of the methods defined above, you can access it by pointing your web browser to http://localhost:8080/xwiki.

HTTP Proxy

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.

Troubleshooting

You can verify some basic settings of your XWiki installation (on Tomcat, MySQL) using the Admin Tools application. Keep in mind that some of these tools only work in a Linux environment.

What to do with an empty XWiki?

Running multiple instances of XWiki in the same container

If you get this error:

com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context
Wrapped Exception: Failed to get cache factory component
...
Caused by:
org.infinispan.jmx.JmxDomainConflictException: Domain already registered org.xwiki.infinispan

You need to edit WEB-INF/cache/infinispan/config.xml for each instance of XWiki.

  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.
  2. For Infinispan version 7, add <jmx duplicate-domains="true"/> element in <cache-container... element.
               

Running XWiki behind a proxy server

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.

In such cases, you can configure XWiki to use the proxy server.

XWiki uses default Java proxy configuration through Apache httpclient. See the Java Networking and Proxies documentation for more details.
The main idea is to add a set of proxy-related properties to the system scope.

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:

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"

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:

XWIKI_OPTS="$XWIKI_OPTS -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777"

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.

If your proxy server require authentication you can use -Dhttps.proxyUser and -Dhttps.proxyPassword (and the http alteratives).

Debugging proxy configuration issues

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:

{{groovy}}
println "== Environment Variables =="
System.getenv().each { name, value -> println "Name: {{{$name}}} = Value {{{$value}}}" }
println ""
println "== Java System Properties =="
System.getProperties().each { name, value -> println "Name: {{{$name}}} = Value {{{$value}}}" }
{{/groovy}}

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:

== Test HTTP Access ==
Your XWiki server's IP is:
{{velocity}}
$xwiki.getURLContent("http://httpbin.org/ip")
{{/velocity}}

== Test HTTPS Access ==
Your XWiki server's IP is:
{{velocity}}
$xwiki.getURLContent("https://httpbin.org/ip")
{{/velocity}}

Unsupported major.minor version 51.0

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.

Installing without internet connection

XIP Package

A XIP package is available. It contains an offline extension repository with all the extensions making the Standard Flavor.

This is actually a zip file containing the required XWiki extensions for both the main wiki and subwikis, in the same format as the one of the local extensions repository. It allows the Distribution Wizard to find the extensions locally instead of getting them online and is thus suited for offline installations of XWiki.

  • download it (use the exact same version of the XIP package as the version of XWiki you have)
  • Unzip it (rename it to .zip if your zip tool does not recognize it) in the folder <permanentdirectory>/extension/repository (if you get complains about already existing files don't overwrite them)
  • Make sure the user running XWiki has the permissions to write to these unzipped files
  • Restart XWiki if it was running
  • Resume standard installation, this time it will find the flavor locally

XWiki doesn't offer XIP packages for Contrib Extensions. However it's possible to generate these XIPs.

Other methods

Several options:

Extension Repositories

XWiki performs some checks at startup and even at runtime and tries to connects to remote Extension repositories. This will not cause any problem if you're offline but you'll get some error logs. You may want to disable Extension repositories by editing your xwiki.properties config file and adding the following empty property (make sure that this is the only property defined with the name):

extension.repositories=

Getting an error about SSL certificate

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).

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.
org.xwiki.extension.repository.search.SearchException: Failed to search extensions based on pattern []
        at org.xwiki.extension.repository.xwiki.internal.XWikiExtensionRepository.search(XWikiExtensionRepository.java:434)
...
Caused by: java.io.IOException: Failed to request [https://store.xwiki.com/xwiki/rest/repository/search?start=0&number=20&q=]
        at org.xwiki.extension.repository.xwiki.internal.XWikiExtensionRepository.getRESTResource(XWikiExtensionRepository.java:246)
...
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
        at sun.security.ssl.Alerts.getSSLException(Alerts.java:192)
...
Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
        at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:387)
...
Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
        at sun.security.provider.certpath.SunCertPathBuilder.build(SunCertPathBuilder.java:145)
...

"File path too long" on Windows when unzipping

The Windows Operating System imposes a file path limit to around 260 characters. 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:

  • 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
  • Install XWiki using the cygwin environment that overcomes this limitation
  • 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.
  • As Windows Unarchiver cannot unzip files with long paths, 7-Zipcan be used instead.

Get Connected