This is a guide how to upgrade your JIRA server. JIRA has security support for two years from a point release. (In this document, a "point release" refers to the minor release.) This information is based on the official Atlassian documentation.

I want to point out that this is for personal reference, and it's based on my own (very idiosyncratic) configuration, so take the specifics with a grain of salt. The general procedure should be simple to follow.

Step 0: Locate relevant details.

You might need to know the administrator password to JIRA for what follows. Make a note of your license key, it's in Configure > Applications.

Step 1: Find out what version of JIRA you are using.

You can see this at the bottom of the JIRA page once you have logged in. In my case it reads:

Atlassian JIRA Project Management Software (v7.7.0#77001-sha1:3be3151)

Step 2: Back up the database.

Dump the database using postgres tools.

pg_dump -F c -Z 9 jira > jira.backup

Step 3: Back up the files.

The easiest method here is just to tar up your entire JIRA directory and dump it somewhere, if it's feasible. I just run this:

root@jiraserver # tar -cf ~/jira-old.tar /jira

My directory clocked in at a nifty 1.3GB of data.

Step 4: Find the archive for the new version.

You can find this at https://www.atlassian.com/software/jira/update.

Click View all versions and it will open a lightbox.

This dialogue lets you select the exact version you want. Click the dropdown at the bottom left and switch to 7 -- this is your choice of major version.

Now it will list the minor versions available. Select 7.7.

Now it will list the patch versions. Select 7.7.4, the highest one available. Click Choose this version.

You'll see several options for the format of the download. The best version for upgrading is one of the archives, which are installed using the 'manual' process.

So you should choose TAR.GZ Archive, and click Get started.

Agree to the license agreement.

This will provide you with a file named atlassian-jira-software-7.7.4.tar.gz, save this file.

Step 5: Stop JIRA

JIRA should be managed with systemd at the moment, so this should be as simple as systemctl stop jira.

Step 6: Determine how to replace files

In my configuration, JIRA houses its static files under /jira/install. So that's the directory you should be replacing. When you extract the tar, you'll get a new subdirectory: atlassian-jira-software-7.7.4-standalone/. So in my example, you'd be doing the following:

root@myserver # cd /jira
root@myserver # tar -xzf ~/atlassian-jira-software-7.7.4.tar.gz
root@myserver # mv install install.old
root@myserver # mv atlassian-jira-software-7.7.4-standalone install

Step 7: Apply Puppet manifests

I assume that you control the configuration of server.xml and other JIRA configuration files in Puppet. You'll want to reapply these. The way that you do this varies depending on your setup. In a good world, you can just run puppet agent --test. I use a masterless setup, so my command looks something more like this:

root@myserver # cd ~/mypuppetrepo
root@myserver # /opt/puppetlabs/bin/puppet apply --verbose --no-splay --modulepath ./modules masterless/myserver.pp

Once the changes are applied, you have to make one more change.

Step 8: Apply JVM-specific tweak

Add this line to the top of /jira/install/bin/catalina.sh:

JRE_HOME=/jira/jvm/jdk1.8.0_162

You're probably wondering, why do this? Actually, the best option is to set this in the environment. Or, an even better option would be to set it in the systemd service file, something akin to:

[Service]
...
Environment=JAVA_HOME=/jira/jvm/jdk1.8.0_162

This could more easily be puppeted.

Step 9: Fix permissions on the writable directory

chown jira:jira /jira/install/logs
chmod 0755 /jira/install/logs

chown jira:jira /jira/install/work
chmod 0755 /jira/install/work

This could (and should) be puppeted. In addition, these directories should probably be configured to be outside of the /jira/install tree, in a sort of /var-like arrangement.

Step 10: Fix the references to the JIRA home directory

Modify /jira/install/atlassian-jira/WEB-INF/classes/jira-application.properties

It should contain:

jira.home=/jira/data

This can also be specified in the systemd service file, although it isn't at present.

Step 11: Start JIRA

And monitor /jira/install/logs/catalina.out file. If something goes wrong, bear in mind that you might have to manually stop and restart JIRA using the scripts under /jira/install/bin, because it will try to hang around even if it wasn't able to start correctly, which can confuse you.