Upgrading to Confluence 4

Confluence 4 was an update we were really excited about because of the fantastic new editor (see our previous blog post on the matter). So naturally, we wanted to upgrade as quickly as possible...

But upgrading such a mission critical system is never that easy, especially when your environment is under constant strain due to heavy use and when there are lots of third party plugins on there. We were rather relieved to note that Atlassian managed to make the process as easy and painless as possible.

The new installer

The most significant improvement to the upgrade process is the new installer. Whether you're creating a brand new installation or upgrading an existing one, there is now one tool that does both. When upgrading, it first makes a backup of the existing installation and home directory and then installs the new software. It even detects your existing custom configurations. The installer will automatically upgrade the following:

• The TCP port values in the server.xml file (all other changes to the server.xml must be copied manually).
• Custom values in the confluence-init.properties (confluence.home property) and setenv.sh / setenv.bat files (JAVA_OPTS parameters).

Currently, only changes made in files under the confluence subdirectory of your existing installation are detected and reported. Fortunately we've been told this will be fixed in a future release. Then ALL changes in ALL files under the installation directory will be detected.

Changes since Confluence 3.5

 The default port has changed!

If you cannot reach Confluence at all after the upgrade, try accessing Confluence on port 8090. Yes, Atlassian has changed the default port of Confluence! In theory though, the new installer should detect if the existing installation uses a different port and should update the server.xml file accordingly.

New tomcat, new rules

In Confluence 4 standalone, the version of the embedded Tomcat server has been upgraded. And this new version of Tomcat brings some changes. For example, the JNDI naming scheme. Previously when you added a JNDI resource under the Confluence context in the server.xml, it was added to the JNDI tree under comp/env. With the new version of Tomcat, the resources are added under the name of the context, namely: comp/env/confluence. This is particularly annoying if you had previously configured your Confluence datasource there. Of course you can change the new JNDI name in all the config files, but luckily there is an easier solution. Since Confluence is the only application running on this instance of Tomcat it is easier just to bind the datasource name under the global comp/env context. To do this:

1. Create a new file called context.xml in the same directory as the server.xml.
2. Move your resources configurations from the server.xml to the context.xml.
3. Restart Confluence.

Hey, who touched my content!

After the upgrade you'll probably notice that all your content has been updated. During the upgrade Confluence converts all content to the new editor format. Therefore a "Migrated to Confluence 4.0" mention will show up on all pages and activity streams.

Wow, after login every page gives a 404!

Ah! You're a RefinedWiki user. Upgrade the RefinedWiki plugin through the Universal Plugin Manager and do not forget to run the upgrade procedure in the RefinedWiki admin section itself (press the big shinny button!). After the new version of the plugin is installed, RefinedWiki needs to upgrade all of your content as well. Until RefinedWiki has upgraded your content, all pages will give a 404 (not found) error.

Upgrading your plugins

Once the new version of Confluence is running and the log files don't reveal any show-stopping errors, the manual part of the upgrade starts!

Since there is no official way to automatically install or upgrade plugins on a running Confluence instance, the process has to be done by hand. Here is how I do it:

1. Write down a list of all the plugins that you need in your Confluence instance. Include the version you currently use (do some spring cleaning if you can!).
2. Now go to http://plugins.atlassian.com and lookup your plugins one by one. Look at the compatibility table if there is a version of the plugin that supports the new version of Confluence (We're hoping this process will get easier soon!).
3. Upgrade all plugins that need upgrading in your test instance and test if your content to see if it still works.
4. If there's a problem, try and find out if this is due to a plugin that does not yet support the new version of Confluence.
5. If this unsupported plugin is not blocking the upgrade, simply disable it.

If you don't have too many third party plugins and aren't trying to script it all out, you should be done within a day, that's including proper documentation and all of the up-front investigation. Remember to always check the upgrade guide and the release notes, including the release notes of all the versions you might have skipped.

Oh and don't forget: TEST FIRST!!! If you didn't know, your standalone Confluence license includes a developer license so that you can deploy it on a staging environment. As far as we're concerned it's really a must have in order to test third party plugins, our own custom ones, user macros, upgrades and more...

Happy upgrading!

Need some expert advice about Atlassian products? Check out our Atlassian Experts page to find out what we could do for you…