On Mar 15, 2017

Your 7 Step Guide to Pain-Free JIRA and Confluence Upgrades

So you’ve been tasked with upgrading your JIRA and Confluence instances? Great! Sounds like someone in your organization read about all the cool new features in the upgraded applications, and realized that production deployment is behind.

Chances are you’re feeling a wide range of emotions right now, and they’re not exactly positive. Utter and all-consuming terror comes to mind, intense dread, and a general feeling of “why me?

Sound familiar? Then this post is for you.

SysAdmin ≠ Atlassian Upgrades Expert

I doubt this is news to you. Unless you’re a self-identified Atlassian expert (unlikely for SysAdmins tasked with managing a wide array of applications) you’re probably not overly-excited at the thought of a drawn out upgrade process that could potentially leave your organization with non-functioning mission-critical applications. Chances are you have little (or no) idea how JIRA and Confluence function on the back-end. Relying solely on Atlassian’s documentation may not do much to overcome inevitable feelings of overwhelm or sometimes even panic(!).

I get it, because I’ve been there. Before joining Equip, I was a SysAdmin (read: full-time generalist). I’ve learned that it takes dedicated focus to keep up with the rapid changes made in the Atlassian tools across releases. Official documentation and even ‘secret steps’ often aren’t enough to ensure that applications like Confluence and JIRA are upgraded correctly on the first attempt. Based on my experience as an Atlassian support specialist (leading dozens of upgrades across many environments), I’ve compiled some of my hard-learned best practices into the following 7 step guide to help take the mystery out of JIRA and Confluence upgrades.

Please keep in mind the steps below are meant to serve as guide-posts, not as a complete and thorough documentation. No two upgrades are ever the same, and depending on the degree of complexity within your own system you may consider reaching out to a certified Atlassian Solution Partner for assistance and support.

In the meantime, let’s review the 7 steps.

Step 1: Set up your test environment

First thing’s first – you have a development or staging environment set up for JIRA and Confluence, right? If not, it’s imperative that you tackle this right away. Ideally you’re hosting the applications virtually and are able to clone the virtual guests so that you have an exact mirror of production. If not, a simple backup and restore to a clean install will work, too. The goal is to have a place where you can test this upgrade, and make sure that everything functions as expected. And if you break something, it’s no big deal.

Step 2: Review your add-ons

The next thing you want to tackle are your add-ons and their compatibility with the latest version of the applications. This is an ideal time to perform an audit, researching whether each installed add-on is actually being utilized. I can’t tell you how many instances I’ve worked in where dozens of add-ons were installed, but very few (if any), were in-use.

Thankfully, both JIRA and Confluence have a super handy tool built in to check compatibility of add-ons against the latest version of the applications. It’s located within the ‘Manage Add-ons’ administration page within each application, and will tell you if the current installed version of an add-on is compatible, or if it needs to be upgraded.

Step 3: Back it up

Alright, so you’ve completed the add-on compatibility check, and you have made the necessary upgrades for compatibility. Now you can move on to the real meat and potatoes of the application upgrade process.

Though, you made backups first, right? XML backups using the built-in backup tools, database dumps, and archives of the application data directory? No? Well do that first!

During the upgrade process the applications will ask if you’d like them to create backups for you. There’s no reason not to do this, but keep in mind that this could potentially consume a lot of time and disk space depending on how large your instances are.

Step 4: Run the installer

Here’s a fun fact: all of the Atlassian applications have 3 pieces as part of their installation:

  1. The application itself (usually installed in a single directory)
  2. The application data directory (which contains attachments, system configuration data, etc.)
  3. The database that the applications connect to (which holds all of the user created data)

This is a simplified overview, but it should give you an idea of how everything’s laid out. Pretty simple, right?

Once you’ve made your backups you can run the installer by selecting ‘Upgrade.’ Chances are you’re being told that there are some modified files in the installation directory. Don’t worry! That’s totally expected in most environments. The vast majority of the time, the modifications flagged were made to the server configuration file to define a proxy. It’s very common to run the applications behind Apache2 or NGINX, which handles all of the SSL and certificate traffic, and passes it to the application.

Simply make a copy of the files that have been flagged by the installer so you can recreate the modifications after the upgrade succeeds (since they will be overwritten them with the unmodified files from Atlassian).

Okay, now you’re done, right? Almost!

Step 5: Review your add-ons… again

After the installer succeeds and the applications restart, you should be able to log in to your newly upgraded JIRA and Confluence applications. Don’t worry if it takes a while for them to restart. There are a number of upgrades to the database that happen in the background. Worst case, check the logs located in the application data directory to see what it’s hanging on.

The next thing you want to do is (surprise, surprise) check the add-ons. If you’re coming from a very old version of the application, there’s a good chance there will be add-ons that need an additional upgrade to be compatible with the new version. You’ll easily be able to see which need it, as they’ll be marked with a big, angry ‘INCOMPATIBLE’ label on the add-on management screen. Go ahead and upgrade those and you should be fine.

Step 6: User testing

Be sure to bring users in to test the new environment.

User testing is vital at this point.  Gathering as many people as you can to check to make sure things are working as expected will go a long way towards making sure that there are as few pain points as possible once you upgrade your production environment. Good testing takes time, so plan on 1-2 weeks for this step (this will vary depending on the size of your instance).

If you can, recruit your testing team from folks that work in the software the most, as they’ll be the most sensitive to anything that doesn’t work as it did prior to the upgrade.

Step 7: Do it all again!

You completed steps 1-6 in your development/staging environment first, right? Good.

Now that you’ve moved through every step of the process from the safety of your test environment (and have a clear understanding of the hiccups and roadblocks that lie ahead), it’s time to go do the real thing. Be sure to take comprehensive notes during your test upgrade as documentation will be very helpful during the production upgrade, and can work wonders to ensure a smooth and efficient upgrade in real-time.

Phew! That doesn’t sound so bad, right? You’ll be the hero of the hour – the (wo)man that made it happen!

I hope this resource helped to alleviate a bit of the panic you’re feeling after being tasked with such an undertaking. Keep in mind that these 7 steps provide a very simplified overview of how to upgrade the Atlassian applications. You’ll need to take more aspects into consideration when using external user directories, clustering, extremely customized versions of the applications, etc. In cases like these (or for anyone still feeling daunted by the task of even a simple upgrade), it may be beneficial to contact an Atlassian Solution Partner like Equip from the onset of the project so they may help you map out the full scope of what’s required for a successful upgrade and even assist with execution.


Cody Agenten is an Atlassian Engineer with Equip, an Atlassian Platinum Solution Partner dedicated to serving customers with robust expertise and the right resources to navigate their Atlassian journey. Cody embarked on his journey with Equip in the early Spring of 2016, after successfully escaping nearly a decade of Systems Administration. As an Engineer with Equip, Cody provides expertise and support to customers on a daily basis, partnering with teams to ensure their Atlassian tools work for them (not the other way around).

You can connect with Cody on LinkedIn: https://www.linkedin.com/in/codyagenten/

Zorbix Themes