JIRA Upgrade HandbookBest practices for upgrading JIRA safely and efficiently

Complexity Made Simple

Doug Bass Jobin Kuruvilla

Authors  Doug  Bass  Senior  Vice  President  of  Engineering  

Jobin  Kuruvilla  Senior  Managing  Consultant  

JIRA Upgrade HandbookBest practices for upgrading JIRA safely and efficiently

Complexity Made Simple

Thousands of software development and support teams use Atlassian’s JIRA project and issue tracking software to capture and organize issues, prioritize and take action on what’s important, and stay up-to-date with their teams’ activities.

If JIRA is mission-critical to your organization, you’ll want to use the latest version, to take full advantage of its power.

Because JIRA is a powerful product, upgrading it requires some expertise.

We’re going to share some of the best practices and checklists we’ve used in hundreds of installations, to safely and effectively upgrade JIRA with rapid success and happy developers!

JIRA Upgrade Handbook © Go2Group, www.go2group.com Page 1

Determine  Your  Version  

§  Which  version?  

§  What  to  watch  for  

|    Go2Group  .com  4  

Decide your upgradeMost of the time, you will want to upgrade to the latest revision. But you may want to avoid new, major “.00” versions. Let others find the early bugs!

You also may want to delay if there are key features the latest revision does not include. Watch out for:

• Features that are not available yet

• Plugins that cannot be upgraded yet or broken inte-grations

• Risks and known issues

For example, if you have the Go2Group JaM plugin installed for JIRA to HP QC integration and it is a key part of the integration, you might not want to upgrade until the plugin is compatible with the version of JIRA you need.

You may want to wait if you know a feature is coming soon. For example, we had a client that didn’t really like the “Auto Watch” feature and needed the ability to disable it for all users. That feature was announced as coming in 5.2.2 <https://confluence.atlassian.com/display/JIRA/JIRA+5.2.2+Release+Notes>, so we delayed their upgrade until 5.2.2 was ready.

JIRA Upgrade Handbook © Go2Group, www.go2group.com Page 2

Prerequisites  

§  Valid  license  §  Supported  plaRorms  

§  CompaBble  plugins,  customizaBons  

§  Ninja  on  call?  

|    Go2Group  .com  5  

Process  

§  TesBng  §  Involve  stakeholders  

§  Plan  for  UAT/QA  

§  Repeat  as  necessary  

§  Plan  downBme  

|    Go2Group  .com  6  

Before you beginIn preparing for your upgrade:

❑ Check that you have a valid license for JIRA

❑ Check that your system is compatible: hardware, operating system, database, Java, etc.

❑ Are current plugins and customizations compatible or do they need to be upgraded? See: <https://confluence.atlassian.com/display/JIRA/Supported+Platforms>

❑ Ensure your JIRA guru is available for any unexpect-ed issues

You might also want to take advantage of newly sup-ported platforms. For example, JIRA 5.2.x supports Java 1.7, which offered JVM improvements. Prior to that version, JIRA only supported Java 1.6.

To check if the plugins are compatible, JIRA provides a “JIRA Upgrade Check” option in the user interface. It gives you a report, based on which plugins are marked as compatible in the Atlassian Marketplace. If the plugin is custom developed and is not available on marketplace, make sure you check the compatibility via <http://check-up.atlassian.com/>. In both cases, we recommend you test after you upgrade.

Plan your processYou’re going to need to:

• Plan thorough testing at the functional, performance, user experience levels

• Communicate with your stakeholders and business owners

• Involve stakeholders and other users in a plan for acceptance testing

• Repeat as necessary

We recommend you document the exact steps, in great detail, during the test runs. It will make life a lot easier during the production run. For example, you might have made a change to the web.xml where you added “securi-ty-constraint” to redirect from http URLs to https. It is a simple change that is easy to forget when you do the production run. Detailed notes can prevent mistakes like that and save you a lot of time.

JIRA Upgrade Handbook © Go2Group, www.go2group.com Page 3

Consider your network ❑ Make sure you’re familiar with your network com-ponents, such as Apache, IIS, SSL certs, and port changes. If you are changing subnets, hardware, OS, ports, etc., these need be be considered and addressed.

❑ An example we come across often is the proxyName configuration in the server.xml. If this is not migrated, your firewall might block the requests to JIRA based on the rules they have in place.

❑ Another important configuration setting in Linux systems is the IP table rules, where only certain ports are allowed. For example, port 8080 might be blocked whereas 8081 is allowed. In such cases, make sure the rules are not altered. This is especially important when you move to a new server because the same rules should be implemented there as well.

❑ A common configuration you might find is Apache or IIS sitting in front of JIRA. Apache or IIS might redirect ports, implement reverse proxy, and serve SSL certificates.

❑ If you are connecting JIRA to other apps over https, make sure the public certificates for those apps are available in the “keystore.” You may copy the “cacerts” file across or re-import them!

❑ If you are moving to a new server, things can get slightly complicated. Make sure the connectivity works from JIRA on the new server to your database and to other integrated apps, such as Confluence. Another thing to check is whether you have connec-tivity to the Atlassian marketplace. If not, UPM won’t be able to connect and you will have to manually upgrade the plugins.

Network  Issues  

§  Firewall,  network  restricBons  

§  Apache/IIS  configuraBon  

§  Proxy,  reverse  proxy  

§  IP  tables,  ports  

|    Go2Group  .com  7  

Server  Issues  

§  Know  your  server!  §  Indexes,  acachments,  JIRA  home/installaBon  

§  Folder  permissions  

§  Scripts  

§  Fail-­‐over?  

|    Go2Group  .com  8  

Know your server configuration ❑ Look at the folders for the indexes, attachments, and JIRA home. Ensure folder permissions are correct.

❑ Scripts need to be updated, including failover scripts.

❑ We recommend you run the upgrade as the JIRA user. If not, make sure the permissions are changed appropriately after upgrade.

❑ Look at your sample scripts: Jelly scripts, init.d script, Groovy scripts, cron jobs, etc.

❑ If you have fail over, what is the strategy? Cold Standby? Warm/Hot Standby? See: <https://conflu-ence.atlassian.com/display/ATLAS/Failover+for+JIRA>

❑ Make sure the second JIRA instance is upgraded too.

JIRA Upgrade Handbook © Go2Group, www.go2group.com Page 4

Before  You  Upgrade  

§  Always  backup!  

§  Follow  OS-­‐specific  instrucBons  

§  Read  release  notes  

|    Go2Group  .com  9  

Ready to begin?Not quite yet! There are a few steps you want to do first.

❑ Most important: Do a backup!!!!

❑ While that’s underway, study the upgrade steps to get from your current version to the version to which you are upgrading. This can be quite simple, or it can require multiple upgrades. Read all pertinent upgrade and release notes for your specific upgrade. Read these steps again and again until you know them inside-out! See: <https://confluence.atlassian.com/display/JIRA/JIRA+5.2.2+Release+Notes>

❑ Read the OS notes. What flavor of OS are you us-ing? Make sure you follow the proper OS notes.

❑ Pay special attention to intermediate upgrade notes. For example, if you are moving to a version higher than JIRA 4.3; there is an important change in the user directories. Starting with 4.3, JIRA uses embed-ded Crowd. If you are migrating from an earlier ver-sion that has LDAP integration, make sure the old osuser.xml is present under WEB INF/classes folder during the upgrade. <https://confluence.atlassian.com/display/JIRA/JIRA+4.3+Upgrade+Guide#JIRA4.3Up-gradeGuide-Upgradeconsideration>. You are most likely to miss this step if you only read the current upgrade notes.

❑ Even the intermediate release notes are important. For example, consider JIRA 5.1 where “AutoWatch” was introduced. If you were moving to 5.2 and you were not aware of this change, your users might start getting a lot more emails than usual. While some like it, some might consider it spam! There is an option to disable it in user profiles but it is better to communi-cate it prior to the upgrade than to do it later.

❑ Another example is where the JIRA project key was limited to 10 characters. It affects only new projects but we have learned from our experience that some customers were not prepared for it.

❑ That’s not all. You might be able to remove some plugins based on the improvements over older versions. For example, the CHANGED and WAS operators introduced in JIRA 4.4.3’s “Advanced Searching” made some plugins redundant.

JIRA Upgrade Handbook © Go2Group, www.go2group.com Page 5

Upgrade  Methods  

§  Upgrade  methods  

§  JIRA’s  upgrade  uBlity  §  Install  new,  point  to  database  §  Install  new,  restore  via  XML  

§  Install  to  intermediate  version  first  

|    Go2Group  .com  10  

Upgrade  

§  Use  the  installer’s  upgrade  opBon,  when  possible  §  Config  tool  

§  For  4.4  or  greater  §  Located  at  bin/config.sh  

§  Verify  JIRA  Home  and  database  configuraBons  

|    Go2Group  .com  11  

Upgrade methods The upgrade utility only works if you are using the same server and only on version 4.4.x and greater.

If you are changing servers, or changing Operating Systems, we recommend you install the new version of JIRA, then point it to the existing database.

For pre 4.0 versions you will need to restore the data via XML.

You may not be able to upgrade in one step. For example, if you are upgrading from 3.x to 5.x, you must upgrade to 4.4.x first, as there were database structure changes in 4.4. The release notes will explain the requirements.

UpgradeUse the installer’s upgrade option, <Option 3>, wherever possible. The upgrade option gives you several benefits:

• It gives you the option to back up the JIRA Home folder

• It always backs up the installation directory

• It copies the memory settings, like JVM arguments, to the new installation

• It checks for local modifications in the installation directory (i.e., added or modified files)

If you have version 4.4 or greater, use the config tool to ensure the database is connected and the JIRA Installa-tion directory is configured properly. The config tool is always located in the JIRA bin Installation Directory: bin/config.sh or bin/config.bat depending on the OS.

If the config tool is not available you must verify the JIRA Home and database configurations.

Again: We recommend you use the upgrade option when you can.

JIRA Upgrade Handbook © Go2Group, www.go2group.com Page 6

Customiza*ons  

§  Reapply  server  customizaBons  

§  Verify  memory  configuraBons,  Java  arguments  

§  Restore  modified  files  

§  Port  added  files  

§  Merge  (✓),  never  overwrite  (  x  )  

|    Go2Group  .com  12  

Customiza*ons  

§  Upgrade  plugins  §  IntegraBons  with  other  systems?  

§  Re-­‐index  

§  Verify  logs,  fix  errors  

|    Go2Group  .com  13  

JIRA customizationsHave you made any customizations to JIRA?

❑ You’ll need to re-apply the server configurations, such as server.xml and the keystore certificates.

❑ Verify your memory configurations and other java arguments. E.g.: Heap memory, Newrelic.

❑ Restore modified files. E.g.: crowd.properties, ser-aph-config.xml, web.xml, templates, jsps.

❑ Port Added files. E.g.: icons, images, templates, etc.

❑ Merge, never overwrite

Server customizations include changes in http connec-tor like ports, proxyName, proxyPort, https connector settings, etc.

An example where merge can cause issues is server.xml. If you overwrite the server.xml file from the JIRA 4.4 instance to the JIRA 5.2 instance, JIRA won’t start. On the other hand, if you merge in the changes, startup will work fine.

More customizations ❑ Do any plugins need to be upgraded?

❑ Third-party integrations?

❑ After you run the upgrade JIRA will re-index, how-ever sometimes you will need to manually re-index

❑ Verify logs are error free. Fix errors and retest.

Plugins are usually upgraded manually after the JIRA upgrade process is completed. In some cases, it is man-datory to do a manual indexing after the upgrade. For example, the GreenHopper plugin requires that you do a manual reindex after upgrading to GH 6.0. If you don’t, the rapid board showed up empty. See: <https://conflu-ence.atlassian.com/display/GH/GreenHopper+6.1.6+Up-grade+Notes#GreenHopper6.1.6UpgradeNotes-Re-index-requiredifupgradingfrom5.9.7orolder>

JIRA Upgrade Handbook © Go2Group, www.go2group.com Page 7

AIer  Installa*on  

§  Test,  test,  and  test!  §  Login  again  the  next  day  and  re-­‐test  

§  Document  

|    Go2Group  .com  14  

Debugging  

§  Check  for  prior  art  in  knowledgebase  

|    Go2Group  .com  15  

After installation ❑ Test, test, and test!

❑ Login again the next day and re-test. The reason we recommend testing the next day is that some cus-tomizations may be scheduled jobs, jelly scripts, or services which can’t be tested immediately after the upgrade. Usually by the next day, scheduled jobs and scripts will have run, and there will be errors to reveal any issues.

❑ Now that the upgrade is working, document the upgrade and the customizations in your internal documentation.

It is good to have documentation for your organization, based on past upgrades, because the Atlassian documen-tation is generic.

For instance, we had an experience where the customer had a Zkoss application deployed within the webapps folder of JIRA standalone. Surely that won’t be covered in Atlassian docs! ;)

Problems? What if you run into upgrade problems? Check the knowledge base!

<https://confluence.atlassian.com/display/JIRAKB/JIRA+-Knowledge+Base+Home>

The screenshot illustrates a case we experienced. This error happened with the MS-SQL database during the upgrade process. The upgrade was stuck indefinitely during the “updating custom field” stage. The fix was not obvious! It was to temporarily turn ON the READ_COMMITTED_SNAPSHOT flag.

You can spend days looking for resolution, repeat the steps, call experts, raise a support case with Atlassian — or just search the knowledge base to find this article! ;)

<https://confluence.atlassian.com/pages/viewpage.ac-tion?pageId=264045011>

JIRA Upgrade Handbook © Go2Group, www.go2group.com Page 8

Plan  for  Rollback  

§  Be  ready  for  Murphy!  

§  Have  backups  on  hand,  be  ready  to:  §  Restore  old  JIRA  installaBon/Home  directories  

§  Restore  database  §  Import  the  old  backup  XML  

§  Test  everything  again!  

|    Go2Group  .com  16  

Prepare for problemsMurphy’s law: Anything that can go wrong, will!

Murphy’s corollary: Murphy was an optimist!

Be ready to rollback, just in case. Have the files at hand and be ready to restore the old JIRA installation/Home directories and the database. Or import the old backup XML.

Test everything – customizations, integrations, modifica-tions — again!

JIRA Upgrade Handbook © Go2Group, www.go2group.com Page 9

About the authorsDoug Bass and Jobin Kuruvilla are partners at Go-2Group and longtime JIRA and application lifecycle management (ALM) experts.

Doug is a veteran systems architect and network de-signer with expertise in distributed application design, database architecture, SCM, ALM integrations, ESBs, project management and is a certified Scrum Master.

The author of the first relational database for military applications in the UK and the first Java/Internet-based chat application, Doug teaches classes in Object-Ori-ented Design. He holds a Masters Degree in Informa-tion Architecture.

Jobin has worked with JIRA since its early days and is now an Atlassian consultant and plugin developer. He’s an active member in the Atlassian Answers forum and operates the JIRA Tricks blog: http://www.j-tricks.com.

Check out Jobin’s “JIRA Development Cookbook,” available at Amazon and other booksellers.

Authors  Doug  Bass  Senior  Vice  President  of  Engineering  

Jobin  Kuruvilla  Senior  Managing  Consultant  

JIRA Upgrade Handbook © Go2Group, www.go2group.com Page 10

Been there, done that! As the leading industry experts in application lifecycle management (ALM) and Atlassian’s oldest partner in North America and Japan, Go2Group has installed and upgraded thousands of JIRA systems, for hundreds of clients in 66 countries.

We’ve learned the hard way – and developed a playbook that helps our clients get up and running quickly.

Contact us. We’ve done it all before!

Less  Pain,  More  Gain  

§  Sharing  Go2Group’s  best  pracBces  §  Hundreds  of  soDware  producBvity  installaBons  since  2002  

§  Oldest  Atlassian  Partner  in  North  America  and  Japan  

§  Hundreds  of  acBve  clients  §  66  countries  

   |    Go2Group  .com  3  

About  Go2Group  

§  The  world’s  largest  reseller  of  Atlassian  development  tools  

§  Enterprise  PlaBnum  Atlassian  Expert  

§  SoDware  ProducBon  Line  AutomaBon  (SPLA)  Experts  

§  ExperBse  includes  enterprise  soluBons  such  as  JIRA/Perforce  integraBons  and  MuleSoD  ESB  

|    Go2Group  .com  17  

About Go2Group Go2Group is a global provider of consulting services, third-party application integrations, data migrations, software testing, and training services in Application Lifecycle Management (ALM) systems. We’ve imple-mented thousands of enterprise-level migrations. We specialize in complex, multi-platform, ALM integration projects.

Our goal: To make it easy. Our clients say, “We feel like you are part of our team.” Go2Group is expert in the en-tire Atlassian product line and in best of breed solutions, including HP, IBM, Perforce, Salesforce, and Sugar-CRM environments.

An Enterprise and Platinum Atlassian Expert, we offer a full suite of services for all Atlassian products and are the world’s largest reseller of Atlassian tools.

http://www.go2group.com/

Corporate Office, USA: 138 North Hickory Avenue, Bel Air, MD 21014

Hawaii: 7007 Hawaii Kai Drive, Suite C26, Honolulu, HI 96825

Japan: Le Premier Akihabara 11th Floor, 73 Kanda Ner-ibei-cho, Chiyoda-ku, Tokyo 101-0022

China: Great Wall Computer Building A301, 38 Xueyu-an Road, Haidian District, Beijing 100083

Telephone:

877-442-4669 (toll free) 410-879-8102 (local)

Email: sales@go2group.com

Go2Group & GSA

Atlassian products and Perforce SCM are available un-der the GSA purchasing program! Schedule 70 – Mul-tiple Award Contract GS-35F-0209W. Expiration date: January 20, 2015

www.go2group.com

Complexity Made Simple