Welcome to hitobito¶ ↑

hitobito is an open source web application to manage complex group hierarchies with members, events and a lot more.

Development¶ ↑

Hitobito is a Ruby on Rails application that runs on Ruby 1.9.3 and Rails 4. To get going, after you got a copy of hitobito and at least one wagon with an organization structure setup as described below, issue the following commands in the main directory:

yum install sqlite memcached sphinxsearch   # install system dependencies

bundle               # install gem dependencies
rake db:create       # create a development database (Sqlite3)
rake db:setup:all    # run migrations and load seed data of the app and all wagons
rails server         # start the rails server

To start the search server, run background jobs or the development mail catcher, run:

rake ts:start
rake jobs:work
mailcatcher -v -f

Group Hierarchy¶ ↑

hitobito provides a powerful meta-model to describe group structures. Groups are always of a specific type and are arranged in a tree. Each group type may have several different role types.

This core part of hitobito does not provide any specific group or role types. They have to be defined in a separate plugin, specific to your organization structure.

An example group type definition might look like this:

class Group::Layer < Group
  self.layer = true

  children Group::Layer, Group::Board, Group::Basic

  class Role < Leader
    self.permissions = [:layer_full, :contact_data]
  end

  class Member < Role
    self.permissions = [:group_read]
  end

  roles Leader, Member
end

A group type always inherits from the class Group. It may be a layer, which defines a set of groups that are in a common permission range. All subgroups of a layer group belong to this range unless a subgroup is a layer itself.

Then all possible child types of the group are listed. When creating subgroups, only these types will be allowed. As shown, types may be organized recursively.

For the ease of maintainability, role types may be defined directly in the group type. Each role type has a set of permissions. They are general indications of what and where. All specific abilities of a user are derived from the role permissions she has in her different groups.

The following basic permissions are defined:

:admin

May administer application wide settings.

:layer_and_below_full

May read and write everything in this layer and all below layers.

:layer_and_below_read

May read everything in this layer and all below layers.

:layer_full

May read and write everything in this layer.

:layer_read

May read everything in this layer.

:group_full

May read and write everything in this group.

:group_read

May read everything in this group.

:contact_data

May see all other people with the :contact_data permission.

Beside these basic group and role type features, some more possibilities exist. See the source of the Group class for additional details.

See hitobito_generic for a complete example group structure.

Plugin architecture¶ ↑

hitobito is built on the plugin framework Wagons. With Wagons, arbitrary features and extensions may be created for hitobito. As mentioned above, as there are no group types coming from hitobito itself, at least one wagon is required to define group types in order to use hitobito.

A few basic things to consider when working with Wagons:

• The main hitobito application and all wagons should reside in the same subdirectory.

• Copy the Wagonfile.ci to Wagonfile to load all wagons in sibling directories in development mode.

• Wagons use the same database as the main application. When creating migrations in hitobito, make sure to remove all wagon additions from the database before the schema is dumped. This is easiest by dropping and recreating the development database.

• When new gem dependencies are added to the main application, run rake wagon:bundle:update to update all wagon Gemfiles.

• Create a new wagon with rails g wagon [name]. Then move it from vendor/wagons to a sibling directory and adjust the wagon’s file app_root.rb accordingly.

See Wagons for more information on wagons and its available rake tasks.

Deployment¶ ↑

For a productive enviroment, the following environment variables may be defined:

RAILS_HOST_NAME

Public host name of the application, used for links in emails. This value is required.

RAILS_HOST_SSL

Does the application run on https (true or false). Default is false.

RAILS_SECRET_TOKEN

Secret token for the sessions (128 byte hex). This value should be set for security reasons.

RAILS_DB_NAME

Name of the database.

RAILS_DB_USERNAME

Username to connect to the database.

RAILS_DB_PASSWORD

Password to connect to the database.

RAILS_DB_HOST

Host to connect to the database.

RAILS_DB_PORT

Port to connect to the dababase.

RAILS_DB_ADAPTER

Database adapter. Default is sqlite3.

RAILS_MAIL_DELIVERY_METHOD

smtp or sendmail. See ActionMailer for details.

RAILS_MAIL_DELIVERY_CONFIG

A comma-separated “key: value” list with all required delivery settings for the chosen method, e.g. “address: smtp.local, port: 25”. See ActionMailer for valid options. If this variable is empty, the Rails defaults (localhost:25) are used.

RAILS_MAIL_PERFORM_DELIVERIES

Set to false when no mails should be delivered at all.

RAILS_MAIL_DOMAIN

The domain name for the mailing lists, default is RAILS_HOST_NAME.

RAILS_MAIL_RETRIEVER_TYPE

pop3 or imap, anything supported by the Mail gem. Default is pop3.

RAILS_MAIL_RETRIEVER_CONFIG

A comma-separated “key: value” list with all required retriever settings, e.g. “address: mailhost.local, port: 995, enable_ssl: true”. See Mail for valid options. If this variable is empty, mailing lists will not work.

RAILS_SPHINX_PORT

Unique port of the sphinx server for this application instance. Defaults to 9312.

RAILS_AIRBRAKE_API_KEY

Airbrake api key of the application. Nothing is sent if this variable is empty.

RAILS_AIRBRAKE_HOST

Host name of the airbrake instance to send errors to.

RAILS_AIRBRAKE_PORT

Port of the airbrake instance. Defaults to 443

License¶ ↑

hitobito is released under the GNU Affero General Public License. Copyright 2012-2014 by Jungwacht Blauring Schweiz. See COPYING for more details.

hitobito was developed by Puzzle ITC GmbH.