Upgrading Jira 4.0 to 5.1: It Is Possible

I recently needed to upgrade our group's Jira tracking software from version 4.0 (very old) to 5.1 (the latest).  The main lesson as always with software is to carefully walk the entropy ridge to your destination: one false step and you will plummet.  My main advice is 

• Don't build from source
• Don't try to install the WAR in your own Tomcat
• Use instead the packaged Jira build.
• Set up your new installation in a completely separate place, minimally using a different account, $JIRA_HOME, and database.  This will keep the old installation safe and allow you to start from scratch a few times with the new installation. 

The instructions at https://confluence.atlassian.com/display/JIRA/Upgrading+JIRA+Manually are reasonable.  I exported the old Jira DB as XML and imported it using the setup wizard for Jira 5 (see step 2 of https://confluence.atlassian.com/display/JIRA/Running+the+Setup+Wizard).  You want to import the XML at this step, not post-installation using the regular administration import/export tools. 

I chose to create an entirely new UNIX account to house the new Jira installation (but on the same server).  I created a new database instance and user also, so the old and new installations were cleanly separated.  This allowed me also to run the old and new instances simultaneously (I changed the new server port numbers) so we could make sure the transition went smoothly before shutting down the old server. 

I did have issues with the import of the XML, but fortunately I was able to edit these out by hand.

• One of the issues had some unusual non-printing characters.  I deleted it.
• The issue links all pointed to the old Jira's base URL, so I globally changed those to the new URL.
• UserHistoryItem: the import process (Step 2 of the Setup Wizard) choked on these, so I deleted them from the XML file.  I also corrected the count value for this field in the Entities section at the end of my XML export file, setting it to zero.

That's mostly it.  The new installation came up with all the old accounts, permissions, and issues in place.  

Needed more PermGen: Gadget Dashboard bundled plugin is not available Error When Accesing JIRA

Upgrading to Jira 5.1, I got the following error: "Gadget Dashboard bundled plugin is not available Error When Accesing JIRA" after completing the Jira installation. This makes Jira unusable. I resolved the problem by increasing the amount of PermGen space for the Tomcat server running Java. Below are my JAVA_OPT environment variable settings:

export JAVA_OPTS="-server -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -Dmail.mime.decodeparameters=true -Xmx1024m -Xms1024m -XX:MaxPermSize=512m"

The values for Xmx, Xms, and MaxPermSize should all be adjusted for the size of your host server's memory.