Koha returns 502 or 503 after enabling Plack

A 502 or 503 means Apache is now proxying to Plack and cannot reach it. In almost every case the two Apache modules Plack needs are not enabled: run sudo a2enmod proxy_http headers, restart Apache, and the site comes back. koha-plack prints that exact advice as a warning when you enable it, and it scrolls past.

$ sudo a2enmod proxy_http headers$ sudo apache2ctl configtest Syntax OK$ sudo systemctl restart apache2

Enabling proxy_http pulls in proxy itself, so those two are the whole list. If the site answers again here, you are done — the rest of this page is for when it does not.

$ sudo koha-plack --status library Plack is enabled and running for library

Enabled but not running is the second common state — Apache has been reconfigured to proxy, and there is nothing on the other end. Start it:

$ sudo koha-plack --start library

If it will not start, the reason is in its own log, not in Apache's:

$ sudo tail -n 40 /var/log/koha/library/plack-error.log

Apache and Plack meet at a Unix socket, one per instance. If the file is not there, Plack is not running whatever a status line says; if it is there with the wrong ownership, Apache cannot open it and you get 503 with a permission error in Apache's log.

$ sudo ls -l /var/run/koha/library/plack.sock srwxrwxrwx 1 library-koha library-koha 0 Aug 12 09:02 /var/run/koha/library/plack.sock

Plack is an optimisation. If the library is open and the site is down, turn it off, restore service, and come back to it:

$ sudo koha-plack --disable library$ sudo systemctl restart apache2

That puts the instance back on plain CGI — slower, and completely functional. Nobody has to be locked out of circulation while a proxy module is sorted out.

Without Plack, Apache runs Koha as CGI: a fresh Perl interpreter per request, loading the whole application every time. It is simple and it is slow. Plack keeps Koha loaded in a long-running process, and Apache stops executing anything — it proxies each request to that process over a Unix socket instead.

So koha-plack --enable does not add a feature next to the working configuration; it replaces the way requests are served, by uncommenting the apache-shared-*-plack.conf Includes in the instance's site file. From that moment Apache needs a working proxy stack, and if proxy_http is missing it has been told to forward requests it has no ability to forward. Hence a site that was fine one command ago.

koha-plack does check, and prints "koha-plack requires some Apache modules that you are missing" with the a2enmod line to run. It stops short of enabling them itself — a script that reconfigures Apache silently is a worse trade — so the warning is the whole safety net, and it is one line in a page of output.

One habit prevents the rest of this article: after enabling Plack, always apache2ctl configtest and then load both the OPAC and the staff interface before walking away. And when a page fails with a 500 rather than a 502, the fault is inside Koha instead — read the right log file. If it is the staff port that is not answering at all, start with Koha, Apache and port 8080.