Deploying Koha

Introduction

Koha is the world’s first free and open-source Integrated Library System (ILS), used by thousands of libraries globally. From small community libraries to large academic institutions, Koha provides a complete solution for cataloging, circulation, patron management, acquisitions, and serials management.

Originally developed in New Zealand in 1999, Koha has grown into a mature, feature-rich platform with an active global community. The name “Koha” is a Maori word meaning a gift or contribution, reflecting its open-source nature.

Key highlights of Koha:

Cataloging: Full MARC21 and UNIMARC support with Z39.50/SRU search
Circulation: Check-in, check-out, holds, and transfers
Patron Management: Member registration, history, and messaging
OPAC: Public catalog with advanced search and user accounts
Acquisitions: Budgeting, ordering, and vendor management
Serials: Subscription and claiming management
Reports: Extensive reporting and SQL-based custom reports
Course Reserves: Manage course reading lists
Plugins: Extensible architecture for customization
SIP2 Support: Integration with self-checkout systems
Multi-Branch: Support for library consortiums

This guide walks through deploying Koha on Klutch.sh using Docker, understanding the architecture, and performing initial library setup.

Why Deploy Koha on Klutch.sh

Deploying Koha on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the complex Perl/Apache/MySQL stack automatically.

Persistent Storage: Store your library database and configuration persistently.

HTTPS by Default: Secure access for staff and patrons with automatic SSL.

Always Available: Your library catalog is online 24/7 for patron access.

Scalable Resources: Adjust resources based on collection size and traffic.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and library systems concepts
A MySQL/MariaDB database

Important Considerations

Koha is a complex, enterprise-grade application:

Resource Intensive: Requires significant memory for Perl and Zebra
Multiple Services: Runs web server, indexer, and background jobs
Initial Setup Time: First run includes database initialization

Plan for adequate resources and initial configuration time.

Preparing Your Repository

Repository Structure

koha-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

FROM koha/koha:latest

# Environment variables for database connection
ENV MYSQL_HOST=${MYSQL_HOST}
ENV MYSQL_PORT=${MYSQL_PORT:-3306}
ENV MYSQL_DATABASE=${MYSQL_DATABASE}
ENV MYSQL_USER=${MYSQL_USER}
ENV MYSQL_PASSWORD=${MYSQL_PASSWORD}

# Koha instance name
ENV KOHA_INSTANCE=${KOHA_INSTANCE:-library}

# Volumes:
# /var/lib/koha - Koha data files
# /etc/koha - Configuration files

EXPOSE 8080 8081

Environment Variables Reference

Variable	Required	Description
`MYSQL_HOST`	Yes	MySQL/MariaDB host
`MYSQL_PORT`	No	MySQL port (default: 3306)
`MYSQL_DATABASE`	Yes	Database name
`MYSQL_USER`	Yes	Database username
`MYSQL_PASSWORD`	Yes	Database password
`KOHA_INSTANCE`	No	Koha instance name (default: library)
`KOHA_DOMAIN`	No	Domain for Koha

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Deploying Koha on Klutch.sh

Set Up MySQL Database

Koha requires MySQL/MariaDB with specific settings:

CREATE DATABASE koha CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'koha'@'%' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON koha.* TO 'koha'@'%';
GRANT SUPER ON *.* TO 'koha'@'%';
FLUSH PRIVILEGES;

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore
git commit -m "Initial Koha deployment configuration"
git remote add origin https://github.com/yourusername/koha-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Koha repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8080 (Staff interface)

Note: You may need separate apps for OPAC (8081) and staff (8080).

Set Environment Variables

Variable	Value
`MYSQL_HOST`	Your database host
`MYSQL_USER`	`koha`
`MYSQL_PASSWORD`	Your database password
`MYSQL_DATABASE`	`koha`
`KOHA_INSTANCE`	`library`

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
`/var/lib/koha`	10 GB	Koha data and indexes
`/etc/koha`	1 GB	Configuration files

Deploy Your Application

Click Deploy to start the build process. Initial setup may take several minutes.

Access Koha

Once deployment completes:

Staff interface: https://your-app-name.klutch.sh
OPAC (if configured): https://opac.your-app-name.klutch.sh

Initial Library Setup

Web Installer

On first access, you’ll be guided through:

Database Setup: Koha creates necessary tables
MARC Framework: Select your cataloging standard
Sample Data: Optionally load sample data for testing
Admin User: Create your superlibrarian account

Essential Configuration

After installation, configure:

Library Branches: Add your library locations
Patron Categories: Define membership types
Item Types: Set up material types
Circulation Rules: Configure loan periods and limits

System Preferences

Navigate to Administration > System Preferences to configure:

OPAC appearance and behavior
Circulation policies
Email notifications
Search settings

Core Features

Cataloging

Create and manage bibliographic records:

Navigate to Cataloging
Add new record or import via Z39.50
Add items (holdings) to records
Records appear in OPAC immediately

Circulation

Manage lending activities:

Check Out: Scan patron card, then items
Check In: Return items and handle transfers
Holds: Place and manage reservations
Fines: Track and manage overdue fines

Patron Management

Administer library members:

Go to Patrons
Add new patrons or search existing
View borrowing history and current checkouts
Manage messages and notifications

OPAC

The public catalog provides:

Advanced search capabilities
Patron account access
Hold requests
Virtual shelves/lists
Ratings and reviews

Advanced Features

Zebra Search Engine

Koha uses Zebra for full-text searching:

Automatic indexing of records
Boolean and keyword searches
Faceted search results

Elasticsearch (Optional)

For larger collections:

Better performance at scale
Enhanced search relevancy
Facet aggregations

SIP2 Integration

Connect self-checkout machines:

Configure SIP2 server settings
Set up terminal authentication
Test with your self-checkout hardware

Production Best Practices

Data Protection

Regular Backups: Back up MySQL and data volumes
Patron Privacy: Review data retention policies
Export Capabilities: Regularly export MARC records

Performance

Indexing: Ensure Zebra indexes are current
Database Optimization: Periodic optimization of MySQL
Memory Allocation: Koha benefits from available memory

Security

Staff Permissions: Use granular permission system
Strong Passwords: Enforce password policies
SSL/TLS: Always use HTTPS (automatic with Klutch.sh)

Troubleshooting Common Issues

Database Connection Errors

Solutions:

Verify MySQL credentials and permissions
Ensure database server is accessible
Check that SUPER privilege is granted

Search Not Working

Solutions:

Verify Zebra indexer is running
Rebuild indexes with rebuild_zebra.pl
Check Zebra configuration

Slow Performance

Solutions:

Increase allocated memory
Optimize MySQL settings
Consider Elasticsearch for large collections

Additional Resources

Conclusion

Deploying Koha on Klutch.sh gives you a complete, open-source library management system with automatic builds and persistent storage. While Koha has significant complexity befitting a full ILS, Klutch.sh simplifies the infrastructure management, letting you focus on serving your library patrons.

Whether running a small community library or a multi-branch system, Koha on Klutch.sh provides the professional tools needed for modern library services.