Setting up XWiki in Tomcat and MySQL

Sebastian — Thu, 10 Sep 2009 13:32:34 +0000

I recently set up a new XWiki 2.0 instance (with MySQL) for documentation purposes. Although some of the steps are already described in the XWiki manual I’ll document it here mainly because I keep forgetting things. Also step-by-step tutorials come in handy when you’re in a hurry.

Create the webapp directory

Since the configuration files have to be modified an exploded WAR has to be used. The webapp directory has to be created and the WAR will be extracted inside of it.

mkdir xwiki && cd xwiki
unzip ../xwiki.war
rm ../xwiki.war

Create and configure a database

Create a database including a dedicated database user. Open the file WEB-INF/hibernate.cfg.xml and uncomment the MySQL block. Modify the following properties:

connection.username
connection.password
connection.url

Important: Don’t forget to add the MySQL JDBC driver to your classpath (e.g. WEB-INF/lib).

Note: It is of course also possible to use a container managed DataSource via JNDI.

Configure Logfile

Since the security manager restricts file IO to the webapp directory the logging has to be reconfigured. To do so the log4.properties file has to be copied from xwiki-core-2.0-milestone-4.jar to the WEB-INF/classes directory. After this the property log4j.appender.file.File has to be modified to point to a writeable path.

Add the context file to Tomcat

Add a file name ${context}.xml to the /conf/Catalina/localhost” directory of $CATALINA_HOME (the Tomcat instance) and put the following content into it:

Eventually put in references to resources like DataSource’s etc.

Create the proxy settings in Apache HTTPD

You can use any proxy settings. I’m currently using a very simple setup:


  Allow from all


RewriteEngine On
RewriteRule ^/$ /xwiki/ [R=301,L]

ProxyPass        /      ajp://localhost:10709/
ProxyPassReverse /      ajp://localhost:10709/

Note: xwiki is the contextPath

Test the installation

Surf to http://www.yourdomain.com/. An empty XWiki page should be displayed. The first step should always be to register a user so the administration area is accessible. The default content can be imported by using the page /${contextPath}/bin/import/XWiki/XWikiPreferences.

I’ll probably blog more about XWiki and how to customize it in the future.