This setup has not been maintained by anyone over the years and is currently not working. We're keeping it in case someone wants to spend time to make it work again.

This tutorial shows how to use IntelliJ Idea to setup a complete development environment for XWiki where you can develop, debug and test XWiki features without leaving the IDE.

This should work both with the Ultimate and the Community editions, that you can download here

Step1: Clone and setup the xwiki-debug-idea project

  • Use git to clone the xwiki-debug-idea repository
  • In the same directory clone the xwiki-platform
  • Go to the xwiki-debug-idea project and run the script.
    • The script should automatically detect the xwiki-platform sources and create the needed links.
    • If you want to use an xwiki-platform located elsewhere, you can tell the script to do so.
  • If everything goes fine you should have something like that:
    $ ls -l
    total 24
    drwxr-xr-x  6 fm fm 4096 Oct 26 17:58 xwiki-debug-idea
    drwxr-xr-x  5 fm fm 4096 Oct 26 11:14 xwiki-platform

    $ cd xwiki-debug-idea

    xwiki-debug-idea$ ./
    XWiki platform sources found at /...somewhere.../xwiki-platform
    Do you want to use this? (y/n) y

    Creating symbolic links...

    xwiki-debug-idea$ tree
    ??? pom.xml
    ??? src
    ?   ??? main
    ?       ??? resources
    ?       ?   ??? logback.xml -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-web/src/main/resources/logback.xml
    ?       ??? webapp
    ?           ??? redirect -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-web/src/main/webapp/redirect
    ?           ??? resources -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-web/src/main/webapp/resources
    ?           ??? skins
    ?           ?   ??? colibri -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-colibri/src/main/resources/colibri
    ?           ?   ??? toucan -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-toucan/src/main/resources/toucan
    ?           ??? templates -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-web/src/main/webapp/templates
    ?           ??? WEB-INF
    ?               ??? cache -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-web/src/main/webapp/WEB-INF/cache
    ?               ??? fonts -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-web/src/main/webapp/WEB-INF/fonts
    ?               ??? hibernate.derby.cfg.xml.default
    ?               ??? hibernate.hsqldb.cfg.xml.default
    ?               ??? hibernate.mysql.cfg.xml.default
    ?               ??? hibernate.postgre.cfg.xml.default
    ?               ??? observation -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-web/src/main/webapp/WEB-INF/observation
    ?               ??? portlet.xml -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-web/src/main/webapp/WEB-INF/portlet.xml
    ?               ??? struts-config.xml -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-web/src/main/webapp/WEB-INF/struts-config.xml
    ?               ??? sun-web.xml -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-web/src/main/webapp/WEB-INF/sun-web.xml
    ?               ???
    ?               ??? web.xml -> /...somewhere.../xwiki-platform/xwiki-platform-core/xwiki-platform-web/src/main/webapp/WEB-INF/web.xml
    ?               ??? xwiki.cfg.default
    ?               ???
  • Copy the one of the default hibernate.{derby,hsqldb,mysqls,postgre}.cfg.xml.default to hibernate.cfg.xml, depending on which database you want to use.
  • Copy and review xwiki.cfg.default to xwiki.cfg
  • Copy and review to

Now you should have a completely setup project, ready to be imported in IntelliJ Idea

Step2: Importing into IntelliJ Idea

  • Start IntelliJ Idea
  • Choose "Open project" from the welcome screen and chose the pom.xml of the xwiki-debug-idea project.


  • Once dependency resolution is over, you can open the project structure dialog by choosing File -> Project structure... from the menu. You should see, in the dependencies tab all the Maven dependencies needed to have the project run.


  • You can now create a run configuration for starting a Tomcat server and deploy XWiki
    • Open the "Edit configuration..." dialog by choosing Run -> Edit configurations...
    • Expand the "Defaults" node, select "Tomcat" and then click on the "+" button on the right. (Note: you might need to have some plugins installed in order to have Tomcat available)
    • Fill the relevant fields in the dialog:
      • Put a meaningful name in the Name field (e.g. XWiki)
      • Put -XX:MaxPermSize=256m in the VM Options field
      • Check the Build artifact checkbox


  • Open the "Deployment tab", click on the "+" button on the right and choose xwiki-debug-idea:war exploded


  • You can set the application context on the right. By default it's set to /. You might want to change this to /xwiki
  • Everything is setup for running XWiki. You can start it by clicking on the Run button or the Run -> Run... menu item. Once run a browser should popup to the home page of your XWiki.

Step3: Importing xwiki-platform projects for hacking XWiki

In the previous step you prepared everything for deploying and run XWiki. In doing so you are using the precompiled JARs downloaded from the Maven repositories. In this step you will import source code project so that you can modify XWiki and run a version containing your modifications (for testing and debugging)

  • Open the Project structure dialog using the File -> Project structure... menu item.
    • Click on the "+" button on the top and choose "Module"


  • Fill in the field in the "Add module dialog"
    • Navigate to the xwiki-platform directory that contains the module that you want to work on (e.g. xwiki-platform-rest-server)
    • Check the "Import maven project automatically"
    • Click "Next" several times to complete the import.


  • You will see the imported module appear in the project navigator on the left, in the main window
  • Select all the projects in the tree, click with the right button on one of them and select Maven -> Reimport


  • If everything went well, you should see in the project structure, in the dependencies tab that the Maven dependencies corresponding to the modules that you have imported in your project are now linked to the projects (they have a different icon). This means that the deployment will use the code you are actually developing in your IDE (and not the one coming from the JARs in your Maven repository)


Step3: Hack XWiki!

You're done. You can now start writing and fixing code and test it from within Idea.

You can also start XWiki in debug mode (Run -> Debug...) and set breakpoints as you usually do.

Basically you can use Idea as you usually do and make it take care of handling all the complex dependencies behind XWiki.

Happy hacking.

Created by Admin on 2012/10/26 18:20

Get Connected