Our method
How we test Koha guides on a live Koha
We run the commands in our Koha knowledge base on a live Koha, the official Koha test container that runs the community’s own code, copy the response, and check each claim against the Koha source code at a named commit. When an article is about the server itself (installing Koha, Apache, the database, email, scheduled jobs, backups or an upgrade), we run it on a fresh Ubuntu server that we log into over SSH as an ordinary user with sudo, the way you will. A script we keep repeats the checks whenever a new Koha release comes out. The label under each command says where its response came from, and a command with no label has not been re-run yet.
The seven steps behind every article
Read the Koha source. We open the file that prints the message or runs the command, at a named commit of the Koha source, and note the lines. A competitor’s page is never the source.
Run it where it belongs. A screen in Koha is run on a live Koha with sample data. A server task is run on a fresh Ubuntu 24.04 server built for that run: we log in over SSH, make an ordinary user with sudo, and run every command as that user, then reboot to check that everything comes back. Either way we include the failure the article covers: the duplicate, the missing field, the refused action.
Copy what Koha printed. The response shown under a command is the text from that run. We never write one from memory or from the source, and a command we could not run shows no response.
Take screenshots from the same run. Screens come from the run, with no patron data, and the buttons to click are marked. Terminal output is never a screenshot.
Save the check. Each claim and each response becomes an assertion in a script we keep. The script restores everything it changed, so the next run starts from the same place.
Publish with the evidence. The article records the Koha release, the system, the setup and the source commit it was checked against, and links every source file it relies on. When the saved check passes, its full run log is published too, and the article links to it.
Run it again on every new release. When Koha publishes a release, we re-run the checks. If everything passes, the date moves. If a response changed, the article is fixed and the old response stays visible for readers on the old release.
What you can check on any article
| What | Where to find it | What it tells you |
|---|---|---|
| Where it was run | The “Tested on” box at the end of each article | Koha release, operating system, setup and the exact source commit. |
| What it was read from | “Verified against the Koha source” in the same box | Each file links to that commit on the Koha community’s own git server, with the lines. The link never changes. |
| What the Koha manual says | “In the Koha manual” in the same box | The manual sections the article rests on, linked at the Koha release it was tested on, so you can check the documented behaviour too. |
| That the output is real | Under each command | “Response from a live run on Koha 26.05”, or the system it ran on, such as “a fresh Ubuntu 24.04 server”. A command with no label was not run live. |
| The run itself | The heading of the “Tested on” box (“Passed all checks”, with a link to the run log), and “Earlier live checks” below it | The plain-text log of each passing run: when it ran, the release and commit it ran on, every claim and what it read back, and the check’s own code. Only runs in which every claim held are published, and none is ever replaced. |
| When it was last checked | Under the title | Published, Updated and Tested against. “Updated” is the day of the last re-run, not the day of an edit. |
| What changed and why | “What changed” under the dates | One line for each change a reader would notice: a new Koha version, a changed step, a new cause. |
When a new Koha release comes out
We do not overwrite the old test. If the checks still pass, the article’s date moves and the release it was tested on changes. The earlier release stays in the box under “Also checked on earlier Koha releases”, with its source commit, and the run logs from that release stay listed under “Earlier live checks”. If Koha now answers differently, we fix the article, add a note under “What changed”, and keep the old command and response in a collapsed “On an older Koha” section. A reader who runs an older server still finds the exact words their screen shows.
There is one page for each question, never a copy for each version. Near-identical pages split what readers and search engines know about the answer, and each would need checking again at every release.
What we cannot run, and how we say so
- Our live Koha is the official Koha test container. It runs the community’s code with the same
koha-*commands as a package install, but it is not a bare server. - A server task runs on a fresh Ubuntu 24.04 server: its own SSH login, systemd, firewall and reboots, built for the run in a data centre and removed after it. It shares that data-centre machine’s kernel, so we do not publish kernel, memory or disk figures from it, and commands that change the machine itself, such as turning on swap, are shown without a response and say why. The server address you see is an example address.
- Articles we checked before November 2026 ran their server commands as the root user in a clean Ubuntu container. We are re-running each of them on the test server. A re-run one says “a fresh Ubuntu 24.04 server” under its commands, and its earlier runs stay listed.
- A step we cannot run at all, such as issuing a Let’s Encrypt certificate, which needs a public domain that points only at that server, carries no “live run” label and says why.
- Windows and WSL steps follow Microsoft’s documentation and are marked as not run on Windows.
- We are re-running our older articles to add the response labels. Until an article has been re-run, a command in it may show no label.
- An article is published only once it has been tested and its “Tested on” box records where. One that is written but not yet tested waits, even past its planned date, rather than going up unchecked.
Standards we write to
We list a standard here only when it changes how an article is written or built. Each link goes to the standard itself.
- Diátaxis
Every article is exactly one of four kinds: a fix, a how-to, an explanation or a reference. We do not mix them on one page. - Google developer documentation style guide
Second person, present tense, sentence-case headings, one action per step, and the result stated after the step. - Google: creating helpful, reliable, people-first content
First-hand experience shown as evidence (real output, real screens), a named author with a page, and a clear answer first. - Google: publication dates
The date you see is the date written in the page data. "Updated" moves only when we re-run the article. - schema.org TechArticle
Each article carries machine-readable data: author, dates, the software it is about, and its citations. - schema.org publishingPrinciples and correctionsPolicy
This page is the publishing and corrections statement every article points to. - WCAG 2.2, text alternatives (success criterion 1.1.1)
Terminal output is text, never a picture. Each screenshot has an alternative text that says what it shows. - ISO 8601
Dates in year-month-day order, readable the same way in every country.
The primary sources are the Koha manual and the Koha source code. We compare with other sites to learn which questions readers ask. We never copy their wording, structure or an unverified command.
Corrections
If a command or message here does not behave as the article says on your Koha, tell us which article, your Koha release and what you saw. We re-run the article, fix what is wrong, and add a dated line under “What changed”. We do not edit an article silently, and we do not change its date unless we re-checked it. Send a correction.
Every article names its author, and each author has a page that says who they are and what they have worked on.

