Deploying a JIRA plugin

In this recipe, we will see how to deploy a plugin into JIRA. We will see both the automated deployment using the Atlassian plugin SDK and the manual deployment.

Getting ready

Make sure you have the development environment set up as we discussed earlier. Also, the skeleton plugin should now have the plugin logic implemented in it.

How to do it…

Installing a JIRA plugin using the Atlassian plugin SDK is a cakewalk. The following steps show how it is done:

1. Open a command window and go to your plugin's root folder, that is, the folder where your pom.xml file resides.

2. Type atlas-run and press Enter. It is possible to pass more options as arguments to this command. The details regarding this can be found at https://developer.atlassian.com/display/DOCS/atlas-run.

   You will see a lot of things happening as Maven downloads all the dependent libraries into your local repository. As usual, it is going to take a lot of time when you run it for the first time.

3. If you are on Windows, and if you see a security alert popping up, click on Unblock to allow incoming network connections.

4. When the installation is complete, you will see the following message:

   [WARNING] [talledLocalContainer] INFO: Server startup in 123558 ms
   [INFO] [talledLocalContainer] Tomcat 6.x started on port [2990]
   [INFO] jira started successfully and available at http://localhost:2990/jira
   [INFO] Type CTRL-C to exit
   

5. Open http://localhost:2990/jira in your browser.

6. Log in using the username as admin and password as admin.

7. Test your plugin! You can always go to Administration | Plugins | Manage Add-ons to confirm that the plugin is deployed properly.

8. If you already have a local JIRA installed, or if you want to manually install your plugin, all you need to do is to package the plugin JAR and install it via the Universal Plugin Manager (UPM), as described in detail at https://confluence.atlassian.com/display/UPM/Installing+Add-ons#InstallingAdd-ons-Installingbyfileupload. Or, you can copy it across to the JIRA_Home/plugins/installed-plugins directory and restart JIRA.

   You can package the plugin using the following command:

   atlas-mvn clean package
   

   Use atlas-mvn clean install if you also want to install the packaged plugin into your local repository.

How it works…

There is only one single command that does the whole thing: atlas-run. When you execute this command, it does the following tasks:

• Builds your plugin JAR file

• Downloads the latest/specified version of JIRA to your local machine if it is the first time you are running the command

• Creates a virtual JIRA installation under your plugin's /target folder

• Copies the JAR file into the /target/jira/home/plugins/installed-plugins directory

• Starts JIRA in the Tomcat container

Now, if you look at your target folder, you will see a lot of new folders that were created for the virtual JIRA installation! The two main folders are the container folder, which has the Tomcat container setup, and the jira folder, which has the JIRA WAR along with the JIRA home setup!

You will find the database (HSQLDB), indexes, backups, and attachments under /target/jira/home. You can also see your jira-webapp at /target/container/tomcat6x/cargo-jira-home/webapps/jira.

If you have any JSPs that need to be put under the webapp, you will have to copy it to the appropriate folder under the aforementioned path!

There's more…

It is also possible to use a specific version of JIRA or to re-use the data that we have used for testing. To find out how, just read on.

Using a specific version of JIRA

As mentioned earlier, atlas-run deploys the latest version of JIRA. But what if you want to deploy the plugin into an earlier version of JIRA and test it? There are two ways to do this:

• Mention the JIRA version as an argument to atlas-run. Make sure you run atlas-clean if you already have the latest version deployed.

  1. Run atlas-clean (if required).

  2. Run atlas-run -v 5.0 or atlas-run -version 5.0 if you are developing for JIRA version 5.0. Replace the version number with a version of your choice.

• Permanently change the JIRA version in your plugin's pom.xml file.

  1. Go to your pom.xml file.

  2. Modify the jira.version property value to the desired version.

  3. Modify the jira.data.version property value to a matching version.

  Following is how it will look for JIRA 5.0:

  <properties>
    <jira.version>5.0</jira.version>
    <jira.data.version>5.0</jira.data.version>
  </properties>

Re-using the configurations in each run

Suppose you have added some data onto virtual JIRA; how do you retain it when you clean startup JIRA next time? This is where a new SDK command comes to our rescue. After the atlas-run command has finished its execution, that is, after you have pressed Ctrl + C, execute the following command:

atlas-create-home-zip

This will generate a file named generated-test-resources.zip under the target folder. Copy this file to the /src/test/resources folder or any other known locations. Now modify the pom.xml file to add the following entry under configurations in the maven-jira-plugin plugin section:

<productDataPath>${basedir}/src/test/resources/generated-test-resources.zip</productDataPath>

Modify the path accordingly. This will re-use the configurations the next time you run atlas-run.

Troubleshooting

Following are some points to remember:

• Missing a JAR file exception? Make sure the local-repository attribute in the settings.xml file points to the embedded Maven repository that comes with the SDK. If the problem still persists, manually download the missing JAR files and use atlas-mvn install to install them into the local repository.

  Note

  Watch out for the proxy settings or antivirus settings that can potentially block the download in some cases!

• Getting a BeanCreationException error? Make sure your plugin is of version 2. Check your atlassian-plugin.xml file to see if the plugins-version="2" entry is there or not. If not, add the entry shown as follows:

  <atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.artifactId}" plugins-version="2">

  Run atlas-clean followed by atlas-run after you have added the preceding entry.