Skip to content
Klutch.sh Docs

Deploying Hitobito

Introduction

Hitobito is a comprehensive open-source member and event management system designed for associations, clubs, and organizations. Originally developed for Swiss youth organizations, it has grown to support various types of membership organizations with complex hierarchical structures.

Built with Ruby on Rails, Hitobito provides powerful features for managing people, groups, events, courses, mailings, and more. Its flexible role and permission system allows organizations to model their specific structures while maintaining proper access control.

Key highlights of Hitobito:

  • Member Management: Comprehensive person and contact management
  • Group Hierarchies: Model complex organizational structures
  • Event Management: Create and manage events, courses, and registrations
  • Role-Based Access: Flexible permissions based on organizational roles
  • Mailing Lists: Integrated email distribution lists
  • Course Management: Training and certification tracking
  • Export Features: CSV, PDF, and label exports
  • Invoicing: Basic invoicing and payment tracking
  • Multi-Tenant: Host multiple organizations
  • API Access: REST API for integrations
  • Customizable: Wagon system for organization-specific extensions
  • Open Source: Licensed under AGPL-3.0

This guide walks through deploying Hitobito on Klutch.sh using Docker.

Why Deploy Hitobito on Klutch.sh

Deploying Hitobito on Klutch.sh provides several advantages:

Organization Access: Members can access from anywhere.

Centralized Data: Single source of truth for member information.

HTTPS Security: Secure handling of personal member data.

Reliable Hosting: Professional infrastructure for critical organization data.

Automatic Updates: Deploy updates without downtime concerns.

Prerequisites

Before deploying Hitobito on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • PostgreSQL database (deployed separately or external service)
  • Basic familiarity with Docker and Ruby on Rails
  • Understanding of your organization’s structure

Understanding Hitobito Architecture

Hitobito consists of several components:

Rails Application: Core web application handling business logic.

Background Workers: Delayed job processing for emails and exports.

PostgreSQL: Primary database for all data.

Redis: Optional caching and session storage.

Sphinx/Thinking Sphinx: Full-text search (optional).

Wagon System: Organization-specific customizations.

Preparing Your Repository

Create a GitHub repository with your Hitobito configuration.

Repository Structure

hitobito-deploy/
├── Dockerfile
├── config/
│   └── database.yml
└── .dockerignore

Creating the Dockerfile

FROM ruby:3.1-alpine


# Install dependencies
RUN apk add --no-cache \
    build-base \
    postgresql-dev \
    nodejs \
    yarn \
    tzdata \
    git \
    imagemagick


WORKDIR /app


# Clone Hitobito core
RUN git clone https://github.com/hitobito/hitobito.git .


# Install gems
RUN bundle install --without development test


# Precompile assets
RUN bundle exec rake assets:precompile


# Set environment variables
ENV RAILS_ENV=production
ENV RAILS_SERVE_STATIC_FILES=true
ENV DATABASE_URL=${DATABASE_URL}
ENV SECRET_KEY_BASE=${SECRET_KEY_BASE}


# Expose port
EXPOSE 3000


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000 || exit 1


# Start application
CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0"]

Environment Variables Reference

VariableRequiredDescription
DATABASE_URLYesPostgreSQL connection string
SECRET_KEY_BASEYesRails secret key
RAILS_ENVNoRails environment (default: production)
SMTP_ADDRESSNoSMTP server for emails
SMTP_PORTNoSMTP port
SMTP_USERNAMENoSMTP username
SMTP_PASSWORDNoSMTP password

Deploying Hitobito on Klutch.sh

    Deploy PostgreSQL

    Hitobito requires PostgreSQL:

    1. Deploy PostgreSQL on Klutch.sh or use managed service
    2. Create a database for Hitobito
    3. Note the connection string

    Generate Secret Key

    Create a secure secret key:

    Terminal window
    openssl rand -hex 64

    Push Your Repository to GitHub

    Commit your Dockerfile and configuration to GitHub.

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project named “hitobito” or “members”.

    Create a New App

    Create a new app and connect your GitHub repository.

    Configure HTTP Traffic

    Set up HTTP traffic:

    • Select HTTP as the traffic type
    • Set the internal port to 3000

    Set Environment Variables

    VariableValue
    DATABASE_URLYour PostgreSQL connection string
    SECRET_KEY_BASEYour generated secret key
    RAILS_ENVproduction

    Attach Persistent Volumes

    Mount PathSizePurpose
    /app/storage10 GBUploaded files
    /app/log1 GBApplication logs

    Deploy Your Application

    Click Deploy to build and launch Hitobito.

    Run Database Setup

    After deployment, run migrations:

    Terminal window
    bundle exec rails db:migrate
    bundle exec rails db:seed

    Access Your Instance

    Navigate to your app URL and log in with the default admin account.

Initial Configuration

Admin Setup

  1. Log in with default credentials
  2. Change admin password immediately
  3. Configure organization settings

Group Structure

Define your organization’s hierarchy:

  1. Go to Groups
  2. Create top-level group
  3. Add sub-groups
  4. Define group types

Role Configuration

Set up roles for your organization:

  1. Define role types
  2. Set permissions per role
  3. Configure role requirements

Member Management

Adding People

  1. Go to People
  2. Click “New Person”
  3. Enter details:
    • Name
    • Contact information
    • Group memberships
    • Roles
  4. Save person

Group Memberships

Assign people to groups:

  • Primary group
  • Additional groups
  • Role in each group
  • Membership dates

Role Assignment

Roles determine permissions:

  • Leaders
  • Members
  • Administrators
  • Custom roles

Event Management

Creating Events

  1. Go to Events
  2. Click “New Event”
  3. Enter:
    • Title
    • Dates
    • Location
    • Description
    • Max participants
  4. Configure registration

Course Management

For training events:

  1. Create course type
  2. Add prerequisites
  3. Track completions
  4. Issue certifications

Registrations

Manage event participation:

  • Online registration
  • Waiting lists
  • Attendance tracking
  • Confirmation emails

Mailing Features

Mailing Lists

Create distribution lists:

  1. Go to Mailing Lists
  2. Create list
  3. Define subscribers (by group/role)
  4. Configure settings

Bulk Mailings

Send emails to groups:

  1. Select recipients
  2. Compose message
  3. Send or schedule

Export Features

People Exports

Export member data:

  • CSV format
  • PDF lists
  • Labels for printing

Event Exports

Export event data:

  • Participant lists
  • Attendance reports
  • Financial summaries

Invoicing

Creating Invoices

  1. Go to Invoices
  2. Create invoice
  3. Add line items
  4. Send to member

Payment Tracking

Track payments:

  • Mark as paid
  • Partial payments
  • Payment reminders

Wagon System

Organization-Specific Features

Hitobito uses “wagons” for customization:

  • Custom fields
  • Additional roles
  • Specific workflows
  • Branding

Available Wagons

  • PBS (Pfadibewegung Schweiz)
  • CEVI
  • Jubla
  • Generic

API Access

REST API

Hitobito provides a REST API:

Terminal window
# Authenticate
curl -X POST https://your-app.klutch.sh/oauth/token \
  -d "grant_type=password&username=user&password=pass"


# Get people
curl -H "Authorization: Bearer TOKEN" \
  https://your-app.klutch.sh/api/people

JSON:API Format

API follows JSON:API specification for consistent responses.

Security Considerations

Data Privacy

Hitobito handles personal data:

  • Configure retention policies
  • Enable consent tracking
  • Implement data export
  • Support right to deletion

Access Control

Review permissions:

  • Audit role access
  • Limit admin accounts
  • Review group access

Backup Strategy

Database Backup

Regular PostgreSQL backups:

Terminal window
pg_dump hitobito_production > backup.sql

File Backup

Back up uploaded files from /app/storage.

Troubleshooting

Application Errors

  • Check Rails logs
  • Review stack traces
  • Verify database connection

Performance Issues

  • Optimize database queries
  • Enable caching
  • Review background jobs

Email Delivery

  • Verify SMTP settings
  • Check email logs
  • Test with simple message

Additional Resources

Conclusion

Deploying Hitobito on Klutch.sh provides a professional member management solution for associations and organizations. With comprehensive features for people management, events, and communication, Hitobito serves as a central hub for organizational administration.

The combination of Hitobito’s powerful features and Klutch.sh’s reliable hosting creates an ideal platform for managing membership organizations of any size.