How to run Confluence and Ency on IBM Websphere

Although IBM Websphere has not been supported as an application server since Atlassian Confluence 3.3, it has been possible to use it for some time. Not so long ago, one of our customers needed us to run a relatively new version of Confluence on Websphere (the latest version is This article is about overcoming the problems which we had to deal with. Links to online resources, which helped us and were not easy to find, are provided.


Confluence version

Using the latest version of Confluence (which was 5.5.7 at that time) didn't work. In our case, installing the Confluence WAR on Websphere caused the total meltdown of the Websphere web server - Websphere couldn't be controlled via the web. We managed to uninstall the application manually using wsadmin script from the console. Because of the frequent use of wsadmin for rapid installation, uninstallation and debugging, we used a script which adds cursor arrow support.




We had no idea where the problem lay or what to focus on, so Instead of trying to look for possible causes and solutions, we instead decided to try out different versions of Confluence. The most recent version which worked best, meaning the installation of WAR didn't mess anything up, was Confluence 5.4.4. We settled on this version and set about fixing it.

Since our customer uses Oracle Database and there is a long-known issue that concerns using a datasource with this database, we were aware of possible problems. We concluded that the issue is still present and used the proposed workaround.



OSGi hell

We reached the point where Confluence could be installed and we could even go through the web wizard. However, we soon discovered that some actions worked (like creating spaces, commenting and editing pages) while others didn't (there was no create button). It wasn't hard to find the cause for this; some plugins failed to start because of missing OSGi dependencies. The most useful OSGi browser for debugging was the one included in Confluence.


We worked out which modules had problems and found that Websphere was exporting standard J2EE modules without their versions (which was set to The next step was go through all the Confluence JARs and remove the required version from their mainfests. The problematic packages were: javax.servlet, javax.servlet.http, javax.servlet.jsp and javax.servlet.jsp.tagext. A few modules started to work; we were on the right track.

Confluence wasn't working properly because it doesn't see classes its version doesn't require it to see and Websphere was exporting them. We found people were having similar problems on Tomcat 7 with older versions of Confluence and were able to fix the issue by modifying Felix's config file. Namely, these packages are needed to be added: javax.servlet.jsp and javax.servlet.jsp.tagext.


It would have been too easy if that had given us a working instance, wouldn't it? Another problem was with packages which Confluence still couldn't see and reported NoClassDefFoundError. The solution was to add a parameter to JVM for the classloader. These packages have to be delegated: javax.servlet, javax.servlet.*, sun.*, com.sun.* and org.w3c.dom.*.


And one last thing. There was a problem with the classloader and xml libraries. For some time we thought that it was caused by xerces but later we found that one Confluence JAR (atlassian-bundled-plugins/confluence-license-rest-5.4.4.jar) contained its own copy of xml-apis. Since it was already provided by the Websphere, it was sufficient to remove it.

This concludes the process of fixes which are necessary for getting Confluence working. Since all these fixes are made prior to building WAR, the fixed archive can be distributed easily to several servers at once.


Making Encyclopaedia run

There were three changes we needed to make in our plugin, which we call Ency.

First, our plugin was developed for a more recent version of Confluence (5.6.6) and we therefore needed to fix a few places where we used the newer API. Luckily we managed to fix it everywhere in a way that it's still compatible with the newer version and therefore won't be stuck with two different versions of source code.

Our plugin is heavily dependent on datasources; it may use tens of them as it needs to connect to various source databases. Websphere seems to put jdbc datasources into a different place in its exported Context. The difference is between java:comp/env/jdbc/data-source and just jdbc/data-source. It may be configurable but we chose to generalize our findDataSource method to make it less location dependent by adding several fallbacks.

The last issue was that Websphere refused to use a public cryptographic key to decrypt a message encypted by a corresponding private key. This security measure can be turned off by a JVM parameter "".



We've proved that it's possible to run a relatively new version of Confluence (5.4.4 in particular) on top of IBM Websphere. There is one issue we are aware of; Confluence becomes about 3-4 times slower. It's mainly noticeable when a loader creates a vast number of pages and the Lucene has to index them all.