OPAC & customization
A separate Koha OPAC for each branch, on its own address
One Koha, one OPAC address per branch: each with the branch's own search default, name, header and CSS. The Apache lines that actually work under Plack, and what a branch OPAC does not separate.
By Babar Junaid
Published 2026-11-14 · Tested against Koha 26.05
Koha can give each branch its own OPAC address from one installation: a second Apache <VirtualHost> with its own ServerName, plus the variables OPAC_SEARCH_LIMIT, OPAC_LIMIT_OVERRIDE and OPAC_BRANCH_DEFAULT. On a server running Plack they must be sent as RequestHeader add X-Koha-SetEnv lines: a plain SetEnv is silently ignored.
A mistake in an Apache file takes the OPAC down
- Run
sudo apache2ctl configtestbefore every reload. - Keep a copy of the files you change in
/etc/apache2/sites-available/.
What a branch OPAC does, and what it does not
It is the same Koha, the same database and the same catalogue, reached by another name. That is enough for most libraries, but be clear about the limits before you promise a branch "its own catalogue":
| On the branch address | What happens |
|---|---|
| The search box | Searches that branch by default: a hidden field limit=branch:CPL is added to it |
| A direct search link or the advanced search | Still searches every library. The limit is a default, not a wall: on our test data "history" gave 26 results from the box and 60 from a direct link |
| Header, side blocks, news | The branch's own HTML customizations, chosen by OPAC_BRANCH_DEFAULT |
| CSS and JavaScript | The branch's Specific OPAC CSS and Specific OPAC JS, after OPACUserCSS |
| The catalogue name in the top bar and the page title | Any system preference can be overridden for the address, for example LibraryName |
| A signed-in patron | Sees their own library's header and blocks, whichever address they used |
| Patrons, loans, the staff interface | Shared, as before. A branch address does not separate data |
If a branch needs its own patrons and its own catalogue that other branches cannot see, an OPAC address is the wrong tool: that is a separate Koha instance. For a single address with one search per branch, the OpacAddMastheadLibraryPulldown preference adds a library list to the search box instead.
Before you start
- A package install of Koha (
koha-common) with root access. The examples use the instance namelibrary:sudo koha-listprints yours. - The branch's library code, from Administration → Libraries (the examples use
CPL, Centerville). See adding a library branch. - A hostname for the branch whose DNS points at the Koha server, the same way as the main OPAC name. The examples use
centerville.library.example.org.
Step 1: Write the branch's VirtualHost
Create a new file for the branch. Copy the OPAC block (the first <VirtualHost>) from /etc/apache2/sites-available/library.conf, change the ServerName, and add the seven lines in the middle:
<VirtualHost *:80> <IfVersion >= 2.4> Define instance "library" </IfVersion> Include /etc/koha/apache-shared.conf Include /etc/koha/apache-shared-opac-plack.conf Include /etc/koha/apache-shared-opac.conf ServerName centerville.library.example.org SetEnv KOHA_CONF "/etc/koha/sites/library/koha-conf.xml" AssignUserID library-koha library-koha SetEnv OPAC_SEARCH_LIMIT "branch:CPL" SetEnv OPAC_LIMIT_OVERRIDE 1 SetEnv OPAC_BRANCH_DEFAULT "CPL" RequestHeader add X-Koha-SetEnv "OPAC_SEARCH_LIMIT branch:CPL" RequestHeader add X-Koha-SetEnv "OPAC_LIMIT_OVERRIDE 1" RequestHeader add X-Koha-SetEnv "OPAC_BRANCH_DEFAULT CPL" RequestHeader add X-Koha-SetEnv "OVERRIDE_SYSPREF_LibraryName Centerville Library" ErrorLog /var/log/koha/library/opac-error.log</VirtualHost>OPAC_SEARCH_LIMITis the default search scope,branch:plus the library code. It does nothing withoutOPAC_LIMIT_OVERRIDE 1: in the run, the limit alone added no field to the search box.OPAC_BRANCH_DEFAULTchooses whose HTML customizations, news and Specific OPAC CSS/JS the page shows.OVERRIDE_SYSPREF_followed by a preference name overrides that preference for this address only. Here the top bar and the page title read "Centerville Library", while the main address keeps its own name. A value containing a comma needs\,on the header line.- Each setting is written twice on purpose. Under Plack (
koha-plack --enable, the normal setup) Apache only passes theRequestHeaderlines to Koha; with Plack off it only passes theSetEnvones. Both are in the run: Plack ignoredSetEnv, CGI ignored the header. zz-keeps the file afterlibrary.confin name order. The first site file for a port is Apache's default: it answers the server's IP address and any unknown name, so it must stay the main OPAC (step 3 checks it).- Keep the
Includelines and the port exactly as in yourlibrary.conf. If yours still has# Include /etc/koha/apache-shared-opac-plack.conf, Plack is off and theSetEnvlines are the ones that count.
Step 2: Enable the site and reload Apache
$ sudo a2ensite zz-library-centervilleEnabling site zz-library-centerville.To activate the new configuration, you need to run: systemctl reload apache2Response from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
$ sudo apache2ctl configtestAH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 203.0.113.10. Set the 'ServerName' directive globally to suppress this messageSyntax OK$ sudo apache2ctl gracefulAH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 203.0.113.10. Set the 'ServerName' directive globally to suppress this messageResponse from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
Syntax OK is what matters. apache2ctl graceful lets requests in progress finish, and prints nothing when it works once Apache has a server-wide ServerName. Until then every apache2ctl command starts with the AH00558 line: a warning, not a failure (our installation guide shows the two lines that silence it). No Plack restart is needed: the variables travel with each request.
Step 3: Check the main address is still the default
$ sudo apache2ctl -SAH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 203.0.113.10. Set the 'ServerName' directive globally to suppress this messageVirtualHost configuration:*:8080 library-intra.example.org (/etc/apache2/sites-enabled/library.conf:22)*:80 is a NameVirtualHost default server library.example.org (/etc/apache2/sites-enabled/library.conf:4) port 80 namevhost library.example.org (/etc/apache2/sites-enabled/library.conf:4) port 80 namevhost centerville.library.example.org (/etc/apache2/sites-enabled/zz-library-centerville.conf:1)…Response from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
That is a server set up as in our installation guide: OPAC on port 80, staff on 8080. The default server line must name your main OPAC host, from library.conf, and the branch name must appear as a namevhost line. In a run with the same file named so that it sorted before the instance's own file, it became the default server, and the main address started serving the branch OPAC.
Then open the branch address and search from the box. In the page source, the search form now carries <input name="limit" value="branch:CPL" type="hidden" />, and the results are that branch's.
Step 4: Give the branch its own header, blocks and colours
- 1Tools → HTML customizations → New entry. Choose the display location (
opacheader,OpacNav,OpacMainUserBlock…) and set Library to the branch. It shows on the branch address only; an entry for All libraries shows everywhere. - 2Administration → Libraries → Edit the branch. Specific OPAC CSS and Specific OPAC JS are added after
OPACUserCSSandOPACUserJSon that branch's pages: colours, a different logo (the customization guide shows the logo rule). - 3Tools → News → New entry: give the item the branch as its Library and it shows on that address's home page only.
In the run, a Centerville header and Centerville CSS showed on the branch address and not on the main one. A patron of Midway who signed in on the Centerville address saw the Midway header instead: once someone is signed in, their own library wins.
One address for a group of branches
For a campus with several branches, make a library group in Administration → Library groups, tick Use for OPAC search groups, add the branches, and note the group's id. Then use branch:multibranchlimit- and the id:
SetEnv OPAC_SEARCH_LIMIT "branch:multibranchlimit-7" SetEnv OPAC_LIMIT_OVERRIDE 1 RequestHeader add X-Koha-SetEnv "OPAC_SEARCH_LIMIT branch:multibranchlimit-7" RequestHeader add X-Koha-SetEnv "OPAC_LIMIT_OVERRIDE 1"The search box then carries limit=multibranchlimit:7, and a search covers every branch in the group. OPAC_BRANCH_DEFAULT still takes a single library code.
HTTPS for the branch address
The branch name needs its own certificate, or a certificate that lists it. koha-create --letsencrypt only covers the instance's own names, so issue it with certbot as in HTTPS for Koha with Let's Encrypt, and copy the seven lines into the :443 block as well.
How to undo it
$ sudo a2dissite zz-library-centervilleSite zz-library-centerville disabled.To activate the new configuration, you need to run: systemctl reload apache2$ sudo apache2ctl gracefulAH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 203.0.113.10. Set the 'ServerName' directive globally to suppress this messageResponse from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
Requests for the branch name then go to Apache's default server, the main OPAC. HTML customizations and CSS for the branch stay in Koha and keep showing to that branch's signed-in patrons.
Why SetEnv stopped working
The three commented lines in Koha's own koha-httpd.conf (SetEnv OPAC_CSS_OVERRIDE, OPAC_SEARCH_LIMIT, OPAC_LIMIT_OVERRIDE) date from when Apache ran Koha's scripts itself, as CGI. A variable set with SetEnv went straight into the script's environment, and guides written then still circulate.
With Plack, Apache no longer runs Koha: it forwards each request to the Plack server over a socket, and SetEnv variables do not travel with a forwarded request. Koha's answer is one request header, X-Koha-SetEnv, which the Koha::Middleware::SetEnv layer turns back into variables. It accepts only a fixed list: OPAC_BRANCH_DEFAULT, OPAC_CSS_OVERRIDE, OPAC_SEARCH_LIMIT, OPAC_LIMIT_OVERRIDE, OVERRIDE_SYSPREF_…, OVERRIDE_SYSPREF_NAMES and TZ.
Because a browser could send that header too, apache-shared.conf removes any X-Koha-SetEnv coming from the client before your RequestHeader add lines run. We sent one ourselves to the main address, and Koha never saw it.
Troubleshooting
| What you see | Why, and what to do |
|---|---|
| The branch address works but searches every library | Only SetEnv lines under Plack, or OPAC_LIMIT_OVERRIDE 1 missing. Add both RequestHeader lines |
| The search box shows a library list instead of searching the branch | OpacAddMastheadLibraryPulldown is on: the list replaces the hidden limit, with the branch preselected. Patrons can pick All libraries |
Forbidden/incorrect X-Koha-SetEnv: OPAC_FOO 1 in plack-error.log | A name Koha does not accept, or a typo. That one value is dropped; the others still apply |
| The main address now shows the branch OPAC | The branch file sorts before library.conf. Rename it (the zz- prefix), check with apache2ctl -S |
| The branch header shows for some people and not others | Signed-in patrons see their own library's content. Test signed out |
OVERRIDE_SYSPREF_LibraryName cuts the name at a comma | Escape it as \, on the RequestHeader line |
For everything else that can be changed on the OPAC, start from the Koha OPAC customization guide; per-branch CSS rules are written the same way as in OPACUserCSS and OPACUserJS.
Tested on live Koha 26.05.02
Passed all 38 checks · Read the run log
- Koha release
- 26.05.02
- System
- Debian 13 (trixie)
- Setup
- Official Koha test container (koha-common commands). A command that needs systemd or a firewall says where it ran.
- Source read at
- Koha commit d3fc229
Earlier live checks (1)
- , Koha 26.05.02 (commit d3fc229): all 28 claims held. Read the run log
In the Koha manual (26.05)
Verified against the Koha source (12 files)
- Koha/Middleware/SetEnv.pm (lines 66-74, 86-111)
- debian/templates/plack.psgi (lines 81)
- debian/templates/apache-shared.conf (lines 79-82)
- debian/templates/apache-site.conf.in (lines 1-19)
- etc/koha-httpd.conf (lines 86-91)
- C4/Auth.pm (lines 444-445, 561-605)
- C4/Context.pm (lines 272-275)
- koha-tmpl/opac-tmpl/bootstrap/en/includes/masthead.inc (lines 13-18, 313-364)
- koha-tmpl/opac-tmpl/bootstrap/en/includes/doc-head-close.inc (lines 41-60)
- Koha/Template/Plugin/Branches.pm (lines 181-190)
- opac/opac-main.pl (lines 48-56)
- opac/opac-search.pl (lines 78-90)
The label under each command says where its response came from; a command with no label was not run live. How we test and which standards we follow.
Want each branch on its own catalogue address with its own look? We set up the hostnames, certificates and branch content on your Koha server.
Want your staff trained on this? We teach it hands on with a live Koha, online or at your library. Ask about staff training
Related
More on opac & customization
Answers to the questions that usually arrive with this one.
How to customize the Koha OPAC: every place to change it
Library name, logo, favicon, contact details, header, navigation links, home page boxes, staff and opening-hours pages, news and events, a new arrivals slider, cover images, the record page, themes and plugins: where each one is changed in Koha, and what survives an upgrade.
OPACUserCSS and OPACUserJS: what belongs in each
Two system preferences hold your OPAC’s custom CSS and JavaScript. Here is what goes in each, what does not belong in either, and how to keep it upgrade-proof.
Changing the Koha OPAC header, footer and navigation
The header, footer and side navigation are content, not code. They are edited in Tools → HTML customizations — one region per named location.

