Koha Solutions

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

Apache refuses to reload a file with a syntax error, and a file that sorts in the wrong place can take over the main address. Both are caught by the checks in step 3.
  • Run sudo apache2ctl configtest before 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 addressWhat happens
The search boxSearches that branch by default: a hidden field limit=branch:CPL is added to it
A direct search link or the advanced searchStill 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, newsThe branch's own HTML customizations, chosen by OPAC_BRANCH_DEFAULT
CSS and JavaScriptThe branch's Specific OPAC CSS and Specific OPAC JS, after OPACUserCSS
The catalogue name in the top bar and the page titleAny system preference can be overridden for the address, for example LibraryName
A signed-in patronSees their own library's header and blocks, whichever address they used
Patrons, loans, the staff interfaceShared, 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 name library: sudo koha-list prints 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:

/etc/apache2/sites-available/zz-library-centerville.conf
<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_LIMIT is the default search scope, branch: plus the library code. It does nothing without OPAC_LIMIT_OVERRIDE 1: in the run, the limit alone added no field to the search box.
  • OPAC_BRANCH_DEFAULT chooses 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 the RequestHeader lines to Koha; with Plack off it only passes the SetEnv ones. Both are in the run: Plack ignored SetEnv, CGI ignored the header.
  • zz- keeps the file after library.conf in 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 Include lines and the port exactly as in your library.conf. If yours still has # Include /etc/koha/apache-shared-opac-plack.conf, Plack is off and the SetEnv lines are the ones that count.

Step 2: Enable the site and reload Apache

Terminal
$ sudo a2ensite zz-library-centervilleEnabling site zz-library-centerville.To activate the new configuration, you need to run:  systemctl reload apache2
Response hidden (3 lines)
Showing the response of this command only

Response from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server

Terminal
$ 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 message
Response hidden (3 lines)
Showing the response of this command only

Response 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

Terminal
$ 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 hidden (8 lines)
Showing the response of this command only

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

  1. 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.
  2. 2Administration → Libraries → Edit the branch. Specific OPAC CSS and Specific OPAC JS are added after OPACUserCSS and OPACUserJS on that branch's pages: colours, a different logo (the customization guide shows the logo rule).
  3. 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:

In the VirtualHost (group id 7)
   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

Terminal
$ 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 message
Response hidden (4 lines)
Showing the response of this command only

Response 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 seeWhy, and what to do
The branch address works but searches every libraryOnly 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 branchOpacAddMastheadLibraryPulldown 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.logA name Koha does not accept, or a typo. That one value is dropped; the others still apply
The main address now shows the branch OPACThe branch file sorts before library.conf. Rename it (the zz- prefix), check with apache2ctl -S
The branch header shows for some people and not othersSigned-in patrons see their own library's content. Test signed out
OVERRIDE_SYSPREF_LibraryName cuts the name at a commaEscape 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
Verified against the Koha source (12 files)

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.

Share this article

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