Deploying a plugin

In this recipe, we will see how to deploy a plugin into JIRA. We will see both the automated deployment using 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 Atlassian Plugin SDK is a cake walk. Here is 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 resides.

2. Type atlas-run and press Enter. It is possible to pass more options as argument to this command for which the details can be found at: http://confluence.atlassian.com/display/DEVNET/atlas-run.

3. 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 lot of time when you run it for the first time.

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

5. When the installation is completed, 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

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

7. Login using the username as admin and password as admin.

8. Test your plugin! You can always go to the Administration | Plugin menu to confirm that the plugin is deployed properly.

If you already have a local JIRA installed or if you want to manually install your plugin for some reason, all you need to do is to package the plugin JAR and copy it across to the JIRA_Home/plugins/installed-plugins directory.

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 package 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:

1. Builds your plugin JAR file

2. Downloads the latest/specified version of JIRA to your local machine if it is the first time you're running the command.

3. Creates a virtual JIRA installation under your plugin/target folder.

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

5. Starts JIRA in the Tomcat container.

Now, if you look at your target folder, you will see a lot of new folders which 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. And you will 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...

There's more to this.

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 it:

1. Mention the JIRA version as an argument to atlas-run; make sure you run atlas-clean, if you already have the latest version deployed:

   • Run atlas-clean (if required).

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

2. Permanently change the JIRA version in your plugin pom.xml:

   • Go to your pom.xml.

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

   • Modify the jira.data.version to a matching version.

This is how it will look for JIRA 4.1.2:

<properties>
    <jira.version>4.1.2</jira.version>
    <jira.data.version>4.1</jira.data.version>
</properties>

Reusing the configurations in each run

Suppose you added some data on to virtual JIRA, how do you retain it when you clean start-up JIRA next time?

This is where a new SDK command comes to our rescue.

After the atlas-run is finished, that is, after you 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 to add the following entry under configurations in the maven-jira-plugin:

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

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

Troubleshooting

• Missing 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 in to the local repository.

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

• BeanCreationException? Make sure your plugin is of version 2. Check your atlassian-plugin.xml to see if the following entry is there or not. If not, add the entry:

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

Run atlas-clean followed by atlas-run after you do that.