Installing XWiki .war package manually

Last modified by Vincent Massol on 2017/01/17 08:47

You'll need to perform 2 mandatory steps:

  • Install and configure a Servlet Container
  • Install and configure a relational database

But first, you'll need to download the .war version of XWiki and check the System Requirements.

Install and configure a Servlet Container

XWiki will work with any Servlet Container (provided it's properly configured obviously). We're only listing instructions for a few containers but you can adapt these instructions for your favorite container.

Some containers have the Java Security Manager turned on. In this case, XWiki needs to be granted some permissions. Below there's a sample policy file if you want to run your container with the Security Manager active. Depending on the version of XWiki Enterprise that you use and on the plugins/extensions that you use the permissions might need to be adjusted to your needs:

grant codeBase "file:<full-path-here>/webapps/xwiki/WEB-INF/lib/-" {
  permission java.util.PropertyPermission "file.encoding", "read";
// Needed by Hibernate -> antlr
  permission java.util.PropertyPermission "ANTLR_DO_NOT_EXIT", "read";
  permission java.util.PropertyPermission "ANTLR_USE_DIRECT_CLASS_LOADING", "read";
// Needed by Hibernate and others
  permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
  permission java.lang.RuntimePermission "createClassLoader";
  permission java.lang.RuntimePermission "setContextClassLoader";
// Needed by commons-logging
  permission java.util.PropertyPermission "org.apache.commons.logging.LogFactory.HashtableImpl", "read";
// Needed for connecting to the database
  permission "", "connect,resolve";
// Needed by the scheduler plugin -> quartz, but works without (maybe except scheduling? should be checked)
//  permission java.util.PropertyPermission "", "read";

//Allow file storage directory reading - for directory and everything underneath
//This is dependent on the setting of environment.permanentDirectory in
permission "${catalina.home}${file.separator}xwikidata${file.separator}", "read,write,delete";
permission "${catalina.home}${file.separator}xwikidata${file.separator}-", "read,write,delete";
//Allow file storage directory reading - temporary directory and everything underneath
//This is dependent on the setting of environment.temporaryDirectory in
permission "${catalina.home}${file.separator}temp${file.separator}", "read,write,delete";
permission "${catalina.home}${file.separator}temp${file.separator}-", "read,write,delete";

You're now ready to install and configure your relational database.

Install and configure a Relational Database

XWiki can work with a lot of relational databases. We're only listing those that we have tested it on. However please note that the XWiki Developers only support some of those databases and the other ones are supported by the community (the XWiki devs apply patches/Pull Requests).

The general strategy is the following:

  • Install your favorite RDBMS
  • Create a xwiki database
  • Create a user with all privileges on that database
  • Copy your RDBMS Java drivers to the XWiki webapp's WEB-INF/lib directory
  • Configure XWiki to use the created database. This involves modifying the WEB-INF/hibernate.cfg.xml file as is described in the tutorials for each database below.
  • XWiki will automatically create the various tables it needs when it executes on the first run

Specific databases instructions

Install and configure the database you wish to use:

Using a Data Source

A more scalable and J2EE-conformant tactic is to use the Servlet Container to manage your data source. You modify the web app as little as possible.

  • Do not add your JDBC library to the web app. Install it to the container's classpath instead, like in $CATALINA_HOME/common/lib.
  • Do not set user, url, etc., nor connection.provider_class in hibernate.cfg.xml. The critical settings are connection.datasource (with JNDI name like java:/comp/env/jdbc/XWikiDS) and the dialect class for your DB vendor. Do not comment out <mapping resource="..."/> elements, hibernate needs them. Note that you should leave the provider_class unset, since XWiki's implementation doesn't handle container-managed data sources.
  • Manage all database access settings using your container facilities, for example Tomcat admin webapp or server.xml + APPNAME.xml. Uncommenting the <resource-ref> element inside WEB-INF/web.xml that matches the above JNDI name and looks like <res-ref-name>jdbc/XWikiDS</res-ref-name> could be a good idea.

Install the XWiki UI

At this point your wiki is empty, i.e it doesn't contain any wiki page. Since applications in XWiki are done in wiki pages you also don't any application available (e.g. Blog, User Directory, User Profiles, etc). In addition, you wiki doesn't contain any user.  

Thus the final step is to fill your Wiki with some initial content (i.e. wiki pages).

This is the job of the Distribution Wizard which automatically starts when you are browsing your new XWiki instance for the first time.

Before XWiki 8.0, the Distribution Wizard was automatically creating an "Admin" user (with a password of admin - in lowercase), which you can then use to log in your wiki. Starting with XWiki 8.0, the Distribution Wizard has a wizard step to let you create an admin user of your choice.

The default distribution is a fully configured wiki that you can use as a starting point for creating your own wiki content. It provides the following:

Manually Import Wiki Pages

Alternatively, you could skip the Distribution Wizard (this can be useful for example if you're offline and wish to install XWiki). However you'd need to perform either of the following operations:

  • Create new pages by hand
  • Import the default Wiki that we are providing as a XAR file by using the Import feature. Since there's no Admin user created at this point, you'll need to log in as superadmin to be able to perform this import. 

If you're upgrading an existing wiki using the manual Import feature, be careful that the XAR import operation will replace the content of the existing pages of your wiki with the content of the XAR (New pages that you have created will not be modified). As a consequence it's critical that you perform a backup first and read the upgrade nodes bellow carefully.

On the other hand, if you use the Distribution Wizard, it'll automatically perform a merge and prompt you for action in case there's a conflict it cannot resolve automatically. Thus using the Distribution Wizard is what we recommend.

Created by Guillaume Fenollar on 2012/01/25 10:29

Get Connected