XWiki Standard 9.8.1 Documentation » XWiki Setup Overview » XWiki Standard Installation and Upgrade

XWiki Standard Installation and Upgrade

Download and Install Java

Starting with version 8.0, we are using Java 1.8 that can be downloaded from the Java website. If you use an earlier version of Java, you will get an error while starting XWiki:

Caused by: java.lang.UnsupportedClassVersionError: org/xwiki/tools/jetty/listener/NotifyListener : Unsupported major.minor version 52.0

The XWiki Standalone Distribution

The standalone installation includes an already configured Jetty container and an HSQLDB database. To install it, you just need to unpack the file xwiki-<version>.zip or xwiki-standard-<version>.zip (XWiki Standard Flavor) available here.

In the directory containing the unpacked zip file, you will also find:

  • start_xwiki.sh (start_xwiki.bat for Windows systems) which starts the Jetty server containing the XWiki platform
  • stop_xwiki.sh (stop_xwiki.bat for Windows systems) which stops the Jetty server containing the XWiki platform
  • the webapps/xwiki directory containing the XWiki Web Application. You will mostly access:
    • the file webapps/xwiki/WEB-INF/hibernate.cfg.xml containing the database communication hibernate parameters
    • the files webapps/xwiki/WEB-INF/xwiki.cfg and webapps/xwiki/WEB-INF/xwiki.properties containing the XWiki configuration parameters

Next, you have to point your server to http://localhost:8080.

Change the Jetty Port

If you already have a Web server running on port 8080, you need to set another port in the start script. This can be done by editing the file start_xwiki.sh (or start_xwiki.bat for Windows systems) and by modifying the value of the "JETTY_PORT" parameter. 

You can do the same thing directly in the command line by executing 

./start_xwiki.sh ##port_number##

Install XWiki Without Internet Connection

Starting with version 9.5, a XIP package is available for the XWiki Standard flavor that you can download from here. This is actually a zip file containing the required XWiki extensions in the same format than the local extensions repository.

In order to use it:

  • unzip the file (in case the file extension is not recognized, you might have to rename it to .zip) in the folder <permanentdirectory>/extension/repository
  • restart XWiki if it was running
  • resume the standard installation so that the flavor is found locally

Production Installs

Install XWiki using Docker

Docker is a tool designed to make it easier to create, deploy and run applications by using containers. Containers allow a developer to package up an application with all of the parts it needs, such as libraries and other dependencies, and ship it all out as one package. By doing so, thanks to the container, the developer can rest assured that the application will run on any other machine regardless of any customized settings that machine might have that could differ from the machine used for writing and testing the code.
The complete guide to install XWiki in Docker is available on https://github.com/xwiki-contrib/docker-xwiki/blob/master/README.md. The easiest way to get started with XWiki in Docker is to use existing images (from DockerHub or built from the sources).
Next, you can use the docker run command and follow three basic steps to run a container for the XWiki image and one for the database image to which XWiki connects to. This blog article explains how to get started with XWiki in Docker.

Deploy the XWiki Standard WAR

To install the XWiki Standard WAR, you need to get the latest xwiki-<version>.war available here. This WAR distribution requires the configuration of a servlet container and a relational database to work with it.

Install and Configure a Servlet Container

XWiki Standard is able to work with any servlet container. You can consult the installation and configuration instructions are available for:

If you are using Tomcat, you need to make sure you set the UTF-8 encoding for URLs. To do so, edit your "conf/server.xml" file and add URIEncoding="UTF-8 to the the HTTP connector listening to the port "8080" (or the one you are using):

<Connector port="8090" protocol="HTTP/1.1"
           URIEncoding="UTF-8 />

Install and Configure a Relational Database

If you choose to install MySQL, you will have to also copy the MySQL JDBC Driver named mysql-connector-java*.jar in the XWiki's \webapps\xwiki\WEB-INF\lib directory. If don't already have it, you can get it from here.

Finally, you will have to configure XWiki Standard to use the installed database by editing the hibernate.cfg.xml file located in the \webapps\xwiki\WEB-INF\ folder. In this file, you will need to uncomment the corresponding database configuration. For instance, if you are using the MySQL database, you will comment the following lines:

 <property name="connection.url">jdbc:hsqldb:file:${environment.permanentDirectory}/database/xwiki_db;shutdown=true</property>
   <property name="connection.username">sa</property>
   <property name="connection.password"></property>
   <property name="connection.driver_class">org.hsqldb.jdbcDriver</property>
   <property name="dialect">org.hibernate.dialect.HSQLDialect</property>

   <mapping resource="xwiki.hbm.xml"/>
   <mapping resource="feeds.hbm.xml"/>
   <mapping resource="activitystream.hbm.xml"/>
   <mapping resource="instance.hbm.xml"/>
   <mapping resource="mailsender.hbm.xml"/>

and uncomment the lines below:

<property name="connection.url">jdbc:mysql://localhost/flavor_xwiki</property>
   <property name="connection.username">xwiki</property>
   <property name="connection.password">xwiki</property>
   <property name="connection.driver_class">com.mysql.jdbc.Driver</property>
   <property name="dialect">org.hibernate.dialect.MySQL5InnoDBDialect</property>
   <property name="dbcp.poolPreparedStatements">true</property>
   <property name="dbcp.maxOpenPreparedStatements">20</property>
   <mapping resource="xwiki.hbm.xml"/>
   <mapping resource="feeds.hbm.xml"/>
   <mapping resource="activitystream.hbm.xml"/>
   <mapping resource="instance.hbm.xml"/>
   <mapping resource="mailsender.hbm.xml"/>

In case you have chosen another name for your MySQL database, for instance "projects" make sure you also make the following changes in the configuration files:

  • In the "WEB-INF/hibernate.cfg.xml" file update the line <property name="connection.url">jdbc:mysql://localhost/xwiki</property> in the MySQL configuration section
  • In the "WEB-INF/xwiki.cfg" file uncomment and update the parameter xwiki.db and eventually xwiki.db.prefix in case you are using prefixes for the sub-wiki database names.

Installation of the default UI using the Distribution Wizard

During first startup, the database being empty, you will be directed to the second step for proceeding to the installation of the default UI. The appropriate UI package will be pre-selected and proposed for installation. During the installation, you will be prompted to register your own user as the owner, meaning that you won't ever lose administration rights for that user, unless you change the owner. The reason is to avoid security issues because in older XE version we used to have a hardcoded Admin user with the password admin and administrators had to change it explicitly or they would risk anyone being able to connect to their instance.

Note that the main wiki owner now has Programming Rights by default, not only Administration Rights.

Proceeding with the Distribution Wizard requires a connection to the Internet from the server. If your server is disconnected from the Internet, you may skip the Distribution Wizard and proceed to the manual installation of the Default XWiki XAR.

The XWiki Standard XAR does not contain any descriptor for the main wiki anymore. This descriptor is now automatically created/updated at startup and associated to the domain name found in the URL that was used to access the wiki the first time.

Finally, starting with version 8.4, sub-wikis have asynchronous initialization which reduces the chance that one or several initializing wikis end up eating all the farm input threads.


Manually Import the Default XWiki XAR

You need this step only if you were unable to use the Distribution Wizard to install the default UI.
The xwiki-platform-distribution-flavor-mainwiki-9.8.1.xar file available here contains a set of default XWiki pages which you can import in an empty XWiki instance. For sub-wikis, the xwiki-platform-distribution-flavor-wiki-9.8.1.xar should be used, and it is available here

Configure Multi-Wiki URL Access and Descriptors

The URL Path Based Access

This mode is enabled by default so you can access sub-wikis using an URL like http://hostname.domain.tld/xwiki/wiki/WikiAlias/view/Space/Page.

The /wiki/ part is used by XWiki to identify the URL as an URL path based multi-wiki access. This part is configurable through the property xwiki.virtual.usepath.servletpath from the xwiki.cfg file.

In path based mode you can manage your wiki descriptor from the wiki administration, and there is no need to manage any special wiki aliases.

The Domain Name Based Access

This mode is disabled by default. To enable it, set the xwiki.virtual.usepath parameter to 0 in the "xwiki.cfg" file. 

You also need to configure your DNS with a wildcard CNAME that redirect *.domain.tld (or *.hostname.domain.tld depending on your use case) to hostname.domain.tld. The goal being that reaching the XWiki server could be achieved with hostname like: wikiname.domain.tld (or wikiname.hostname.domain.tld). If you are using SSL, your SSL certificate should also support wildcard names which is generally a paid option. You may also define additional unrelated DNS CNAME entries for the wikis, but this method will not allow dynamic creation of new wikis without a system administrator intervention on the DNS.

In domain based mode, you can access a wiki using the domain name (or the alias) registered in its descriptor with the field server ("Alias" in the UI). For example, if the URL is http://hostname.domain.tld, the value of the server field should be "hostname.domain.tld". You currently cannot manage this information from the wiki administration, but you can edit it from the Wiki index, using the edit action (you need to be an administrator to see this action).

When no matching alias is found:

  • if the host is an IP address (,, etc.), XWiki selects the main wiki
  • else, if the first part of the host name is "www", XWiki selects the main wiki
  • else, if the first part of the host name matches a wiki identifier, XWiki selects this wiki

If no wiki is found, by default, the main wiki is displayed. If you want an error to be displayed, you can configure xwiki.virtual.failOnWikiDoesNotExist to 1 in xwiki.cfg to have the wikidoesnotexist.vm template or xwiki:XWiki.WikiDoesNotExist page displayed. The old xwiki.virtual.redirect configuration is not supported anymore.

So, to be able to access your wiki you may need :

  • to ensure xwiki.virtual.failOnWikiDoesNotExist is 0 or not defined OR
  • to configure your DNS OR
  • to modify the hosts file in your operating system.
Note that you have to set the xwiki.authentication.logoutpage property accordingly. Modify the "wiki" part inside the value of the property for the right alias.

Running Multiple Instances of XWiki in the Same Container

In case you have several instances of XWiki Standard in the "webapps" folder of Tomcat (or any other servlet container from this list), you need to edit the  WEB-INF/cache/infinispan/config.xml file. Next, for each instance of XWiki, you have to change the jmxDomain value under the globalJmxStatistics tag so that each web application has a unique name. The default value is org.xwiki.infinispan:


Otherwise, you will get the below error message in the console or in the log files:

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

Running XWiki Behind a Proxy

Distribution Wizard and the Extension Manager require an Internet connection for searching and downloading extensions. In case your XWiki Standard instance works in a network that is accessing the internet through a proxy-server, the search results will come up empty and you will get "Connection Refused Exception" in the log files. To fix this, you must set up XWiki to know your proxy-server using "Apache httpclient" which is the default Java proxy configuration.

For Linux systems, modify the "/<tomcat-home>/bin/catalina.sh" file and add the proxy 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"


  • Dhttp.proxyHost and -Dhttps.proxyHost represent the name of the proxy-server
  • -Dhttp.proxyPort and -Dhttps.proxyPort are the listening ports

On a Windows system, run the "Monitor Tomcat" tool, click the "Java" tab and add the line below to "Java Options":

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"

Upgrade the Main Wiki

Backup the Existing Data

In order to avoid having post upgrade issues it is essential that you backup your wiki. 

Backup the Databases

In case you have installed and configured a relational database it is recommended that you create a copy before upgrading. To do this execute mysqldump --add-drop-database --databases xwiki > xwiki.sql for MySQL. 

If you have also subwikis, you need to add their names next to xwiki in the above command to include them in the backup.

Backup the Installed Extensions

The extensions installed by the Distribution Wizard or by the Extension Manager are cached in the extensions folder of the permanent directory set for the servlet container.

Backup the Attachments

If you are storing attachments on the filesystem you will also have to make a copy of the storage folder in the permanent directory set for the servlet container. The default value is defined by the environment.permanentDirectory property of your WEB-INF/xwiki.properties configuration file.

Backup the SOLR Index Folder

If you are using SOLR as default search engine you need to locate the SOLR index folder which is environment.permanentDirectory/solr.

Since the Solr configuration is stored on the filesystem in the environment.permanentDirectory/solr folder, it is recommended that you delete the entire folder before the upgrade. The reason for this is the fact that the Solr configuration might change between releases and by deleting the folder it will be recreated with the new configuration. 

Backup the Configuration Files

In addition to the drivers and plugins you might have installed in your wiki, you also need a backup of several configuration files:

  • the Hibernate configuration file WEB-INF/hibernate.cfg.xml
  • the old XWiki Standard configuration file WEB-INF/xwiki.cfg
  • the new XWiki Standard configuration file WEB-INF/xwiki.properties
  • the Logging configuration file WEB-INF/classes/logback.xml
  • the WEB-INF/cache/infinispan/config.xml file that stores the unique value of jmxDomain; you should only backup this file when you have multiple XWiki instances in the same servlet container 

These files should be merged with the new versions.

Backup the Skin Folder

If you have a custom skin that is stored on the filesystem, make sure you backup the corresponding folder located in the webapps/xwiki/skins/ directory. 

Upgrade the Web Application

The recommended strategy is to stop the servlet container, download the xwiki-platform-distribution-war-9.8.1.war  file you want to upgrade to then expand it. It is important not to copy the new files on top of the old ones because XWiki Standard would fail due to the old JARs that still remain in the /WEB-INF/lib/ folder.

Next, check that the WEB-INF/xwiki.cfg file is properly configured for a migration as shown below:

#-# Whether migrations are enabled or not. Should be enabled when upgrading, but for a better startup time it is better to
#-# disable them in production.

#-# Whether to exit after migration. Useful when a server should handle migrations for a large database, without going
#-# live afterwards.
# xwiki.store.migration.exitAfterEnd=0

#-# Indicate the list of databases to migrate.
#-# to upgrade all wikis database set xwiki.store.migration.databases=all
#-# to upgrade just some wikis databases set xwiki.store.migration.databases=xwiki,wiki1,wiki2
#-# Note: the main wiki is always migrated whatever the configuration.
# xwiki.store.migration.databases=

You should also check the Release Notes for all the versions from the version you are upgrading from up to the new version you are installing in order to find out about the new features or configuration changes.

Restore the Databases

The main steps to follow when restoring the MySQL database are:

  • Stop the servlet container
  • Restore the data from the dump with mysql xwiki --user=root -p < xwiki.sql
  • Start the servlet container

More information regarding the restore process is available on xwiki.org.

Upgrade the XWiki XAR

After restarting the servlet container, if you access any wiki page and log in, the Distribution Wizard will be triggered in order to help you perform the XAR upgrade. The pages that you have already modified will be automatically handled thanks to the merge conflict resolution feature.

Upgrade the Sub-Wikis XAR

The easiest way is to let the Distribution Wizard handle the XAR upgrade for sub-wikis during the third step of the process. This way, the pages that you have already modified will be automatically handled thanks to the merge conflict resolution feature. 

Enable the superadmin Account

In case access rights get corrupted and you cannot authenticate with your wiki administrator user, you may choose to enable the superadmin account as follows:

  • edit the "WEB-INF/xwiki.cfg" file
  • uncomment the line # xwiki.superadminpassword=system
  • restart XWiki
  • login with the user superadmin and the password indicated by the xwiki.superadminpassword configuration parameter

Download Older Versions of Our Products

If you are interested in some older versions of the XWiki products you can check this page.

Enhance your wiki using XWiki Pro

XWiki Pro offers a full set of productivity and business-oriented applications on top of XWiki. The package gives you access to all the paid apps developed by XWiki SAS, as well as some free apps. XWiki Pro also includes support for your XWiki instance and is available both on-premise, as well as in the cloud, starting at the Silver level.


How to install XWiki Pro?

The guide to install XWiki Pro is available on the XWiki Store: https://store.xwiki.com/xwiki/bin/view/Extension/XWikiPro/#installation


Related Pages

Trying to decide between Cloud and On Premise? See the comparison on the XWiki Help Center.

Search this space