📚 Deploy Koha on Debian VPS for Self-Hosted Library Management System

This article provides a guide to deploy Koha on Debian VPS to run a self-hosted library management system.

What is Koha?

Koha is an open-source integrated library system, used world-wide by public, school and special libraries, as well as in some larger academic libraries.

Below is a production-style Debian VPS guide using Koha’s official Debian package method. Koha recommends Debian/Ubuntu package installation for most installs.

Recommended VPS Specs

For a small library or testing:

• OS: Debian 12 (Bookworm)
• RAM: 4+ GB minimum
• CPU: 2+ vCPU minimum
• Disk: 40+ GB SSD
• Root access: yes
• Domain/subdomain: recommended

For production, use more RAM and SSD storage, especially if you expect many records, staff users, OPAC traffic, or heavy indexing.

Example domains:

OPAC:  library.example.com
Staff: staff.library.example.com

Koha uses Apache, MariaDB/MySQL, Zebra or another search backend, background jobs, caching, and email services, so production deployments need normal Linux server administration, web server, database, backup, and security skills.

Compare Debian VPS Plans

Deploy Koha on Debian VPS

To deploy Koha on Debian VPS, follow the steps below:

1. Point DNS to the VPS

   Create DNS A records:

   library.example.com       A       YOUR_SERVER_IP
   staff.library.example.com A       YOUR_SERVER_IP
   

   Wait for DNS propagation.

   Check:

   dig +short library.example.com
   dig +short staff.library.example.com
   

2. Log in to the VPS

   ssh root@YOUR_SERVER_IP
   

   Update Debian:

   apt update
   apt upgrade -y
   reboot
   

   Log back in:

   ssh root@YOUR_SERVER_IP
   

   Install basic tools:

   apt install -y curl wget gnupg2 ca-certificates lsb-release apt-transport-https vim unzip software-properties-common
   

3. Set Hostname and Timezone

   hostnamectl set-hostname koha-server
   timedatectl set-timezone America/Chicago
   

   Edit hosts file:

   nano /etc/hosts
   

   Add:

   127.0.0.1 localhost
   YOUR_SERVER_IP koha-server
   

4. Add the Koha repository

   Create the Koha keyring:

   wget -qO- https://debian.koha-community.org/koha/gpg.asc | gpg --dearmor > /usr/share/keyrings/koha-keyring.gpg
   

   Add the stable Koha repository:

   echo "deb [signed-by=/usr/share/keyrings/koha-keyring.gpg] http://debian.koha-community.org/koha stable main" > /etc/apt/sources.list.d/koha.list
   

   Update package lists:

   apt update
   

5. Install Koha

   apt install -y koha-common
   

   Check version:

   koha-version
   

6. Install and secure MariaDB

   apt install -y mariadb-server
   systemctl enable --now mariadb
   

   Secure MariaDB:

   mysql_secure_installation
   

   Recommended answers:

   Switch to unix_socket authentication: Y
   Change root password: N, if socket auth is active
   Remove anonymous users: Y
   Disallow root login remotely: Y
   Remove test database: Y
   Reload privilege tables: Y
   

7. Configure Koha defaults

   Open Koha site defaults:

   nano /etc/koha/koha-sites.conf
   

   Recommended basic configuration:

   DOMAIN=".example.com"
   INTRAPORT="8080"
   INTRAPREFIX="staff"
   INTRASUFFIX=""
   OPACPORT="80"
   OPACPREFIX=""
   OPACSUFFIX=""
   DEFAULTSQL=""
   ZEBRA_MARC_FORMAT="marc21"
   ZEBRA_LANGUAGE="en"
   BIBLIOS_INDEXING_MODE="dom"
   AUTHORITIES_INDEXING_MODE="dom"
   USE_MEMCACHED="yes"
   MEMCACHED_SERVERS="127.0.0.1:11211"
   MEMCACHED_NAMESPACE="koha"
   

   For this domain setup:

   OPAC:  library.example.com
   Staff: staff.library.example.com
   

   You may also keep ports if you prefer:

   OPAC:  library.example.com
   Staff: library.example.com:8080
   

   But separate subdomains are cleaner for production.

8. Enable required Apache modules

   a2enmod rewrite cgi headers proxy_http
   systemctl restart apache2
   

   Disable default Apache site:

   a2dissite 000-default
   systemctl reload apache2
   

9. Create a Koha instance

   Use a short instance name, for example library.

   koha-create --create-db library
   

   This creates:

   Koha instance: library
   Database: koha_library
   Config: /etc/koha/sites/library/koha-conf.xml
   Apache config: /etc/apache2/sites-available/library.conf
   

   Enable the Apache site:

   a2ensite library
   systemctl reload apache2
   

10. Check Koha services

    koha-list
    koha-list --enabled
    koha-plack --status library
    koha-zebra --status library
    

    Start services if needed:

    koha-plack --start library
    koha-zebra --start library
    koha-worker --start library
    

    Enable them:

    koha-plack --enable library
    koha-zebra --enable library
    koha-worker --enable library
    

    Restart Apache:

    systemctl restart apache2
    

11. Find the Koha web installer login

    Show the generated database credentials:

    xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/library/koha-conf.xml
    echo
    xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/library/koha-conf.xml
    echo
    

    If xmlstarlet is missing:

    apt install -y xmlstarlet
    

    You can also inspect manually:

    nano /etc/koha/sites/library/koha-conf.xml
    

    Look for:

    koha_library
    ...
    

12. Open firewall ports

    If using UFW:

    apt install -y ufw
    ufw allow OpenSSH
    ufw allow 80/tcp
    ufw allow 443/tcp
    ufw allow 8080/tcp
    ufw enable
    ufw status
    

    If staff runs on a subdomain through port 80/443, you may not need to expose 8080.

13. 14. Visit the Koha web installer

    Open:

    http://staff.library.example.com
    

    Or, if using port mode:

    http://library.example.com:8080
    

    The Koha web installer creates the database tables, loads initial data, and then moves into onboarding. (Koha Community)

    Use the credentials from:

    /etc/koha/sites/library/koha-conf.xml
    

    During setup:

    1. Choose language.
    2. Confirm Perl modules.
    3. Confirm database connection.
    4. Create database tables.
    5. Select MARC flavor, usually MARC21.
    6. Import mandatory sample/default data.
    7. Continue to onboarding.

    Koha’s onboarding tool then walks through creating the first library, patron category, admin patron, item type, and circulation rule.

14. Configure HTTPS with Let’s Encrypt

    Install Certbot:

    apt install -y certbot python3-certbot-apache
    

    Request certificates:

    certbot --apache -d library.example.com -d staff.library.example.com
    

    Choose redirect HTTP to HTTPS when prompted.

    Test renewal:

    certbot renew --dry-run
    

15. Configure email sending

    Koha needs working email for notices, password resets, overdues, and patron messaging.

    Install Postfix:

    apt install -y postfix mailutils
    

    For simple outbound mail, choose:

    Internet Site
    

    Set mail name:

    library.example.com
    

    Test:

    echo "Koha mail test" | mail -s "Koha test" you@example.com
    

    For production, configure SPF, DKIM, DMARC, and preferably use a transactional SMTP relay.

16. Configure cron jobs

    Koha installs cron tooling, but verify:

    koha-run-backups --help
    ls /etc/cron.d/koha-common
    

    Enable routine tasks for the instance:

    koha-enable library
    

    Check background jobs:

    koha-worker --status library
    

17. Rebuild Zebra indexes

    After setup or imports:

    koha-rebuild-zebra -v -f library
    

    For routine reindexing:

    koha-rebuild-zebra -v library
    

18. Useful Koha administration commands

    List instances:

    koha-list
    

    Disable instance:

    koha-disable library
    

    Enable instance:

    koha-enable library
    

    Restart Plack:

    koha-plack --restart library
    

    Restart Zebra:

    koha-zebra --restart library
    

    Restart workers:

    koha-worker --restart library
    

    Run database update after package upgrade:

    koha-upgrade-schema library
    

    Backup instance:

    koha-dump library
    

    Backups usually land under:

    /var/spool/koha/library/
    

19. Secure the server

    Create a non-root sudo user:

    adduser adminuser
    usermod -aG sudo adminuser
    

    Harden SSH:

    nano /etc/ssh/sshd_config
    

    Recommended:

    PermitRootLogin no
    PasswordAuthentication no
    PubkeyAuthentication yes
    

    Restart SSH:

    systemctl restart ssh
    

    Install Fail2ban:

    apt install -y fail2ban
    systemctl enable --now fail2ban
    

    Keep the system patched:

    apt update
    apt upgrade -y
    

20. Backup strategy

    Minimum daily backup:

    koha-dump library
    

    Copy backups off-server:

    rsync -av /var/spool/koha/library/ backupuser@backup-server:/backups/koha/
    

    Also back up:

    /etc/koha/
    /etc/apache2/sites-available/
    /etc/letsencrypt/
    /var/spool/koha/
    

    Test restore regularly on a separate VPS.

21. Upgrade Koha safely

    Before upgrading:

    koha-dump library
    cp -a /etc/koha /root/koha-config-backup
    apt update
    apt list --upgradable | grep koha
    

    Upgrade:

    apt upgrade
    

    Then:

    koha-upgrade-schema library
    koha-rebuild-zebra -v -f library
    koha-plack --restart library
    koha-worker --restart library
    systemctl restart apache2
    

22. Troubleshooting

    Check Apache:

    systemctl status apache2
    journalctl -u apache2 -n 100
    

    Check Koha logs:

    ls /var/log/koha/library/
    tail -f /var/log/koha/library/*.log
    

    Check MariaDB:

    systemctl status mariadb
    

    Check Koha config:

    koha-list
    koha-plack --status library
    koha-zebra --status library
    koha-worker --status library
    

    Common fixes:

    systemctl restart apache2
    koha-plack --restart library
    koha-zebra --restart library
    koha-worker --restart library
    koha-rebuild-zebra -v -f library
    

23. Final access URLs

    OPAC:
    https://library.example.com
    
    Staff interface:
    https://staff.library.example.com
    

    After onboarding, log into the staff interface with the admin patron account you created.

Conclusion

You now know how to deploy Koha on Debian VPS and run a self-hosted library management system.

Related:

• How to Deploy Evergreen ILS on Debian VPS