Saturday, November 22, 2008

A Personal Hosted Confluence Wiki for Free

I had been searching for a way to use Confluence as a personal wiki for me and my wife. I couldn't find a cheap hosted solution where I could just get an account for 2 people on an instance of Confluence maintained by someone else. I also didn't really want to pay a hosting company like Linode or Slicehost $20 a month for my own virtual machine on which I'd have to install and maintain Confluence myself.

Recently I heard about Morph Labs which describes themselves as a Platform as a Service (PaaS). They offer free hosting accounts that give you up to a 1GB database. I immediately got the idea to try running the personal edition of Confluence on this service. Eventually I got it working, but the process to get up and running was not at all easy. In fact, I struggled for serveral nights.

The rest of this post documents the process I went through. I hope it will help someone else avoid the many hours I spent learning how to work within Morph AppSpace with a third-party Java web application. Good luck, and if you have any tips or corrections, please comment and I'll update this post.

Start by signing up for a Morph AppSpace account with Morph Labs. Create a new subscription and setup a new database for that subscription. Be sure to choose Java, not the default Ruby on Rails, when setting up your subscription. Choose PostgreSQL for your database as this seems to work best with Confluence. Once your subscription is setup, download the Properties File, morph_deploy.properties, and Deployment Jar File, morph-deploy.jar, that can be found in the Java Tools for Morph AppSpace Deployment section.

Next, go get your free license for personal Confluence. It allows you to register 2 users. Hold on to that license text. You'll need to activate Confluence once it is installed. Then download the latest version of Confluence which is currently 2.9.2.

Unpack the file you downloaded somewhere on your computer. Inside, you should find an edit-webapp directory. Any files you need to modify should get copied into this directory. The contents of this directory get overlayed on top of the contents of the eventual Confluence WAR file that you're going to build, so make sure to adhere to the standard WAR directory structure. The whole purpose of the edit-webapp directory is to keep your local changes separate from the distribution so when it comes time to upgrade Confluence, you can just replace it and you'll know what you had to modify.

Copy confluence/WEB-INF/classes/confluence-init.properties to edit-webapp/WEB-INF/classes/confluence-init.properties.
Edit the copied confluence-init.properties, specifying the home dir as /var/java/ where APP_NAME is whatever name you chose as your subdomain at Morph. For example, if your domain is family-wiki.morphexchange.com, then your home directory path would be /var/java/family-wiki.

Copy confluence/WEB-INF/web.xml into edit-webapp/WEB-INF/web.xml.
Edit web.xml adding the jdbc datasource:

<resource-ref>
<description>Morphlabs Datasource</description>
<!-- any name will do for the res-ref-name -->
<res-ref-name>jdbc/morph-ds</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>


and the JavaMail session:

<resource-ref>
<description>Morphlabs Mail Session</description>
<!-- any name will do for the res-ref-name -->
<res-ref-name>mail/Session</res-ref-name>
<res-type>javax.mail.Session</res-type>
<res-auth>Container</res-auth>
</resource-ref>

I had to disable Confluence's JMX-based monitoring because of problems registering MBeans. This isn't a big deal since, for a personal instance of Confluence, I don't really have any need to monitor performance and gather statistics. This web page explained how to disable JMX. Download jmanageContext.xml from the URL shown on that page. Then, copy jmanageContext.xml into edit-webapp/WEB-INF/classes.

Remove mail.jar and activation.jar from confluence/WEB-INF/lib. Morph AppSpace already includes those in the Jetty server and having an extra copy in your WAR might cause class loader issues that would prevent JavaMail from working properly. This is the only change that you'd have to remember to do again if you were to ever download a new version of Confluence.

Now it is time to build the WAR file. Run ./build.sh which creates dist/confluence-2.9.2.war. If you need to make any changes to any files, be sure to run this build script again.

Download morph_deploy.properties and morph-deploy.jar from your subscription within the Morph Control Panel.

Run

java -Xmx512m -jar morph-deploy.jar --config morph_deploy.properties confluence-2.9.2/dist/confluence-2.9.2.war


Now, sit back, relax, and wait while your WAR is being uploaded and deployed on Morph AppSpace. This could take up to 15 minutes, so be patient.

Hit your-subscription-name.morphexchange.com and if all went well, you should see a Confluence installation web page. Following the Confluence installation wizard, entering your personal license text. Choose Custom Installation, External Database, Connect via a Datasource.
Enter java:comp/env/jdbc/morph-ds as the datasource.

Confluence takes a long time to setup the database, so the page may appear to hang. Each time I tried this (I had to try many times before figuring all this out), the page timed out. I don't know if something went wrong or Morph AppSpace just has a time limit on waiting for a page to render. Even though the page timed out and I saw some kind of "Proxy error" message, the database still seems to have been initialized properly, but the application wasn't able to recover. I had to go into the Morph Control Panel to restart the application. Once I did that, Confluence was up and running!

Coming soon to this post: Setting up a mail server and using Groovy and XML-RPC to perform a daily backup of your confluence data.