Installing Koha, the open-source integrated library system, can be challenging for libraries looking for a stable, secure, and fully functional setup. This guide provides a step-by-step, production-ready installation process for Koha 25.11 on Ubuntu 24.04 LTS and Ubuntu 25, including HTTPS configuration, firewall setup, superlibrarian creation, and automated backups.
Following this guide ensures your Koha system is secure, reliable, and ready for daily library operations.
Why Koha 25.11 on Ubuntu?
- Koha 25.11 is the latest stable release, packed with new features and security updates.
- Ubuntu 24.04 LTS is ideal for production servers due to long-term support.
- Ubuntu 25 can be used for modern setups where newer packages are required.
- Using official repositories and best practices ensures a maintainable and production-ready system.
Prerequisites
Before starting, make sure your server meets these requirements:
- Operating System: Ubuntu 24.04 LTS or Ubuntu 25
- User Privileges: Root or sudo access
- System Resources: Minimum 2 GB RAM and 20 GB disk space (4 GB+ recommended)
- Connectivity: Stable internet connection
- Optional: SSH access for remote management
A clean Ubuntu server installation is recommended to avoid conflicts with Apache, MariaDB, or other services.
Step 1: Update Ubuntu & Install Dependencies
Update the system and install necessary packages:
sudo apt update && sudo apt upgrade -y
sudo apt install wget gnupg lsb-release software-properties-common apache2 mariadb-server mariadb-client certbot python3-certbot-apache ufw unzip perl libapache2-mod-perl2 -y
Enable and start Apache and MariaDB:
sudo systemctl enable apache2 mariadb
sudo systemctl start apache2 mariadb
Step 2: Add Koha Official Repository
For Ubuntu 25+ and 24.04, modern key handling is required:
wget -q -O- https://debian.koha-community.org/koha/gpg.asc | gpg --dearmor | sudo tee /usr/share/keyrings/koha-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/koha-archive-keyring.gpg] http://debian.koha-community.org/koha stable main" | sudo tee /etc/apt/sources.list.d/koha.list
sudo apt update
This ensures installation of Koha 25.11 from the official repository.
Step 3: Install Koha Packages
Install Koha core and web interface:
sudo apt install koha-common koha-web -y
koha-commoninstalls core library files, andkoha-webprovides the staff interface and OPAC.
Step 4: Secure MariaDB
Run the MariaDB secure installation tool:
sudo mysql_secure_installation
Follow the prompts to set the root password, remove anonymous users, and secure your database.
Step 5: Create Koha Database
Create a dedicated database and user for Koha:
KOHA_DB_USER="kohauser"
KOHA_DB_PASS="StrongDBPass123"
sudo mysql -u root -p <<MYSQL
CREATE DATABASE kohadb;
GRANT ALL PRIVILEGES ON kohadb.* TO '${KOHA_DB_USER}'@'localhost' IDENTIFIED BY '${KOHA_DB_PASS}';
FLUSH PRIVILEGES;
EXIT;
MYSQL
Use strong passwords for production environments.
Step 6: Create Koha Site
Create and enable your Koha site:
KOHA_SITE="mylibrary"
sudo koha-create --create-db $KOHA_SITE
sudo a2ensite $KOHA_SITE
sudo systemctl restart apache2
Step 7: Preconfigure Superlibrarian Account
Create a default superlibrarian to bypass manual web installer:
SUPERLIB_USER="admin"
SUPERLIB_PASS="AdminPass123"
SUPERLIB_EMAIL="admin@example.com"
sudo koha-sysadmin --create-user $SUPERLIB_USER --password $SUPERLIB_PASS --email $SUPERLIB_EMAIL --site $KOHA_SITE
Remember to change passwords before going live.
Step 8: Configure Firewall
Enable UFW firewall to secure the server:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
Step 9: Enable HTTPS with Let’s Encrypt
Obtain a free SSL certificate for your domain:
read -p "Enter your domain (e.g., library.example.com): " DOMAIN
sudo certbot --apache -d $DOMAIN --non-interactive --agree-tos -m $SUPERLIB_EMAIL
All Koha traffic will now be served securely via HTTPS.
Step 10: Set Up Automated MariaDB Backups
Back up the Koha database daily at 2 AM:
BACKUP_DIR="/var/backups/koha"
mkdir -p $BACKUP_DIR
echo "0 2 * * * root /usr/bin/mysqldump -u $KOHA_DB_USER -p$KOHA_DB_PASS kohadb > $BACKUP_DIR/kohadb_\$(date +\%F).sql" | sudo tee /etc/cron.d/koha_backup
Step 11: Verify Services
Check that all services are running:
sudo systemctl status apache2
sudo systemctl status mariadb
sudo systemctl status koha-common
Step 12: Access Koha
- Staff Interface:
https://<your-domain> - OPAC:
https://<your-domain> - Superlibrarian username:
admin - Superlibrarian password:
AdminPass123
Use the official Koha manual for any additional configuration: Koha Installation Wiki
Best Practices for Production
- Change all default passwords immediately.
- Enable automatic security updates for Ubuntu.
- Monitor backups and server health regularly.
- Keep Koha and all dependencies updated for security and stability.
Automate database and configuration backups. Regular backups are critical for preventing data loss.
Troubleshooting Common Issues
| Problem | Likely Cause | Solution |
|---|---|---|
| Errors with database access | Incorrect credentials | Verify the username/password in koha-conf.xml |
| Ports 8080/8081 blocked | Firewall or another service | Allow ports via firewall & check conflicts |
| Missing Perl modules | Package dependencies issues | Install required modules manually |
Why This Method Is Recommended
✔ Based on official Koha installation procedures for Debian/Ubuntu — see Koha community documentation.
✔ Uses stable package management (APT) instead of manual builds, which is more reliable and maintainable.
✔ Supports the latest Koha 25.11 release with regular updates.
Final Notes
- Ubuntu 24.04 LTS remains the most stable and support‑friendly base OS for production Koha installations.
- Ubuntu 25 can be used for testing or environments where newer packages are needed, but keep in mind its shorter support lifecycle.
- Always follow the official Koha manual and wiki for updates or version‑specific change
