Project

General

Profile

How to Install a Plugin » History » Version 14

« Previous - Version 14/17 (diff) - Next » - Current version
Dominic Cleal, 01/07/2014 11:26 AM
toc


How to Install a Plugin

Foreman plugins are implemented as gem in Ruby on Rails. See below for the different installation methods, which depend on your platform.

RPM installations

Packaged plugins

A limited number of plugins are available fully packaged from our yum repositories for ease of use. The number of these is increasing, so check the List of Plugins to see if a package is available yet. If it's a useful or popular plugin and not yet packaged, please file a feature request in the packaging project.

The repos are available here: http://yum.theforeman.org/plugins/. Separate repos are available for each Foreman release, containing plugins that are compatible with that particular version. Packages are not currently GPG signed.

1. Configure the repo by creating /etc/yum.repos.d/foreman_plugins.repo:

[foreman-plugins]
name=Foreman plugins
baseurl=http://yum.theforeman.org/plugins/1.3/el6/x86_64/
enabled=1
gpgcheck=0

2. Find the package for the plugin: yum search rubygem-foreman
3. Install the package, e.g. yum install ruby193-rubygem-foreman_discovery
4. Restart Foreman: touch ~foreman/tmp/restart.txt or service httpd restart

Some plugins (e.g. foreman_column_view) may also require configuration in /usr/share/foreman/config/settings.plugins.d/, check for any .example files.

Advanced: installing from gems

Not recommended, as it's possible for the 'gem' command to try and install newer versions of Rails which can cause problems. Do note the install without dependencies below to avoid this problem.

Ensure the plugin you want is available from rubygems.org as a gem. Plugins that aren't published (just git repos) can't be installed with this method without being built as a gem.

1. If on EL6, run scl enable ruby193 bash first for an SCL-enabled shell (not needed on Fedora)
2. Install without dependencies: gem install --ignore-dependencies foreman_column_view
3. If you need other dependencies (see the rubygems.org page), check the yum repo above (e.g. deface, nokogiri) or install the same way with 'gem'
4. Add to the bundler.d/Gemfile.local.rb file as detailed below.
5. Restart Foreman: touch ~foreman/tmp/restart.txt or service httpd restart

If you hit problems, uninstall the added gems with gem uninstall -v VERSION GEM.

Deb installations

Packaged plugins

A limited number of plugins are available fully packaged from our deb repositories for ease of use. The number of these is increasing, so check the List of Plugins to see if a package is available yet. If it's a useful or popular plugin and not yet packaged, please file a feature request in the packaging project.

The repo is available at http://deb.theforeman.org plugins main. There is only one component (main) for all plugins at this time. They are signed with the Foreman APT key.

1. Add a source line like this: deb http://deb.theforeman.org/ plugins main to Apt
2. Find the package for the plugin: apt-cache search ruby-foreman
3. Install the package, e.g. apt-get install ruby-foreman-discovery
4. Restart Foreman: touch ~foreman/tmp/restart.txt or service apache2 restart

Some plugins (e.g. foreman_column_view) may also require configuration in /usr/share/foreman/config/settings.plugins.d/, check for any .example files.

Advanced: installing from gems

Since the Debian packages still use bundler, you can use the "from source" section below.

"from source" installations

It is recommended to use ~foreman/bundler.d/Gemfile.local.rb (see Bundler_groups for background) so that it is not overwritten by future upgrades.

If it's published on rubygems.org, just add the name and the latest released version will be downloaded. Add to bundler.d/Gemfile.local.rb:

gem 'foreman_sample_plugin'

Or bundler can install the plugin from a git repository. Add to bundler.d/Gemfile.local.rb:

gem 'foreman_sample_plugin', :git => "https://github.com/example/foreman_sample_plugin.git" 

Next, as a Foreman user (not root), run the following command:

$ bundle update foreman_sample_plugin

Then restart Foreman with touch ~foreman/tmp/restart.txt.