Add-on Tips and Tricks

Still need help?

The Atlassian Community is here for you.

Ask the community

Purpose

The purpose of this knowledge base article is to understand from a high level how to install plugins, how they start, troubleshooting steps, and where the data is stored. 

Installation

You can simply install add-ons through the marketplace (See Installing Marketplace apps for a full reference). Though if you receive errors via this method with a particular add-on please try the manual installation described below. 

Manual Installation: Technically with most add-ons you can install them manually by downloading the JAR file through the  (make sure to check compatibility via version history on marketplace.atlassian.com) and copying that file into <jira-home>/plugins/installed-plugins (You can check Manage Add-ons) or in the case if it's an OBR file install it through the UI via the marketplace (See Installing file Installing file by upload for reference).  

Some add-ons may require special instructions for installation. In these cases, please refer to the add-on's installation documentation.

Solution

Start-up

When JIRA starts it will look at the <jira-home>/plugins/installed-plugins directory and attempt to load all the plugins. This includes the bundled plugins as well asthird party add-ons.  Two common issues you will see related to plugins on startup:

  1. Plugins failing to load due to timing out. This can simply be an issue of increasing the timeout as the startup process is very resource intensive. Adding -Datlassian.plugins.enable.wait=300 argument to the JIRA startup arguments should do the trick. See Setting Properties and Options on Startup for details. 
  2. JIRA fails to start due to disabled plugins. Please see JIRA applications System Plugin Timeout While Waiting for Add-ons to Enable to address this issue. 

JIRA safe mode

You can enable JIRA safe mode through the UI as an administrator. You will navigate to Manage Add-ons when logged in as an administrator. Click Enable safe mode at the bottom of the page.

If you JIRA is failing to startup you can copy the contents out of <jira-home>/plugins/installed-plugins to a staging location. Then attempt to start jira. It is a good idea to monitor the catalina.out located in <jira-install-folder>/logs to monitor the startup using tail -f in  or in windows a similar equivalent.  


Disabling non-system add-ons

From JIRA 7.3, JIRA can be started with all non-system add-ons, or a selection of these add-ons, disabled. This helps with troubleshooting when these non-system add-ons are causing issues with your JIRA instance, such as causing JIRA to fail on start up, or when the add-on is malfunctioning and can't be removed through UPM. The parameters do not persist, that is, they are applied at start up once, and if you need to restart JIRA, you need to apply them again. The process is slightly different depending on your operating system:

Windows

The parameters should be specified at system start up when JIRA is started using the start-jira.bat file, for example:

<installation-directory>/bin/start-jira.bat /disablealladdons /disableaddons=com.atlassian.test.plugin

If you don't use start-jira.bat for starting JIRA, but still wish to use this feature, you can add the following JVM parameter to the invocation of the servlet container that's running JIRA:

-Datlassian.plugins.startup.options="/disablealladdons /disableaddons=com.atlassian.test.plugin"

To disable multiple plugins, use acolon separated list of plugins. Regex/wildcards are not permitted, the full key of the plugin must be provided, for example:

-Datlassian.plugins.startup.options="/disablealladdons /disableaddons=com.atlassian.test.plugin:com.atlassian.another.test.plugin"

Notes

  • If the add-on key contains a space, this feature will not work, you need to manually deal with that add-on.
  • This feature does not work for JIRA Data Center applications.
  • This can be used to disable an add-on deemed critical to JIRA starting, and if one of those is disabled, JIRA will fail to start

  • Thiscan canbe used to disable JIRA application OBR bundles, for example, to stop the JIRA Software add-on:

    <installation-directory>/bin/start-jira.bat /disableaddons=com.atlassian.jira.jira-software-application

Linux

The parameters should be specified at systemstart upwhen JIRA is started using the start-jira.shscript, for example:

./bin/start-jira.sh --disable-all-addons --disable-addons=com.atlassian.test.plugin

If you don't use start-jira.sh for starting JIRA, but still wish to use this feature, you can add the following JVM parameter to the invocation of the servlet container that's running JIRA:

-Datlassian.plugins.startup.options="--disable-all-addons --disable-addons=com.atlassian.test.plugin"

To disable multiple plugins, use acolon separated list of plugins. Regex/wildcards are not permitted, the full key of the plugin must be provided, for example:

-Datlassian.plugins.startup.options="--disable-all-addons --disable-addons=com.atlassian.test.plugin:com.atlassian.another.test.plugin"

Notes

  • --disable-addons takes a colon-separated list (chosen as a colon is the only prohibited character from a plugin key) of addonsto be disabled. These can be system add-ons.
  • This feature does not work for JIRA Data Center applications.
  • This can be used to disable an add-on deemed critical to JIRA starting, and if one of those is disabled, JIRA will fail to start

  • Thiscan canbe used to disable JIRA application OBR bundles, for example, to stop the JIRA Software add-on:

    ./bin/start-jira.sh --disable-addons=com.atlassian.jira.jira-software-application

Plugin cache

Plugin cache is stored in the following locations: <JIRA_HOME>/plugins/.bundled-plugins and <JIRA_HOME>/plugins/.osgi-plugins. The contents of these folders can be cleared when JIRA is shutdown. The cache will be regenerated automatically on JIRA start-up. 

Where is plugin data stored?

Often times when plugins fail to load on start-up or cease to function. There is a concern that the data is lost. If the plugin is failing to enable either on startup or during operation. The data is actually stored in the database. Depending on the plugin where it is specifically stored can vary by plugin. This is why it's important to have a good back-up policy to ensure data recovery in the case of plugin corruption. Just to be clear the JAR files contain the classes etc for the plugin to load but the plugin data is actually stored in the database. 


Description The purpose of this knowledge base article is to understand from a high level how to install plugins, how they start, troubleshooting steps, and where the data is stored. 
Product Jira
Platform Server
Last modified on Oct 17, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.