Setting Up Koha: A Free Library System You Can Run Yourself

A staged guide for the non-technical librarian · ~12 min read

Koha is a full, professional library management system — catalog, circulation, patrons, holds, reports, a public online catalog (the OPAC) and a staff interface — and it is completely free and open-source. Libraries of every size run it. The only thing standing between a small library and a real ILS has never been money; it has been the belief that you need to be “technical” to install it.

That belief is now out of date. It used to be that only librarians comfortable with servers could take advantage of free tools like Koha. Today an AI assistant can walk a non-technical librarian through the entire setup, step by step — producing the exact command for your machine, explaining what each one does in plain English, and untangling any error the moment it appears. This guide is the map. The AI is the guide who walks beside you. I know because I’m a school librarian, not a programmer, and this is exactly how I did it.

What you’re buildingA computer running Linux, with a web server and a database, hosting Koha at two web addresses: a public catalog your patrons use, and a staff side where you do the cataloging and circulation. Everything below is free except the computer and a domain name.

Before you begin

Hardware: nothing fancy. A modest 64-bit machine — a refurbished mini-PC, or even an older laptop — with about 4 GB of RAM (8 GB is comfortable) and room on the drive for your catalog. It needs to stay on, since it’s serving your library.

Cost: the software is free. You’ll spend a little on the machine (if you don’t have a spare) and a few dollars a year on a domain name.

Time: plan for an afternoon, or a few shorter sessions. Some steps just run; others you’ll do carefully. Going slowly is normal and fine.

The one mindset shift: you are not going to memorize any of this. You’re going to keep an AI chat open in one window and your server in another, and move between them — ask, paste the command, see what happens, report back. That’s the whole method, and it’s genuinely how the work gets done.

Stage 1 · A computer running Linux

Koha runs on a Debian-based Linux — either Debian itself or Ubuntu Server (the LTS “long-term support” version). You install it from a USB stick and accept the sensible defaults; your AI can talk you through the installer screen by screen if it’s your first time. Once it’s running, the very first thing you do on any new Linux machine is bring it up to date:

sudo apt update sudo apt upgrade

(sudo means “do this as administrator”; apt is how Debian installs and updates software. You’ll see these two a lot.)

Stage 2 · Getting on the internet

Two things are needed here: a domain name (the human-friendly address, like yourlibrary.org), which you buy from any registrar for a few dollars a year, and a way for the outside world to actually reach your server. There are two routes:

The traditional route: a public IP address from your internet provider, a port forward on your router, and free HTTPS certificates from Let’s Encrypt (a tool called certbot).
The modern route — and the one I’d recommend for a home setup: a free Cloudflare Tunnel. It makes an outbound connection from your server to Cloudflare, so you need no public IP and no port forwarding (this is the only thing that works if your provider uses “CGNAT,” which many home connections do), and it handles HTTPS for you automatically.

This is a great moment to lean on the AIThe networking choices depend on your exact provider and router. Describe your situation (“home internet, not sure if I have a public IP, here’s my router model”) and let the assistant tell you which route fits and give you the steps for it.

Stage 3 · The web server (Apache)

Apache is the program that actually serves web pages — it’s what hands Koha’s catalog and staff pages to a browser. Installing it is one line:

sudo apt install apache2

To check it worked, visit your server’s address in a browser; you should see Apache’s default welcome page. From here on, a handful of Apache commands recur — starting, stopping, and reloading it after a change:

sudo systemctl reload apache2 # apply config changes sudo systemctl restart apache2 # full restart

Stage 4 · HTTPS (the padlock)

Your site should be served securely, over https://. If you took the Cloudflare Tunnel route, this is already handled for you — nothing to do. If you took the traditional route, certbot fetches and installs a free certificate in a single guided command. Your AI will give you the exact form for your domain.

Stage 5 · The database (MariaDB)

Koha keeps everything — every record, patron, and checkout — in a database. MariaDB is the free one Koha uses:

sudo apt install mariadb-server mariadb-client sudo mysql_secure_installation

That second command is a short interview that locks the database down: it sets a password and removes the insecure test defaults. Answer “yes” to the safety prompts (your AI can sit with you through each one).

Stage 6 · Koha itself

Koha isn’t in Debian’s normal software list, so you first tell your machine where to find it — you add the Koha community repository (the Koha project’s website gives the current signing key and the one line to add; this is a perfect thing to paste to your AI and say “walk me through adding this”). Once that’s done, installing Koha is, again, one line:

sudo apt update sudo apt install koha-common

Next, switch on the Apache features Koha needs, and create your library’s instance — a single command that builds the database and the configuration together (here the instance is named library):

sudo a2enmod rewrite cgi headers proxy_http sudo koha-create --create-db library

Then turn on Plack, which makes Koha run much faster, and restart Apache:

sudo koha-plack --enable library sudo koha-plack --start library sudo systemctl restart apache2

Finally you point Koha’s two web addresses — the public OPAC and the staff interface — at your domain by editing Koha’s site configuration. The exact edits depend on your domain names, so this is another “show the AI your config and let it give you the precise changes” moment.

Stage 7 · Finish in the browser

The last mile happens in a web browser, not the terminal. Visit your staff address and Koha’s web installer greets you: it loads the default data and sets up your catalog through a friendly wizard. You’ll need the instance’s admin password, which Koha generated for you — reveal it with:

sudo koha-passwd library

Log in, and the installer’s onboarding walks you through naming your library, creating your first patron category and item type, and you’re looking at a working library system.

Stage 8 · Make it yours

Koha is deeply customizable, almost all of it through the staff interface — no more terminal needed. The main places you’ll personalize:

System preferences — Koha’s master control panel: library name, language, date format, and your circulation rules (loan periods, fines, holds).
Item types, patron categories, and branches — the shape of your collection and community.
Branding — your library’s name, logo, and a favicon on the catalog.
Searching in non-Latin scripts — if you catalog in Chinese, Japanese, Arabic, or similar, you’ll enable a component called ICU and install the matching language pack, for example Traditional Chinese:
sudo apt install yaz-icu sudo koha-translate --install zh-Hant-TW
(rebuild the search index afterward — your AI will give you that command).
Automatic jobs — Koha ships scheduled tasks for overdue notices, holds, and nightly re-indexing; you switch on the ones your library wants.

The real secret: do it with the AI

Everything above is the route. Here’s how the journey actually feels when you have an assistant beside you — three habits do most of the work:

1. Ask for the exact command for your exact machine.

Example promptI’m setting up Koha on Ubuntu Server 24.04. Give me the exact commands to install Apache and confirm it’s running, and explain what each one does before I run it.

2. When something breaks — and it will — paste the error. This is the single most valuable move. An error message that looks like a wall to you is a clear signpost to the AI.

Example promptI ran the koha-create command and got this error: [paste the whole message]. What does it mean, and exactly how do I fix it?

3. Ask what a command does before you run it. You stay in control, and you learn as you go.

Example promptBefore I run “sudo koha-plack --enable library,” explain in plain English what it changes and whether it’s safe.

One honest cautionKoha has many moving parts, and a real install touches the network, a web server, a database, and the application itself. Expect a few snags — that’s not failure, it’s the normal texture of the work. Go one stage at a time, and once it’s running, ask your AI to set up regular backups so your catalog is safe.

That’s the whole shape of it. A free, professional library system, run by one person, on a small machine in the corner — the kind of thing that used to be out of reach for a library without a budget or an IT department. It isn’t anymore.

Next: how I use AI day-to-day in the library