Upgrading Jira is a pleasant activity, but it can also surprise you. Atlassian documentation includes a framework upgrade plan, but it`s worth preparing your own checklist of activities that must be performed before and after the upgrade. In today’s post, I will share with you my list, specific for the environment I work in.

You can read the official documentation here, it is also worth reading the upgrade checklist. I will present a procedure based on my own experience with the upgrade. It was performed on the Linux environment, I hope it will help you. Don`t hesitate to share your thoughts in a comment section or at contact [at] jiraforthepeople.com.

Preparation

• set the Annoucement Banner (https://your-jira-instance/secure/admin/EditAnnouncementBanner!default.jspa) and inform employees via the corporate messenger
  • the banner should be placed in a reasonable advance
• read the release notes and the upgrade notes for the target version of Jira
  • e.g. for a version 8.12: release notes, upgrade notes
• preparing release notes for users
• making a backup
  • xml: https://your-jira-instance/secure/admin/XmlBackup!default.jspa
  • database backup
• disable cron jobs running on the server
• mute monitoring
  • Jira will be temporarily unavailable, if your company is monitored for its operation, mute it for this time
• download appropriate Jira version
• perform pre upgrade checks using the native tool in Jira: https://your-jira-instance/plugins/servlet/troubleshooting/pre-upgrade/
  • the tool checks, among others whether the application licenses allow you to upgrade to a specific version
• perform Jira update check https://your-jira-instance/plugins/servlet/upm?source=side_nav_manage_addons
  • check if the add-ons will be compatible with the target version of Jira
  • some of them can be updated immediately, others only after Jira upgrade
• make sure that your licenses allow you to upgrade add-ons to the required versions
• read the release and upgrade notes for add-ons
  • check if the new version of the add-on doesn`t become paid or doesn`t contain breaking changes
• disable incompatible add-ons
• upgrade add-ons
  • depending on your needs, you can upgrade to the latest version of the add-on or another version you need
  • with each upgrade, I always have the server log tracking enabled in the second window:

    tail -f /opt/jira-home/log/atlassian-jira.log

Installation

• grant permission to run the installer

  chmod + x ./atlassian-jira-software-8.12.3-x64.bin

• open the screen application
  • installation in the screen application, which will protect us against the consequences of a sudden disconnection from the server

    screen -S upgrade_jira

• I always open two additional windows for following the logs

  tail -f /opt/jira-home/log/atlassian-jira.log
  tail -f /opt/jira-home/log/atlassian-jira.log | grep ERROR

• launch the installer
• copy custom changes aside
  • the installer will give you a list of files that have been modified from the original Jira configuration, you should copy them on the side

After installation

• transfer custom changes
  • I use the vimdiff tool to compare files, e.g.

    vimdiff old_server.xml new_server.xml

• in case of the need to transfer trusted jira certificates, I recommend my original script. I`ve described its action in a separate post
• disable automatic reindex
  • in the jira-config.properties file, set: upgrade.reindex.allowed = false
• remove the content of /opt/jira-home/plugins/.osgi-plugins/
  • after upgrading add-ons this catalog may contain outdated data, it will be restored according to the latest versions
• turn on JIRA instance
• upgrade Jira Service Desk to the appropriate version
  • https://your-jira-instance/plugins/servlet/applications/versions-licenses
• upgrade and turn on other add-ons
• verify Jira health checks
  • https://your-jira-instance/plugins/servlet/troubleshooting/view/
• verify Application Links
  • https://your-jira-instance/plugins/servlet/applinks/listApplicationLinks
• verify the synchronization of User Dictionaries
  • https://your-jira-instance/plugins/servlet/embedded-crowd/directories/list
• perform basic Jira operations (create issue, delete issue, comment, worklog)
• perform a full Jira reindex: https://your-jira-instance/secure/admin/IndexAdmin.jspa
  • note that during the full reindex Jira will be unavailable
• enable cron jobs on the server
• turn on monitoring
• take off the Announcement Banner
• inform users about completing the upgrade, provide Release Notes