A multi-tenant setup (a.k.a "virtual mode", "multi-wiki" or "farm mode") allows you to have several wikis running on the same XWiki instance (i.e. in the same JVM).

Each wiki has its own database schema, thus allowing for a complete data separation between the different wikis in the same instance.

The main advantage of multi-tenancy is performance optimization. A single XWiki instance on a physical machine (thus a single Servlet Container) will perform much better than having several XWiki instances running on the same machine, which wouldn't scale. As an example known XWiki multi-tenant instances host several thousands hundreds to several thousands wikis on a single XWiki instance.

Requirements

The multi-tenancy feature currently works only on some databases:

• Databases known to work are: MySQL, Oracle and HSQLDB (starting with XWiki 4.3M1)
• PostgreSQL is currently not supported as the JDBC driver doesn't support setCatalog() for changing databases. That's because PostgreSQL connections are pointed to a specific database at connection time (see jira issue XWIKI-1960)
• Derby is currently not supported

In addition to having a supported database you'll also need:

• Choosing one instance of XWiki that has been installed on your network. The database name for this wiki should be xwiki. If you've still got to install the XWiki instance, please refer to the installation guide and install XWiki Enterprise first
• Admin privileges on this XWiki instance
• You need to be sure that the xwiki user used to create the main database has the correct permissions to be able to create other schemas since each subwiki will create a new database schema
• You need to be able to restart the java container (e.g. Tomcat or Jetty), or can have this restarted on demand.
  • The xwiki.cfg file will also have to be modified, so you will need to have write access to this file on the server

Set up

• Stop your XWiki instance, edit the WEB-INF/xwiki.cfg file, look for the xwiki.virtual property and set it to 1: xwiki.virtual=1
• Restart your XWiki instance
• Install the Wiki Manager Application

Starting with XWiki Enterprise 3.3 you can easily install the Wiki Manager Application using the Extension Manager by following these steps:

• Go to the administration page and click on "Add Extensions" under "Extension Manager"
• Click on "Advanced search" and enter the following information:
  • extension id: org.xwiki.platform:xwiki-platform-wiki-manager-ui
  • extension version: 4.3 (adapt to the version you wish to install; make it match the version of the XWiki Enterprise you're using)
• Click "Search"
• Click "Install"
• Click "Apply"
• Verify that the Wiki Manager extension is correctly installed by navigating to the WikiManager WebHome page which should now exist

You now have a multi-tenant installation and can proceed to use the Wiki Manager Application to create subwikis.