If you’re running Koha ILS on an Ubuntu server and notice extreme server load, slow OPAC/staff interface, or killed processes like mysqld or opac-search.pl, you’re likely facing an overload caused by Apache CGI mode, low swap space, or Zebra indexing misconfiguration.
This guide shows you how to debug, fix, and verify performance issues on a Koha server, especially with Ubuntu 20.04 LTS.
🧩 1. How to Debug
Start by checking the system’s resource usage. Use these commands:
🔍 Check system load and processes
uptime
top
htop
If load is 50, 100, or higher, the system is under fatal strain.
🔍 Check memory and swap usage
free -h
If swap is full and RAM is nearly 100% used, you’re close to crashing.
Example bad output:
Mem: 7.8G used / 120M free
Swap: 511M used / 2M free
🔍 Look for runaway Koha processes
ps aux --sort=-%mem | head
If you see hundreds of opac-search.pl or opac-detail.pl processes, Koha is still running in CGI mode, not Plack — a major performance killer.
🔍 Check Zebra indexing tasks
ps aux | grep zebra
grep -R "rebuild" /etc/cron* -n
If rebuild_zebra.pl is running multiple times or during the day, it may be overloading the server.
🛠️ 2. How to Fix
✅ A. Add More Swap (Essential!)
Low swap is a common cause of process crashes and system freezes. Add 8 GB swap:
sudo swapoff -a
sudo rm -f /swapfile
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
✅ B. Enable Plack (Major Performance Boost)
sudo koha-plack --enable library
sudo a2enmod headers proxy_http
sudo koha-plack --start library
sudo a2dismod cgi
sudo systemctl restart apache2
⚠️ Replace
librarywith your actual Koha instance name if different.
Plack replaces slow CGI processes with fast, persistent workers.
✅ C. Optimize Koha Cron Jobs
Edit main cron file:
sudo nano /etc/cron.d/koha-common
Use this safe schedule:
*/5 * * * * koha-indexer --instance library --quiet
0 3 * * * koha-rebuild-zebra -v -f library
*/10 * * * * koha-foreach --enabled --command "/usr/share/koha/bin/build_holds_queue.pl"
0 * * * * koha-foreach --enabled --command "/usr/share/koha/bin/cronjobs/overdue_notices.pl"
0 2 * * * koha-run-backups --days 7
Reload cron:
sudo systemctl reload cron
✅ D. Tune MySQL for 8GB RAM
Edit MySQL config:
sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf
Add:
[mysqld]
innodb_buffer_pool_size = 1024M
max_connections = 60
Restart:
sudo systemctl restart mariadb
✅ 3. How to Verify
✅ Check Plack is running:
ps aux | grep plack
You should see:
starman master ...
starman worker ...
(No more opac-search.pl everywhere ✅)
✅ Check new swap status:
free -h
Look for:
Swap: 8.0G 0B used 8.0G free
✅ Check load and responsiveness:
htop
uptime
A healthy Koha server with Plack should show:
- Load average < 4
- 1–3% CPU for Plack workers
- 5–6 GB RAM free
🎯 Final Tips
- Always enable Plack for Koha — it’s 10x faster and uses far less memory.
- Increase swap for production servers, especially if RAM is <16GB.
- Schedule full Zebra reindex only during off-hours.
- Regularly monitor with
htop,nmon, andjournalctl.
💡 Need Help?
Feel free to comment below or fork this guide for your environment. Koha is a powerful system, but like any enterprise app, it needs tuning to run smoothly under real-world load.
Happy hosting! 🚀