✦ Koha • Debian • Ubuntu • Windows 10/11

The best free library system, now without the hassle.

koha.nexus is a smart, free, and easy-to-use assistant for installing, configuring, maintaining, and extending the Koha Integrated Library System via a friendly and guided dashboard.

Start installation → View on GitHub Full README
22 languagesDashboard & Koha packages
2 systemsLinux or Windows via WSL 2
16+ featuresManagement, tools & tools
GPL-3.0+Free & modifiable software
installation — terminal 
$ wget https://raw.githubusercontent.com/PauloFBaldiFH/koha.nexus/refs/heads/main/installer
$ sudo bash installer

KOHA.NEXUS
✓ Validating server...
✓ Installing Koha
✓ Configuring database
✓ Preparing backups
✓ Configuring access

→ Dashboard ready: sudo config.sh
All in one place

A dashboard built for those who keep the library running.

From the initial installation to backups, indexing, security, migration, cataloging, and web publishing, the core features are gathered in a single control point.

Guided installation

System, disk, network, and port pre-validation; installation and tuning of Koha, MariaDB, Apache, Memcached, and Plack, plus SWAP, NTP, and timezone.

Backup hub

Compressed SQL backups, MARC21 exports, manual copies, and optional integration with Google Drive via rclone.

Safe restore

Backups are validated and tested in a temporary database before any replacement of the current catalog.

Search & indexing

Switch between Zebra and Elasticsearch 7, indexer watchdog, and tools for index repair and rebuild.

Web publishing

Cloudflare Tunnel without needing to open router ports, Certbot for SSL, and Google Search Console assistant.

Security

Fail2ban, UFW firewall, options to restrict staff access on port 8080, and database password rotation.

Library tools

Data import, SQL reports, catalog quality checks, GDPR/LGPD privacy tools, annual patron category rollover, and more.

Brazil localization

CPF validation, Pimaco labels, catalog cards, holidays, official census reports, and ABNT bibliographic references.

WhatsApp & Telegram

Delivery of Koha notices through WhatsApp gateways or a Telegram bot, completely optional.

Assisted cataloging

PHA or Cutter-Sanborn, DDC, Cutter calculator, safe MARC record replacement, and AI assistance.

Windows + WSL 2

Run Koha on a single Windows PC, complete with desktop shortcuts, notifications, system tray, and diagnostic tools.

Auto-update

Dashboard updates straight from GitHub with SHA-256 installer verification.

Start here

Linux installation in a few commands.

The project targets Debian 11/12/13 or Ubuntu 22.04/24.04 on amd64 or arm64 architecture, and can also run on Windows via WSL 2.

Direct installer

Download the current installer script and run it with administrative privileges.

bash 
wget https://raw.githubusercontent.com/PauloFBaldiFH/koha.nexus/refs/heads/main/installer
sudo bash installer

Clone the repository

You can also keep translation files alongside the script to work offline.

bash 
git clone https://github.com/PauloFBaldiFH/koha.nexus.git
cd koha.nexus
sudo bash installer

Minimum requirements

  • Debian 11/12/13 or Ubuntu 22.04/24.04, 64-bit
  • 2 GB of RAM; 4 GB or more recommended
  • 5 GB free space; 10 GB or more recommended
  • root or user with sudo privileges
  • Internet access for Koha repositories
  • Ports 80 and 8080 available

After installation

  • Open the staff interface at http://SERVER-IP:8080
  • Complete the Koha Web Installer
  • Create your super librarian via the dashboard
  • The public catalog is at http://SERVER-IP:80
  • Reopen the dashboard anytime with sudo config.sh
Windows 10 / 11

A full Koha environment on a single PC, using WSL 2.

The Windows edition is designed for small libraries, training, and evaluation, keeping Koha services inside Debian on WSL 2 while offering native Windows tools.

WINDOWS INSTALLER

Install Koha with two clicks.

Download Install-Koha.cmd directly from the official repository and run it. It launches the PowerShell installer for you.

⬇ Download Install-Koha.cmd View source on GitHub ↗

Installation

Open PowerShell normally and run:

PowerShell 
[Net.ServicePointManager]::SecurityProtocol='Tls12'; irm https://raw.githubusercontent.com/PauloFBaldiFH/koha.nexus/main/windows/install.ps1 | iex
Easier way: The button above downloads Install-Koha.cmd. No need to open PowerShell manually.
How to enable Virtualization in BIOS:

Restart your PC and repeatedly press the setup key as soon as the screen turns on:

  • Del or F2 — ASUS, Gigabyte, MSI, ASRock, Acer
  • F10 or Esc — HP / Compaq
  • F2 or F12 — Dell
  • F1, F2 or Enter — Lenovo

Inside the BIOS, find Intel Virtualization Technology (VT-x) or AMD SVM / AMD-V (under Advanced, CPU Configuration, or Overclocking), switch it to Enabled, and press F10 to save.

Can't access BIOS via keys? In Windows, go to Settings → System → Recovery → Advanced startup (Restart now) → Troubleshoot → Advanced options → UEFI Firmware Settings.

WSL 2 Debian systemd Windows Terminal Notifications System tray
1

System check

Verifies a compatible Windows version, 64-bit architecture, memory, free space, and BIOS virtualization.

2

WSL 2 + Debian

Installs WSL 2, prepares Debian, and configures the administrative user and systemd.

3

Koha Environment

Installs Koha inside Debian and creates Windows shortcuts, scheduled tasks, and control tools.

4

Library network

Configures access for other computers on the local network and tests ports 80 and 8080.

5

Daily operation

Start, Stop, Restart, status, diagnostics, index rebuild, and safe shutdown are accessible without opening a console.

Notifications

Crashes, recoveries, backups, low disk space, and unclean shutdowns trigger native Windows alerts.

1-Click Diagnostics

Exports logs and useful information for support, securely removing passwords, tokens, and keys.

Safe shutdown

Koha is shut down in stages before WSL and Windows power off to prevent data corruption.

Library tools

More than installing Koha: taking care of the collection.

The dashboard tools utilize Koha's own mechanisms and follow a strict protection flow with locking, previewing, confirmation, and verified backups before any data is altered.

Magic Import Tool

A single entry point for spreadsheets, MARC files, compressed archives, collections, items, patrons, and circulation data.

CSV • TSV • XLSX • ODS • DBF • MARC21 • MARCXML

Undo MARC import

Allows reverting a batch import in a controlled manner, preserving catalog integrity.

SQL Reports Pack

Read-only reports for loans, overdues, acquisitions, missing barcodes, items never borrowed, and lost items.

Category rollover

Moves patrons between categories using criteria defined by the library, with a dry run before execution.

Data quality

Runs catalog inconsistency checks without altering the actual records.

Privacy & GDPR/LGPD

Anonymizes old borrowing histories and securely deletes expired patrons that meet defined criteria.

Protection by default: Operations that alter data follow a shared lock with backups, previews, confirmations, and a verified PRE-* copy before making changes.
Cataloging

PHA, Cutter-Sanborn, DDC, and AI working alongside the cataloger.

The project brings together helper tools for classification, author notation, Cutter calculation, and safe MARC record replacement, without removing the professional review step.

Author notation

Uses the library's own PHA or Cutter-Sanborn table and highlights numbers already used in the catalog.

DDC lookup

Searches by number or subject from a local copy of the library's DDC, integrated with the cataloging form.

Cutter Calculator

Calculates notation, suggests classes based on the catalog, and can auto-fill 090, 092, or the item call number field.

Replace a MARC record

Replaces a record via MARC or XML through preview, transactional lock, and saving the previous version.

AI cataloging

Receives photos of the cover, title page, and verso, generating a record proposal applying cataloging rules before human review.

Local or Cloud Models

Supports OpenAI-compatible services and local models via Ollama or LM Studio, without storing tokens in the dashboard.

AI Cataloging Workflow

  • Book photos and optional instructions
  • Structured JSON response
  • Application of AACR2/ISBD and MARC rules
  • Review by the librarian/operator
  • Mandatory preview before saving
  • Record and model response can be preserved for auditing

Important Principle

The AI functions as a cataloging assistant. The generated proposal is reviewed and only then sent to Koha. The project also includes strict prompts to prevent hallucinating fields not supported by the photographs or context.
Brazil: localization

Features tailored for the daily routine of Brazilian libraries.

The Brazilian localization features are opt-in: nothing is applied automatically during installation or by schedule.

FeatureWhat it offersProtection
CPF Validation Audits CPF (National ID) using check digits and identifies shared numbers. Read-only until confirmation
Pimaco Labels Templates for A4 and Letter sheets, including spine, barcode, and title. PRE-LABELS
Catalog Card Generates catalog cards in the style used by Brazilian libraries, integrated into the record view. PRE-FICHA
Brazilian Calendar National holidays and floating dates, with an option for municipal holidays. PRE-CALENDAR
Census Reports Reports for indicators related to MEC, INEP, IBGE, and SNBP based on Koha data. PRE-CENSO
ABNT NBR 6023:2018 Generates references and bibliographies from MARC21 records in HTML and plain text. Read-only
Note: Census data represents what is registered in Koha. The README recommends cross-checking every result against official forms before submission.
Operation & Security

Automation without hiding what's going on.

The dashboard centralizes recurring tasks and highlights important points for maintenance, diagnostics, and recovery.

Standard Automation

WhenTask
Daily 23:00Compressed SQL backup and optional cloud upload
Sundays 03:00MARC21 export
Daily 01:30Session and Zebra queue cleanup
Daily 05:00Plack restart
Every 2 minZebra indexer watchdog
Every 5 minElasticsearch watchdog, when used

Important Files

  • /root/koha_credentials.txt — initial credentials
  • /var/backups/koha_sql — SQL backups
  • /var/backups/koha_marc — MARC backups
  • /etc/koha-easy-install/ — dashboard settings
  • /var/log/koha-easy-install/ — dashboard and validation logs
  • ~/importar — input folder for the Magic Import Tool

Diagnostics

The dashboard gathers status, health checks, Apache logs, deep database maintenance, and ready-to-use reports for support.

health check Apache logs MariaDB Koha logs

Power Failure

The project includes verification after an unclean reboot, creates a new backup, and updates the index when necessary. On Windows, the safe shutdown routine attempts to stop Koha gracefully before the system shuts down.

Uninstallation is destructive: The uninstall.sh script permanently removes Koha, databases, local backups, and configurations. Backup your data off-server before using it.
Public Network

Libraries using koha.nexus

Explore the public catalogs maintained by our partner institutions. Search engines follow these links to automatically discover and index their collections.

Fetching catalogs on the koha.nexus network...
Open Source

Built to be used, studied, and improved.

The project includes tests, translations, collaboration tools, and installer checksum verification for automatic updates.

Tests

Bats test suite for backup/restore, indexing, library tools, WSL, and Windows components.

Translations

Versioned dictionaries by language, coverage validation, and automatic rejection of translations missing variables.

Verification

The installer uses SHA-256 to securely validate its own updates.

License

GNU General Public License v3.0 or later (GPL-3.0-or-later). The project can be used, studied, shared, and modified. Modified distributions must remain under GPL and make the corresponding source code available. The software is provided without warranty.