XWiki Enterprise 8.4.4 Documentation » XWiki Enterprise Setup Overview » XWiki Enterprise Installation and Upgrade

XWiki Enterprise Installation and Upgrade

Quick Installs

The Graphical Windows Native Installer

The graphical Windows native installer includes an already configured Jetty container and an HSQLDB database but it requires administration rights on the target operating system. To install it, you need to execute the latest xwiki-enterprise-installer-windows-<version>.exe file available here and follow the on-screen instructions.

To start XWiki, click on the "Start XWiki Enterprise" desktop icon which will open a DOS window for the running server. Next, you have to point your server tohttp://localhost:8080. To stop XWiki, click on the "Stop XWiki Enterprise" desktop icon.

The XWiki Enterprise Generic Installer

This installer works on all platforms and it needs Java to execute. Just like for the graphical Windows native installer, you must have administration rights on the target operating system. To install it, you need to double click on the latest xwiki-enterprise-installer-generic-<version>-standard.jar file available here and follow the instructions.

To learn how to start or stop the server, follow this link.

Download and Install Java

Starting with XWiki Enterprise 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 Enterprise 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-enterprise-jetty-hsqldb-<version>.zip 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 XEM 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##

Production Installs

Deploy the XWiki Enterprise WAR

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

We have also started to work on a minimal XWiki distribution in order to have a WAR as small as possible allowing to install one of the Flavors found automatically in the registered repositories. For now, this is just extensions.xwiki.org. The new distribution has 188MB (compared to the 219MB of XWiki Enterprise) - one important limitation is that some old plugins were kept because they were too difficult to install as extensions.

Install and Configure a Servlet Container

XWiki Enterprise 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 Enterprise 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 Enterprise 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-enterprise-ui-mainwiki-all-<version>.xar file available here contains a set of default XWiki pages which you can import in an empty XWiki instance. For subwikis, the xwiki-enterprise-ui-wiki-all-<version>.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 Enterprise 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 Enterprise Behind a Proxy

Distribution Wizard and the Extension Manager require an Internet connection for searching and downloading extensions. In case your XWiki Enterprise 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 Lucene Index Folder

The default folder that stores the Lucene index is environment.permanentDirectory/lucene. The default value is defined by the xwiki.plugins.lucene.indexdir property of your WEB-INF/xwiki.cfg file. In order to properly start the indexation after the upgrade, it is recommended to delete the folder content. 

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 Enterprise configuration file WEB-INF/xwiki.cfg
  • the new XWiki Enterprise 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-enterprise-web-<version>.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 Enterprise 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 Enterprise 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.


Search this space