How to Fix High Server Load in Koha ILS on Ubuntu

If your Koha ILS server is experiencing extremely high CPU or memory usage, a slow OPAC or staff interface, or processes such as mysqld and opac-search.pl being killed, the problem may be caused by insufficient RAM or swap, excessive CGI processes, incorrect Plack configuration, resource-intensive indexing jobs, or database configuration issues.

This guide explains how to diagnose and fix common Koha performance problems on Ubuntu, including how to check system resources, configure swap, enable Plack, review cron jobs, optimize MariaDB, and verify the results.

---

1. Diagnose the Problem

Check System Load and Processes

uptime top htop

Check the load average, CPU usage, memory usage, and processes consuming the most resources.

Check RAM and Swap

free -h

If RAM is almost completely used and swap is also heavily utilized, the server may be experiencing memory pressure.

sudo dmesg -T | grep -i -E 'out of memory|oom|killed process' sudo journalctl -k | grep -i -E 'out of memory|oom|killed process'

These commands can help identify whether the Linux OOM killer has terminated processes because the server ran out of memory.

Check Koha Processes

ps aux --sort=-%mem | head -30

Check whether a large number of Koha CGI processes are running:

ps aux | grep '[o]pac-search.pl' | wc -l ps aux | grep '[o]pac-detail.pl' | wc -l

A large number of CGI processes can consume significant memory and CPU resources. If your Koha installation uses Plack, excessive CGI processes may indicate that the configuration needs to be reviewed.

Check Zebra and Indexing Processes

ps aux | grep '[z]ebra' ps aux | grep '[r]ebuild_zebra' grep -R "rebuild" /etc/cron* -n 2>/dev/null

Full indexing operations can consume significant CPU, memory, and disk I/O. Check whether indexing jobs are running during busy periods or more frequently than required.

---

2. Fix the Problem

Add Swap

Swap provides additional memory capacity when RAM is temporarily exhausted. If your server does not already have an appropriate swap file, you can create an 8 GB swap file:

sudo fallocate -l 8G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile

Verify the configuration:

swapon --show free -h

Make the swap file persistent after reboot:

echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

You can also configure Linux swappiness:

echo 'vm.swappiness=10' | sudo tee /etc/sysctl.d/99-koha-memory.conf sudo sysctl --system

Enable Plack

Plack allows Koha to use persistent application processes instead of creating a new CGI process for every request. This can significantly improve performance under concurrent traffic.

sudo koha-plack --enable library sudo koha-plack --start library

Replace library with your actual Koha instance name.

Check the running Plack processes:

ps aux | grep '[s]tarman' ps aux | grep '[p]lack'

Review Koha Cron Jobs

sudo ls -l /etc/cron.d/ sudo grep -R "koha" /etc/cron.d/ 2>/dev/null

Identify resource-intensive jobs such as full indexing, backups, report generation, and batch processing. Schedule these jobs during periods of lower server activity whenever possible.

Tune MariaDB

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

For a server with limited resources, you can configure values such as:

[mysqld] innodb_buffer_pool_size = 1G max_connections = 60

Restart MariaDB after making changes:

sudo systemctl restart mariadb

Monitor memory usage after changing these settings to ensure MariaDB is not consuming too much of the server’s available RAM.

---

3. Verify the Changes

Check Plack

ps aux | grep '[s]tarman'

Plack workers should be running for the configured Koha instance.

Check Swap

free -h swapon --show

Confirm that the configured swap space is available.

Check Server Load

uptime htop free -h

Monitor CPU, RAM, swap, and load average during normal usage. A healthy server should not show sustained CPU saturation, continuous heavy swapping, or memory exhaustion.

Check Service Logs

sudo journalctl -p warning..alert --since "1 hour ago" sudo journalctl -u apache2 --since "1 hour ago" sudo journalctl -u mariadb --since "1 hour ago"

Look for repeated errors, worker failures, database connection problems, and other issues that may affect performance.

---

4. Koha Performance Checklist

• Monitor CPU, RAM, swap, and disk I/O.
• Check for OOM-killer messages.
• Identify excessive Koha CGI processes.
• Enable and verify Plack.
• Review indexing and background jobs.
• Schedule resource-intensive jobs during off-peak hours.
• Configure MariaDB according to available RAM.
• Monitor the server after configuration changes.
• Keep Koha and its supporting software updated.

---

Conclusion

High server load on a Koha installation can be caused by memory pressure, excessive CGI processes, database workload, indexing jobs, or other resource-intensive tasks.

Start by identifying the actual bottleneck with htop, free -h, process monitoring, and system logs. Then apply targeted changes such as adding appropriate swap, enabling Plack, adjusting background jobs, and tuning MariaDB.

After making changes, monitor the server during normal usage to confirm that CPU, memory, database, and Koha processes remain within acceptable limits.