The installation procedure may differ for different plugins, but it has some common steps, which we will review in this section. Before installing a plugin, you should always check out its documentation to ensure that you will be doing this properly.
Redmine plugins usually come in a directory, which should be copied to the plugins subdirectory of Redmine (that is, for example, into /opt/redmine/redmine-3.2.0/plugins if you have installed Redmine at /opt/redmine/redmine-3.2.0).
Tip
What if the plugin's directory is missing or has an invalid name?
The plugin should contain the init.rb file in its main directory. So, if this file is in the root, it means that the plugin's directory is missing. Also, the init.rb file should contain the following line:
Redmine::Plugin.register :plugin_name do
Here, plugin_name is the name of the plugin. The plugin's directory must have exactly the same name.
Most plugins require migration. This means that, in order for the plugin to work, some changes must be made to the Redmine database. To perform plugin migration, execute the following command on the Redmine server:
$ rake redmine:plugins:migrate RAILS_ENV=production
It is safe to execute this command even if the plugin does not require migration.
Finally, to activate the plugin, you need to restart Redmine using the following command:
$ sudo service apache2 reload
This is actually all you need to do to install an ordinary plugin for Redmine.
Often, new versions of plugins are released to support newer versions of Redmine. Therefore, when a new version of a plugin arrives, you need to make sure that it still supports the version of Redmine that you are using. Otherwise, upgrading to such a version may break your installation. But how can you check for supported versions?
The first source where you should check this is the page from which you got the plugin. Thus, if it was GitHub, check in the README.md file (if it's missing there, look for similar files, for example, README.txt).
You can also check the page of the plugin in the official Redmine plugin directory at http://www.redmine.org/plugins. Check out a sample page, shown in the following screenshot:
The versions of Redmine that are supported by the latest version of the plugin are listed in the Compatible with field (you can also check which versions of Redmine were supported by older versions of the plugin in the Changelog section of the page). Unfortunately, this information can be outdated in the official directory (because, for example, the latest version was not registered yet).
Alternatively, you can try checking the home page of the plugin, which should be shown in the installed plugins list, if specified. To check this list, open the Plugins page in the Administration menu. Certainly, for this information to be reflected on the home page, the new version should be authored by the same person as the version that you are already using (in other words, it should not be a fork).
Now, let's speak about the upgrade procedure. In general, it is the same as the installation one. That is, to upgrade a plugin, you usually need to perform the same three steps:
- Update the code (it would be a great idea to back up the old code).
- Run the migration.
- Restart Redmine.
I assume that you will want to try several plugins to decide which one best fits your needs (unfortunately, some plugins do not provide enough information to make a decision without trying them). So, in this case, you will need to know how to uninstall them correctly.
To uninstall a plugin, you first need to roll back the database changes that were made during the migration phase of the installation. Thus, if you want to remove the plugin_name plugin, you need to execute this:
$ rake redmine:plugins:migrate NAME=plugin_name VERSION=0 RAILS_ENV=production
Note VERSION=0, which means that the plugin should be migrated to the "zero" (that is, none) version. Also note that it is safe to execute this command even if the plugin does not include migration scripts.
After that, you can remove the plugin's directory (which is named after it) from the plugins subdirectory of the Redmine root directory (that is, /opt/redmine/redmine-3.2.0 if you installed Redmine there).
Finally, you need to restart Redmine:
$ sudo service apache2 reload