Archive:Hermes hacking

This article is being considered for deletion! Reason: openSUSE is not using Hermes anymore, development has stopped in 2013.. Please do not blank, merge, or move this article, or remove this notice. Refer to this article's discussion page and our deletion policy for more information.

Hermes

Hermes - Architecture - Subsystems - Contribute - Webui - Administration - OBS Integration

How to start

Hermes can be hacked on in the git checkout. To checkout the source code run

git clone https://github.com/openSUSE/hermes.git

To work with Herminator, be sure to have set up an http server such as Apache or lighttpd to serve the perl scripts.

To work on Starship, you need a Ruby on Rails environment. We use the 'official' Ruby for the openSUSE tools from the openSUSE Tools Repository.

The perl-DBD-mysql package is also needed.

Create the Database

To create the database for Hermes, the ruby on rails migration is used, as it is the most powerful mechanism for that. Even if you only want to play with the non ruby parts of Hermes, you need to create the database with starship.

First, create an empty database in mysql, ie. called hermes, eg. like this as root:

 mysql -e "create database hermes character set 'utf8'; grant all on hermes.* to hermes@localhost identified by 'hermes'; flush privileges;"

Change into the subdirectory "starship":

 cd starship

Check config/database.yml and setup the correct user, host and database name there for your environment (if you want to run hermes in production, configure the "production" environment); note that on some systems, you also have to change the path to the MySQL socket file to /var/run/mysql/mysql.sock instead of /var/lib/mysql/mysql.sock

You can control which environment (and hence settings) to use the environment variable RAILS_ENV, eg.:

 export RAILS_ENV=development

For a production system, use

 export RAILS_ENV=production

To actually create and set up all tables, call

 rake db:migrate

in the starship directory. That's it.

Note: Something is wrong with the migration 20091125104613_change_gennotisent_default.rb. It is supposed to set the default value of some datetime fields to '0'. Unfortunately this doesn't happen. It remains NULL which prevents both hermesgenerator and hermesworker not to generate/deliver any messages. Until this is fixed you can use this SQL snippet to fix it:

 ALTER table notifications CHANGE generated generated datetime DEFAULT 0;
 ALTER table generated_notifications CHANGE sent sent datetime DEFAULT 0;

Starship does not work without some initial database contents. These can easily be created by calling

 rake db:seed

Authentication in Starship

Hermes currently knows three kinds of authentication:

• simulate, ie. the user is hardcoded
• ichain, Novell iChain authentication is used
• basic authentication with a browser window

To pick the authentication code, set environment variables in starship/config/environments/, for example in development.rb for the development mode:

# Authentication:
# Starship can either authenticate against Novell iChain or use basic
# auth, which can be be configured with various sources through the
# webserver
# Parameter: AUTHENTICATION
# set this parameter to either
# :simulate => means the user is hardcoded to termite
# :ichain   => iChain is used.
# :off      => basic auth
AUTHENTICATION = :off

Setup a User

As you need a user at least in Starship, here is how you create it. The easiest way is to use the ruby console in Starship the following way:

 freitag@trixa:~/suse/git/hermes/starship> script/console 
 Loading development environment (Rails 2.3.8)
 Loaded gui abstraction from .../abstraction.xml
 Loaded starship config from config/starship.yml
 >> p = Person.new
 => #<Person id: nil, email: nil, name: nil, jid: nil, stringid: nil, admin: false, hashed_password: nil, salt: nil>
 >> p.email='hacker@opensuse.org'
 => "hacker@opensuse.org"
 >> p.name='Heino Hack'
 => "Heino Hack"
 >> p.stringid='heino'
 => "heino"
 >> p.salt = Person.random_string(10)
 => "gMbLgpLPXg"
 >> p.hashed_password = Person.encrypt('secret', p.salt)
 => "e81e3d8242e87979756bd94fc8ff8273b9ab11bb"
 >> p.save
 => true
 >> exit
 freitag@trixa:~/suse/git/hermes/starship>

Creating a Configuration File

Hermes needs a global configuration file placed at

 /etc/hermes.conf

To create it, copy the template in conf/hermes.conf.in to /etc and adjust it to your settings. The config file must be valid perl code and can be checked with the perl interpreter for syntax:

 kf@subbotin:~/hermes> perl -c /etc/hermes.conf
 /etc/hermes.conf syntax OK

Some important settings:

• %LOG: it's recommended to set the logpath entry for logging, which results in logfiles for the various Hermes processes in the path.
• $DB{'default'}: Specify the database settings you want to use here.
• $HerminatorDir: The base path of the Herminator, where currently the notification plugins are read from
• $OBSAPIBase: The API of the openSUSE Build Service to use (if needed).

Change others as needed.

Creating Notification Types

After the installation, the list of available notification types is empty. They get created with their first use automatically, so there is no need to create them explicitly. Use the command line tool notifyHermes.pl from the top level directory of the Hermes checkout to create notifications, for example using:

 notifyHermes -o 'bla=foo, bar=baz' CheckHermes

Call notifyHermes.pl -h to get help.