Koha LMS Installation Guide on Linux (Debian/Ubuntu)
This document provides a clear, step-by-step, production-oriented guide to install Koha Integrated Library Management System (LMS) on a Linux server, specifically Debian or Ubuntu. Koha officially recommends Debian-based systems and this guide follows best practices used in real-world library deployments.
1. System Requirements
Hardware (Minimum Recommended)
- CPU: 2 cores
- RAM: 4 GB (8 GB recommended for production)
- Disk: 50 GB+
Software
- Debian 11 / 12 or Ubuntu 20.04 / 22.04
- Root or sudo access
- Static IP address (option but recommended)
- MariaDB installed and set up
2. Update the System
sudo apt update && sudo apt upgrade -y
sudo reboot3. Notes Before Installation
- Server hostname configuration is not covered here as it can be handled directly via DNS.
- Ensure your server IP resolves correctly to the domain/subdomain you plan to use for Koha.
- Run all commands as a user with sudo privileges.
4. Install Required Dependencies
sudo apt install -y gnupg curl ca-certificates wget5. Add Koha Repository
Import Koha GPG Key
wget -qO- https://debian.koha-community.org/koha/gpg.asc \
| sudo gpg --dearmor -o /usr/share/keyrings/koha.gpg
Add Repository
Debian
Debian 11 / 12 and Ubuntu (20.04 / 22.04)
echo "deb [signed-by=/usr/share/keyrings/koha.gpg] https://debian.koha-community.org/koha stable main" \
| sudo tee /etc/apt/sources.list.d/koha.listUpdate package list:
sudo apt update6. Install Koha
sudo apt install -y koha-common7. Configure Apache
Enable required Apache modules:
sudo a2enmod rewrite cgi headers proxy_http
sudo systemctl restart apache2Edit Koha configuration:
sudo nano /etc/koha/koha-sites.confUpdate:
INTRAPORT="80"
INTRAPORT="8080"
INTRAPREFIX=""Restart Apache:
sudo systemctl restart apache28. Create a Koha Library Instance
sudo koha-create --create-db libraryCheck status:
sudo koha-list9 Why koha-list is “command not found”
This is normal on newer Debian / Koha packages.
Reason:
Koha admin commands are not in your default PATH.
They live in:
/usr/sbin/Fix (temporary):
sudo /usr/sbin/koha-listFix (permanent – recommended):
echo 'export PATH=$PATH:/usr/sbin' >> ~/.bashrc
source ~/.bashrcNow:
koha-listYou should see:
library10. Get Admin Password
sudo koha-passwd libraryOutput (should get something like) :
Username for library: koha_library
Password for library: Z+=hW2PY9oN{l-yB
Press enter to clear the screen...11. Access Koha Web Interfaces
Staff Interface
http://your-server-ip:8080OPAC (Public Interface) - Dont do this util until u set up the staff interface
http://your-server-ipLogin:
- Username: (from previous step)
- Password: (from previous step)
12. Post-Installation (Very Important)
After logging in to the Staff Interface for the first time:
-
Complete the Koha Web Installer
-
Choose your bibliographic framework:
- MARC21 (most common)
- UNIMARC (mainly Europe)
-
Install:
- Default system preferences
- Sample libraries (optional)
- Authorized values
-
Configure:
- Circulation rules
- Patron categories
- Item types
-
Set up SMTP email for notices and passwords
Do not skip this section, as Koha will not function correctly without proper configuration.
13. Useful Koha Commands
sudo koha-list
sudo koha-start library
sudo koha-stop library
sudo koha-restart library
sudo koha-remove library14. Logs and Troubleshooting (First Place to Check)
Apache Logs
/var/log/apache2/Koha Logs
/var/log/koha/library/Common Issues
- Missing Apache modules
- Plack not running
- Database permission errors
15. Backup (Recommended)
sudo koha-dump libraryBackups stored in:
/var/spool/koha/library/16. Security Best Practices
- Enable firewall (UFW)
- Use HTTPS (Let’s Encrypt)
- Regular backups
- Keep system updated
17. Official Resources
Author: Amruth L P Purpose: Production-ready Koha LMS deployment on Linux