Installation & setup
Koha, Apache and port 8080: staff and OPAC on two hostnames
Koha serves two websites from one install. Here is how the OPAC and the staff interface are separated, why staff lands on port 8080, and how to move it off.
Updated 2026-08-09 · Tested against Koha 26.05
A Koha instance is two websites: the public OPAC and the staff interface. koha-create writes one Apache virtual host for each, and by default the OPAC answers on port 80 while staff answers on port 8080. So a fresh install reaches staff at http://your-server:8080. When that port does not answer, it is almost always because Apache was never told to listen on it.
Step 1Make sure Apache is listening on 8080
This is the entire problem in most cases. A <VirtualHost *:8080> on a port Apache is not listening on does nothing at all, and produces no error to tell you so.
$ grep -R "^Listen" /etc/apache2/ports.conf Listen 80If Listen 8080 is not in the output, add it and reload:
$ echo "Listen 8080" | sudo tee -a /etc/apache2/ports.conf$ sudo apache2ctl configtest$ sudo systemctl reload apache2configtest before reload, every time
apache2ctl configtest costs a second and turns an outage back into a typo.Step 2Make sure the site is enabled
$ sudo a2ensite library$ sudo a2enmod rewrite cgi$ sudo systemctl reload apache2The site file is /etc/apache2/sites-available/library.conf, named after the instance. Both virtual hosts live in that one file, which is why enabling or disabling it affects the OPAC and staff together.
Step 3Use two hostnames instead of a port
Port 8080 is a default, not a requirement, and it is a poor one for a library: it is blocked on many institutional networks, it is awkward to certificate, and staff have to remember it. The better arrangement is two hostnames, both on the standard port.
Set it in /etc/koha/koha-sites.conf before running koha-create:
DOMAIN=".example.org"INTRAPORT="80"INTRAPREFIX=""INTRASUFFIX="-intra"OPACPORT="80"OPACPREFIX=""OPACSUFFIX=""With those values an instance named library gives you an OPAC at library.example.org and staff at library-intra.example.org, both on port 80. The names are built as <PREFIX><INSTANCE><SUFFIX><DOMAIN>:<PORT> — documented in that file, and worth reading before inventing a scheme of your own.
Both hostnames need a DNS record
Host header, so each name must resolve to the server. If only the OPAC name has a record, requests for the staff name never arrive and Apache serves the first virtual host instead — which presents as "the staff URL shows the OPAC".Changing it on an instance that already exists
Editing koha-sites.conf only affects instances created after the edit. For one that already exists, change the virtual host directly.
- 1Edit
/etc/apache2/sites-available/library.confand change<VirtualHost *:8080>to<VirtualHost *:80>. - 2Set
ServerNameon that block to the staff hostname you want. - 3Add a DNS record for that hostname pointing at the server.
- 4Update the
staffClientBaseURLsystem preference so the links Koha generates — including the ones inside notices — point at the new address. - 5Run
sudo apache2ctl configtest, thensudo systemctl reload apache2.
The system preference matters more than it looks. Koha builds absolute URLs for password resets and hold notices from it, and a stale value sends both patrons and staff to an address that no longer answers.
Then put HTTPS in front of both
Once each site has its own hostname, a certificate is straightforward — and both sites need one. Staff log in with a password, and patrons log in to see their own borrowing record; neither belongs on plain HTTP. koha-create even takes a --letsencrypt flag for new instances.
Set OPACBaseURL and staffClientBaseURL to the https:// addresses afterwards, or Koha carries on generating links back to plain HTTP.
Troubleshooting
| What you see | What it usually is |
|---|---|
| Port 8080 refuses the connection | No Listen 8080 in ports.conf, or a firewall. Check in that order. |
| The staff URL shows the OPAC | The staff hostname has no DNS record, so Apache falls back to the first matching virtual host. |
| OPAC works, staff is a 404 | The site is not enabled (a2ensite), or the instance name in the file does not match. |
| Every page is a 500 | mod_cgi or mod_rewrite is not enabled. sudo a2enmod cgi rewrite. |
| Works on the server, not from outside | The firewall allows 80 but not 8080 — the strongest argument for moving staff onto its own hostname. |
| Login redirects to the wrong address | staffClientBaseURL or OPACBaseURL still holds the old URL. |
Cannot log in once the page does load? The credentials are generated per instance — see finding your Koha admin password.
Would rather not do this yourself? We do it as a service — and if you would rather it were already done, it is on Koha Cloud before you log in.
Related
More on installation & setup
Answers to the questions that usually arrive with this one.
The Koha web installer returns a 500 error or times out
The installer dies partway through and the browser shows a 500 or a gateway timeout. Read the instance log to find out which step failed, then restart the install cleanly rather than retrying on a half-built database.
Koha cannot locate the configuration file koha-conf.xml
The error means the process has no KOHA_CONF set, not that the file is gone. Run the command through koha-shell, and here is how to confirm the file really is where Koha expects it.
Can you install Koha on Windows? (WSL2, VMs, and when not to)
There is no Windows build of Koha. You can run it on a Windows machine through WSL2 or a virtual machine — which is fine for evaluation and wrong for a live library.
Finding your Koha instance’s admin password (koha-passwd)
The credentials the Koha web installer asks for are generated at install time and printed by koha-passwd. Here is how to find them, and how to reset a staff login.