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.

There are 2 solutions when installing XWiki:

• Use the Standalone distribution which already packages a Servlet Container (Jetty) and a database (HSQL). This is the recommended option for first time XWiki users and for users who wish to quickly try out XWiki.
• Use the WAR distribution and configure both your container and your database to work with it.

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

Pick one of the trails in the outline on the right to get started.

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

Tutorials

Tutorials are step by step procedures to install XWiki for a specific configuration. You can choose to follow one of them or follow the instructions in the sections below.

• XWiki On Windows (French)
• XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL) (English)
• XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL) (German)
• XWiki On Windows - GlassFish - Oracle (Russian)
• XWiki on OpenSUSE - Tomcat - MySQL (English)

Prerequisites

• Java 6 or greater installed.
• A minimum of 300MB of heap memory and 96MB of permGen. Recommended value are above 512MB for the heap and 128MB for the permGen (-Xmx512m -XX:MaxPermSize=128m)
• XWiki has been tested on the following browsers:
  • Firefox 3.6
  • Firefox 4
  • Internet Explorer 6.x
  • Internet Explorer 7.x
  • Internet Explorer 8.x
  • Chrome 13

Installing the Standalone distribution

This is by far the easiest way to install XWiki. We are offering 3 packaging for ease of installation:

• A Windows exe. Simply execute it and follow the instructions. Do not close the DOS Windows that shows up. This is the XWiki server running, instead point your browser tohttp://www.localhost:8080/.
• A generic Installer that works on all platforms. It requires Java to be installed on your system. Simply double-click on it and follow the instructions.
• A zip version. Unzip it in any XWIKIHOME directory of your choice.

The Windows installer creates shortcuts to start and stop XWiki in your Windows start menu. Launch the Wiki using "start".

If you've used the zip file or generic Installer, go to the directory where you've installed XWiki (XWIKIHOME) and run start_xwiki.bat in Windows or start_xwiki.sh on Unix. To stop it, run the stop_xwiki.bat script on Windows and stop_xwiki.sh on Unix or Mac. On Mac you will need to use "Open with Terminal" or run this script from the Terminal.

Once XWiki is started point your browser tohttp://localhost:8080/and the go to the User's Guide to learn how to use XWiki.

In some cases, you might already have a Web Server running on port 8080. If this happens you have to pass another the port to the start script (e.g. by using the port 8081, as in start_xwiki.sh 8081).

Installing the XWiki WAR manually

You'll need to perform 2 mandatory steps:

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

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.

• Tomcat installation
• Jetty installation
• GlassFish installation
• WebSphere installation
• JBoss Installation
• Oracle OC4J Installation
• Apache Geronimo

Some containers have the Java Security Manager turned on. In this case, XWiki needs to be granted some permissions. Here's below 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:

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 listed those that we have tested it on.

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.
• (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... hopefully one day Xwiki will allow you to override hibernate.cfg.xml without needing to change the app itself.
  • Do not add your JDBC library to the web app.  Install it to the container classpath instead, like to $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. (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 and configure the database you wish to use:

• HSQL Installation
• MySQL Installation
• PostgreSQL Installation
• Oracle Installation
• DB2 Installation
• Derby Installation
• Microsoft SQL Server Installation
• H2 Installation

Concluding Step

At this stage you have finished configuration XWiki. If you start your database and container and point your browser to http://localhost:8080/xwiki/ you'll have a working, albeit minimal, wiki (without any page loaded). The next step is either to create new pages by hand or import the default Wiki that we are providing as a XAR file, by using the Import feature.

Installing the Default Wiki XAR

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

• A Blog
• A Recent Changes page
• The Panels Application
• Search
• Administration page (Access rights, Group and users management, etc)
• ... and much more

It comes configured with an "Admin" user (password is "admin" in lowercase). You'll need that username/password to log in once you've imported the default wiki.

To install the XAR, use the Import/Export tool.

Upgrading an XWiki Installation

There are different parts of XWiki that you may want to upgrade:

• XWiki Core
• Documents provided with the default XWiki XAR

Upgrading XWiki Core

The general strategy is to download the WAR distribution and to replace your current installed WAR. Make sure you don't copy on top since this could leave some old files around which would make XWiki fail (like if old JARs are lying around in WEB-INF/lib). Before replacing your current WAR, make sure you back it up and more specifically that you copy the hibernate.cfg.xml, xwiki.cfg and xwiki.properties files which you'll need to copy in your newly installed WAR since they contain your XWiki configuration. Make sure you also copy any plugins you may have added or any template files you may have modified.

Some additional operations may be required for upgrading and you must check the release notes for all the versions from the version you're upgrading from up to the new version you're installing. It's also possible that new features are available and that your xwiki.cfg file needs to be modified. If this is the case then it'll be specified in the release notes.

Note that the database schema is automatically upgraded when needed. All you need to do is to ensure your xwiki.cfg file is correctly configured to perform the migration. Here's a relevant excerpt from the xwiki.cfg file:

Upgrading wiki documents

You may want to upgrade to a newer version of the Default Wiki XAR in order to benefit from the latest changes. As mentioned above in the "Installing the Default Wiki XAR" section you should be very careful and when doing the import make sure you selectively decide what pages you wish to import. More specifically the following pages should be imported with great care:

• XWiki.XWikiPreferences: This page contains some configuration of your wiki (it overrides the configuration defined in xwiki.cfg). If you import a new version of this page you'll loose any customization you may have made such as the skin to use, the rights for your wiki, etc.
• XWiki.RegistrationConfig: Contains Registration configuration of your wiki.
• Invitation.InvitationConfig: Configuration for the Invitation Application.
• XWiki.WebPreferences, Main.WebPreferences, and all other spaces WebPreferences pages: Same as XWiki.XWikiPreferences but at the level of a space.
• XWiki.XWikiAllGroup (list of registered users) and XWiki.AdminGroup (list of Admins): If you have existing users and import a new version of these pages, you'll find that your users do not belong to these groups anymore and thus may not be able to edit pages, log in, etc. You'll need to add them again to the right groups.
• XWiki.Admin: This page contains the Admin user with the default password. If you import it you'll create a security hole. Thus it's very important not to import this page.
• Any other page you have modified, such as Main.WebHome, a modified Panel, etc.

Let's clean it up

• Expand the XWiki WAR that you installed in your servlet container (the one that contains the JDBC drivers to access your database) into a new folder, using jar xvf xwiki-enterprise-web-3.1.war, or avoid this step if you performed an export/import data migration (you already expanded it) 
• Merge your old xwiki.cfg, xwiki.properties and hibernate.cfg.xml files with the new versions found in the WEB-INF folder. Take care that if some changes were already made (probably because of database configuration when you installed the JDBC drivers) could be lost, so take care to add these changes
• Install this new folder as the xwiki application in your servlet container (may be by copying the folder to the servlet filesystem space or by packing it in a WAR file and deploying it in the container's administration interface)

At this point all is set, you can experience your old wiki data over the new XWiki core!

Troubleshooting

You can verify some basic settings of your XWiki install (on Tomcat, MySQL) using the Admin Tools application.