Published Tibor Hegyi | 2016-02-08

A customer of ours (Morphologic Localisation Ltd), for whom we developed a JIRA addon many years ago to integrate JIRA with their legacy systems, has recently contacted us to help them upgrade their Confluence instance to the latest version. The first question that everyone would have asked was what version of Confluence they had.

The answer was quite shocking: Confluence 2.9. we got excited and afraid at the same time. Last time we saw a similarly old Confluence site was back in 2008 when we installed the first Confluence instance at SonyMusic in Munich.

Our customer was a kind we can wish for any consultant. It was very easy to communicate and to work with them. We did not even had to meet personally, we talked over the phone, used chat, but the trust was established the very first minute. We proposed T&M, they accepted it because they understood the complexity of the process and our arguments. So the job was doomed a happy ending.

A Vital Dinosaur

When we first entered the Confluence site, we realized that the customer was a heavy user, they built a huge documentation and knowledge base system. Yet the good old Confluence 2.9 was so fast we could not believe my eyes. All pages opened in less than a second, they seemed like static HTML pages. All of this felt very abnormal in today's, modern, resource intensive fatty systems including JIRA and Confluence.

Interestingly Confluence Download Archive still lists almost all versions back to 1.0.3 released in 2004(!). It is very impressive to see how old Confluence is and what a tremendous amount of work and functionality had been incorporated into this product. The below chart shows how the size of Confluence Standalone distribution changed over time. Yes, it started as a 19MB(!) package in 2004. While version 5.9.4 is almost 440MB(!). A 23 times bigger giant.

It as also very astonishing to see how Atlassian imagined the UI back in 2009 when Confluence 2.9 was released. It was so simple, pure, oldish, lack of any eye-candy features. Still we remembered how impressed we were in 2008/9 about the beauty of Confluence UI Atlassian had developed at that time.

We still remembered the old Rich text/wiki markup editor with many-many bugs, limitations, annoying behaviours. Luckily it had passed away and Atlassian developed an uncomparably better editor we can enjoy today.

we wanted to install Confluence 1.0.3 out of pure fun too to see the very first screens, we have found an old evaluation license from 2005 in my MAC account which was accepted by Confluence 1.0.3. However, after configuring database connections, Hibernate threw a bunch of exceptions and Confluence could not complete database initialization. Probably java 1.7 was not good for that. This is how Confluence 1.03 install screens looked like.

Even Confluence 2.9 looked quite funny comparing to what we know Confluence like:

The Upgrade Process

It was obvious that the upgrade cannot be done in a one huge jump from 2.9 to 5.9.4, but rather in three stages as advised by the Confluence Update Documentation.

Our customer wanted not only to upgrade Confluence, but also to move it to totally new server environment replacing the old mysql database with Postgres too. Therefore we have not followed the documentation word-by-word.

There were two aspects that made the upgrade process less complex:

  • The customer did not have any thirdparty addons deployed in their old Confluence instance
  • They could stop using Confluence for upgrade process. This meant we did not have to do a test upgrade first but updated their production system immediately. As we moved to a new server, the old system could remain intact.

Upgrade from 2.9 to 3.5.13

First, we created an XML backup from the old Confluence 2.9.

We selected the latest minor build of 3.5.13 that was downloadable. We manually installed it in the new server environment using an empty Postgresql database.

Once it was running we simply performed a Restore from XML backup. Confluence 3.5.13 could upgrade the content easily without any problems.

Upgrade from 3.5.13 to 5.0.3

The above steps were repeated:

  • XML export from 3.5.13
  • Install Confluence 5.0.3 manually (not with the installer) an empty database
  • Import the XML backup and let Confluence perform the upgrade

It completed again without any problems.

We felt we were close to a successful upgrade.

Upgrade from 5.0.3 to 5.9.4

Again the well known steps:

  • XML export
  • Install 5.9.4 this time using the installer as it was supposed to be the final instance, empty database
  • Import the XML backup and let Confluence perform the upgrade

All went fine. However all content was imported without attachments.

Upgrading Attachments

Confluence 2.9 already stored attachments in the Confluence home directory. However the structure of the attachment directories was totally different from what Confluence 3.5.13 required. In the stage of 2.9 to 3.5.13 the attachments were not converted to the new directory structure.

Luckily this is something that might have happened to others as well. Most probably this was the reason Atlassian added a tricky feature to restructure attachments from the old format to the new, calling: CONFLUENCE_BASE_URL/admin/restructureattachments.jsp

It restructured the directories in a second. Later when I upgraded 3.5.13 to 5.0.3 and then 5.0.3 to 5.9.4, we simply copied the new directory structure over and all was fine. Well, almost. Space logos and user avatars were missing.

Googling the internet for an hour did not yield any useful information. Browsing again and again the old Confluence home directory, we noticed there was a folder called "nonspaced" in the attachment folder, which proved to be relief. After copying it to the server, space logos appeared properly.

However, we could not manage to restore user avatars. We were searching, googling a lot but could not find an answer for the question where Confluence 2.9 stored user avatars.

If you know where user avatars were stored in old Confluence versions, please let us know.

Post Upgrade Tasks

After completing the upgrades, some manual reconfiguration had to be done:

  • Confluence Mail Archiving system addon was disabled somehow during the upgrade, hence all mail accounts that used to work in Confluence 2.9 had to be reconfigured after enabling the addon.
  • I had to assignee a lot more memory to Confluence. 2.9 was happily running on 384MB, 5.9.4 got 1.5GB.
  • Confluence base url had to be reset to the live url


There are a few consequences to draw from the above experience:

  • Even the very old Confluence sites may be upgraded to the latest version in a few hours
  • Lack of addons made it much simpler
  • Space logos and user avatars need special attention.

Despite the powerful server environment, Confluence 5.9.4 is far from the performance of Confluence 2.9. Yet, none would like to work with the old version. Confluence has emerged to be one of the best tools for collaboration, knowledge management. With its plenty of features, nice user interface, integration capabilities make it a lot more powerful product that is fun to work with.

We also recommend these articles: