Plugin development - foreman_plugin_template - cannot load such file

Support
1

Hello,
I am following official docs describing how build custom plugins:
https://github.com/theforeman/foreman/blob/develop/developer_docs/how_to_create_a_plugin.asciidoc

  1. I fetched the foreman_plugin_template git repo. I didn’t change name of the plugin, nor modified anything in the plugin code.
cd /opt
git clone https://github.com/theforeman/foreman_plugin_template my_super_plugin
Cloning into 'my_super_plugin'...
remote: Enumerating objects: 599, done.
remote: Counting objects: 100% (182/182), done.
remote: Compressing objects: 100% (120/120), done.
remote: Total 599 (delta 73), reused 136 (delta 56), pack-reused 417 (from 1)
Receiving objects: 100% (599/599), 151.61 KiB | 6.59 MiB/s, done.
Resolving deltas: 100% (182/182), done.
  1. Added plugin template to Foreman
cd /usr/share/foreman/bundler.d/
cat foreman_plugin_template.rb

### OUTPUT OF cat:
gem 'foreman_plugin_template', :path => '/opt/my_super_plugin'
  1. Foreman cannot be started:

Feb 5 07:37:31 myserver01 dynflow-sidekiq@worker-1[471567]: 2025-02-05T06:37:31.540Z pid=471567 tid=a4sf WARN: RuntimeError: Gem loading error: cannot load such file – foreman_plugin_template
Feb 5 07:37:31 myserver01 dynflow-sidekiq@worker-1[471567]: 2025-02-05T06:37:31.540Z pid=471567 tid=a4sf WARN: /usr/share/gems/gems/bundler_ext-0.4.1/lib/bundler_ext/output.rb:13:in `strict_err’

Expected outcome:
Foreman plugin template installed successfully.
What am I doing wrong here? Is there a bug?
Why I can’t even load the foreman plugin template?
Directory /opt/my_super_plugin is accessible by everyone, I even changed permissions to 777 and it didn’t help.

Foreman and Proxy versions:
3.13, installed from official Foreman repos (using foreman-installer)

Distribution and version:
Alma OS 9.4

2

Ok I figured this out. If anyone wants to develop his own plugin it might be helpful.

To start with there was a bug in GitHub - theforeman/foreman_plugin_template: Template for creating new plugins. Simply because it requires Foreman version 3.14:
foreman_plugin_template/lib/foreman_plugin_template/engine.rb at master · theforeman/foreman_plugin_template · GitHub, line 16:

requires_foreman '>= 3.14.0'

It may be valid now, but this code was pushed to git more 2 months ago when Foreman 3.14 wasn’t available at that time.

So how I develop and test my plugin in the dev environment?

  1. Clone repo:
    git clone https://github.com/theforeman/foreman_plugin_template your_plugin_name
  2. Rename your plugin:
    ./rename your_plugin_name
  3. If you are using older version of Foreman (lower than 3.14) go to lib/<your_plugin_name>/engine.rb and comment out the if condition which requires version 3.14 or change version to e.g. 3.12
    requires_foreman '>= 3.12.0'
  4. Open gemspec file, and fill in your data, like author, your email, plugin description
    vi your_plugin.gemspec
    You can make other changes in your code if you want, but you will be able to do it later on.
  5. Create a gem file:
    gem build your_plugin
  6. Install your gem
    gem install your_plugin-0.0.1.gem
  7. Your plugin is located in:
    /usr/local/share/gems/gems/your_plugin-0.0.1
    You can modify your plugin directly from here.
  8. Add Plugin to Foreman.
    Go to following directory and edit or create Gemfile.local.rb file:
    /usr/share/foreman/bundler.d/Gemfile.local.rb
    In this file add your plugin:
    gem 'your_plugin'
  9. Restart Foreman
    systemctl restart foreman