Getting Started with Confluence

In principle, I think wikis are great. I've worked on too many projects that have ended up with fifteen different copies of the "definitive" functional spec - all called something like Copy (2) of Rhubarb - Functional Spec - FINAL (3).doc - and no-one's really sure what's going on any more. The idea of a centralised documentation repository that everyone can read and anyone can edit, with a full history of who changed what, is appealing to say the least.

In practise - software specs are weird, awkward documents. Some concepts and ideas are best described as English prose. Some things are best described using screenshots, sketches, flow charts, sequence diagrams, class diagrams. Some things are best included by just pasting the code - 'cos you've already written it, and at the end of the day C# is just a really, really accurate description of an algorithmic solution to a particular problem.

I've played with MediaWiki, but found the installation process a bit daunting - we're a Microsoft shop; we have Windows, SQL Server and the like already up and running, and no real LAMP expertise to speak of...

I've set up Sharpforge, I've used the wiki engine built in to FogBugz. I've recently been playing with PerspectiveWiki (and I have to say, the v3 alpha is very, very nice indeed - but covered in warnings about how it's early alpha and you shouldn't use it for real).

One notable platform I haven't played with is Sharepoint... call me cynical, but when it's a Microsoft business platform that you can attend a five-day training course on, it's probably not quick & easy. We're not that big a team, we're all in one building, there's relatively little collaborative authoring going on, and Sharepoint just feels like total overkill for what we need.

So... this morning, I googled "project documentation wiki" or some such phrase, and stumbled across a commercial wiki engine called Confluence. Mike Coon wrote a post a while back called "It's the Installation, Stupid" - basically saying that nobody wants to install and configure a whole application stack just to try out a new package. He's absolutely right. Confluence uses J2EE, Tomcat, Apache and a whole raft of stuff I really don't want to install - but I didn't have to. I just ran setup.exe. Despite the fact it's based on J2EE, a platform I've never even touched - I had an evaluation up and running on one of our dev servers within half an hour. So far, I'm very impressed with it. The WYSIWYG editing is slick and intuitive, the admin and configuration is excellent, and if all goes well I'll be putting my money where my mouth is before the month is up :)

A couple of hours later, and it was up and running against our existing MS SQL Server database, authenticating via LDAP against our Active Directory server, and generally making the world a better place. One of these days I really have to get my head around LDAP a little better... when it works, it's absolutely wonderful ("no, no new password, just log in with your normal one") but my LDAP filters are too close to cargo-cult programming for comfort right now.

One major gotcha that was almost a showstopper until I found a way around it was getting Confluence to run on the default port 80 on the same server as our existing IIS intranet site, so here's what I did - and so far, it's working.

Confluence coexisting with IIS on a single server

Microsoft IIS, by default, grabs port 80 of every IP address on your server - and there's no way to switch this off using built-in Windows admin capabilities. This means if you want another web server running on the same box, you need to do a bit of tweaking to both IIS and the other server to make them coexist happily.

Confluence installs by default on port 8080, but for various reasons (mainly being I just don't like it), I wanted to get it running on port 80 - alongside the existing IIS sites.

There's extensive docs at the Confluence site about installing an ISAPI redirect so you can have www.mysite.com hosted by IIS and www.mysite.com/wiki invisibly proxy all requests to a JIRA or Confluence server - but that's not really what I was after.

First off, I bound a second IP address to the adapter of the server via Windows' TCP/IP controls - so my server was now running on 192.168.0.78 and 192.168.0.79

Next thing to do was to set up a DNS record (you could also spoof this using your /etc/hosts file) on our local server, so that http://wiki/ resolved to 192.168.0.79 - all our existing intranet addresses still resolve to the previous 192.168.0.78 address

Now for the fun part, which is lovingly documented in Microsoft Knowledge Base Article 813368. Basically, you need to download the Windows Server 2003 Support Tools, and use the included httpcfg.exe to modify the IIS metabase so that IIS will only listen on specified IP addresses. This done, it meant that IIS was still running fine on 192.168.0.78, and 192.168.0.79:80 was still available.

Next step was to modify the server.xml file that's shipped with Confluence. I have to admit this part was pretty much guesswork, but it made sense and it seems to have worked, so use it at your own risk.

By default, this file is installed at C:\Program Files\Atlassian Confluence\Application\conf\server.xml, and the clue is the <Connector /> section which refers to port 8080. By default, Confluence installs at http://localhost:8080/, so on a hunch I tried switching port="8080" to port="80" in this node, restarting Confluence, and as if by magic, everything started working.

<Server port="8005" shutdown="SHUTDOWN" debug="0">
    <Service name="Tomcat-Standalone">
        <Connector className="org.apache.coyote.tomcat4.CoyoteConnector" 
           port="80" 
           minProcessors="5"
           maxProcessors="75"
           enableLookups="false" 
           redirectPort="8444" 
           acceptCount="10" 
           debug="0" 
           connectionTimeout="20000"
           useURIValidationHack="false" 
           URIEncoding="UTF-8"
        />