hitobito is an open source web application to manage complex group hierarchies with members, events and a lot more.
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
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.
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
toWagonfile
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 fromvendor/wagons
to a sibling directory and adjust the wagon’s fileapp_root.rb
accordingly.
See Wagons for more information on wagons and its available rake tasks.
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
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.