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 (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 Install an app from a file for reference).  

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 as third 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 Bundled plugin not available error thrown on Jira server login 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.

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 system start up when Jira is started using the start-jira.sh script, 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 a colon 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 addons to 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

• This can 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.