Developing a New Module

Kanrisuru was built to be extended with additional remote server managment modules as 3rd party gems.

Leveraging Core Module Commands

Alot of standard linux commands that form the building blocks of writing a module are available for you to utilize. Check in the docs to see if what you are creating doesn’t have some of the commands implemented already.

Extend as a Ruby Gem

Creating a new module is as simple as creating a new Ruby Gem. Please review the official rubygems.org guides for more information on the basics with writing a Gem.

Naming Convention

To create a new project, you should first name the module with an appropriate name. As an example, for the Nginx module:

kanrisuru-nginx

Where kanrisuru-[MODULE] is an extension module of the Kanrisuru namespace.

Gem Dependency

In your .gemspec file, make sure to include kanrisuru as a dependency:

# ./kanrisuru-nginx.gemspec
...
gem.add_dependency 'kanrisuru', `~> XX.YY`
...

You may want to specify the major / minor version of Kanrisuru to ensure your dependency doesn’t break with Kanrisuru updates.

Project Structure

At the core of the gem is the project structure that leverages Kanrisuru’s already built in set of core modules. Looking at the nginx module:

$ tree lib/
lib
└── kanrisuru
    ├── nginx
    │   ├── package.rb
    │   ├── service.rb
    │   ├── signal.rb
    │   └── version.rb
    └── nginx.rb

At a minimum, you’ll need to have the following setup:

lib/
lib/kanrisuru/
lib/kanrisuru/module.rb
lib/kanrisuru/module/

Adding Commands to a Module

With your gem project started, the kanrisuru gem dependency specified, and your lib directory setup properly, you’ll want to create the set of commands that your module will provide.

OsPackage

Kanrisuru provides the OsPackage::Define, OsPackage::Collection and OsPackage::Include to make it easy for your module to plug each command into the Kanrisuru ecosystem.

OsPackage::Define

When writting your set of commands, it’s best to nest these under a ruby module. Take for example, creating a module that let’s a user manage an Apache server:

# ~/kanrisuru-nginx/lib/kanrisuru/nginx/manage.rb
module Kanrisuru
  module Apache
    module Manage
      extend OsPackage::Define

      os_define :linux, :start
      os_define :linux, :stop

    end
  end
end

By extending the Kanrisuru::Apache::Manage module with OsPackage::Define, we’ll be able to add a few methods that are necessary with how Kanrisuru determines method / os compatability at run time.