Moving My Koha OPAC to Https

With the latest release of Koha 20.05, I’ve decided as of late to engage in some server-side T.L.C. of my library, which has been sorrowfully neglected these past months. What follows is a report on the steps I took to move my Koha OPAC over to https – finally! I don’t claim authority on this topic, as I am a professional librarian engaging in Web and database administration as an amateur. Caveat emptor, please.

Quick Browse

Why https?
How to move Koha’s OPAC to https?
System information
Step 1. Download a Let’s Encrypt certificate for your Koha domain
Step 2. Configure Apache’s Koha OPAC virtual host file
Step 3. Open up your firewall to https traffic
Step 4. Redirect all http traffic going to Koha to https
Step 5. Change your OPAC base url to https
The problem of mixed content
Coce book cover caching server
Coverflow plugin
Bonus: Moving Koha Intranet (staff client) to https
Conclusion

Why https?

Well, there are many reasons, which can all be found online. The most popular reason to move to https is that it increases the security of transaction data between a user and a Website. Think of paying for something online or logging into a Web application. These kinds of transaction are privater and securer within an https environment. In other words, https offers end-to-end encryption of http traffic, reducing the risk of “man-in-the-middle” attacks (the tech world’s phrasing, not mine) and snooping.

But for hobbyists like myself whose Koha library is not a public, lending institution, but instead a favoured past-time, moving one’s Website to https can, since 2014, also improve your search engine ranking. Admittedly, too, the psychological effect of always visiting my library and the browser telling me that my connection is “not secure” has finally caught up with me. There’s something calming at the site of a green lock symbol next to my URL absent a red line or yellow warning triangle superimposed upon it.

How to move Koha’s OPAC to https?

For those who are unaware, there is some guidance provided by fellow Kohaers on this topic, but not much since moving a Website to https is more of a network security / Web server matter than a Web application – or, in this case, Koha – matter. One can find some documentation on this topic archived in Koha’s listservs as well as on Koha’s Bugzilla page. I haven’t yet found any information on the Koha Wiki. This has in part led to my posting on this topic, with the hope that someone in the Kohasphere may find it useful. The following assumes that you do not have any SSL certificates at your disposal and a moderate knowledge of Ubuntu command-line environment and Web/database administration. So, here we go.

System information

  • Koha 20.05.00.000
  • Running Plack, Memcache, Zebra
  • Apache 2.4.29
  • MariaDB 10.1.44
  • Ubuntu 18.04 (Bionic)
  • Coce book image server (local)

As with any move to https, a Website requires an SSL certificate from a trusted provider. There are many. Until recently, these were usually at a cost; however, Let’s Encrypt has changed that, as they offer free SSL certificates to those who need them. First, the certificate is installed on your server. Then, you must configure your Web server to point to those certificates. Once this is achieved, you can then redirect your http website to https. What follows requires root access to your Web server, as everything takes place in a command shell environment, which I access via Putty. How to access your server via Putty is beyond the scope of this post.

Step 1. Download a Let’s Encrypt certificate for your Koha domain

For this I used the following guide over at Digital Ocean, with the proviso that my server is not setup for DNS locally. But that seems to be okay, because my /etc/hosts file is populated with the following line:

...
158.69.204.211 library.craigbutosi.ca library www.library.craigbutosi.ca
...

The first string is my public IP address; the second, my (registered) domain name; the third and fourth are domain aliases. In order to install an SSL certificate from Let’s Encrypt, you must do so using Certbot, ensuring that, during the process, you create the certificates according to the value in your ServerName line within your Apache virtual host (“VH”) file, which, by default on Ubuntu, should be located here:

/etc/apache2/sites-available/YOUR_KOHA_INSTANCE.conf

Mine looks like this:

# Koha instance library2 Apache config.

# OPAC
<VirtualHost *:80>
  <IfVersion >= 2.4>
   Define instance "library2"
  </IfVersion>
   Include ...
#  Include ...
  Include ...
  Include ...

   ServerAdmin library@craigbutosi.ca
   ServerName library.craigbutosi.ca
   ServerAlias www.library.craigbutosi.ca
...

Please take note that the ellipses ( … ) are not literal. They indicate the presence of actual values in my VH file, which I am choosing not to share here for security reasons. Whenever you see ellipses you can assume that they are placeholders for actual values.

Once you run Certbot, a few things will happen as you move along the process (see the Digital Ocean tutorial for details). At the end, a new virtual host file to run your website in SSL (i.e., https) is created. This new virtual host file contains the pathways to the SSL certificates Certbot installed on your system (the actual certificates are stored in different directories). After I ran Certbot, I noticed the following new VH file “library2-le-ssl.conf”:

Apache Virtual Host Files. A new file created after installing SSL certificate “library2-le-ssl.conf”.

You’ll notice above that there are other VH files. “Library2.conf” was created during my Koha installation. This includes all the configuration data required to run Koha (by default on Port 80 for OPAC and Port 8080 for staff client). The other file, “default-ssl.deactivated”, was not required, so I changed the extension from .conf to .deactivated as it was causing complications with redirection. This might be different for you if your server relies on the default ssl VH file. I wouldn’t recommend deactivating it. I did because the only thing running as a Web app on my server is Koha.

Step 2. Configure Apache’s Koha OPAC virtual host file

Interestingly, I noticed that Certbot incorrectly populated my library2.conf virtual host file with directives that should have been placed in the library2-le-ssl. I simply moved these over. The directives I moved were:

SSLEngine ...
Include ...
SSLCertificateFile ...
SSLCertificateKeyFile ...
SSLCertificateFile ...
SSLCertificateKeyFile ...

Once you’ve moved the SSL-related directives out of your Koha instance VH file for http (i.e., Port 80), and into your ssl VH file created by Let’s Encrypt (i.e., Port 443, which is the standard port for https), you can then restart Apache. If it restarts without error, then your syntax should be good. Just in case, run the following command:

sudo apache2ctl configtest

If you get the Syntax OK returned, then you’re good. If not, check your error logs.

At this point your original Koha instance VH file will be the same as it was before. No further additions should have been added to it after you run Certbot and install certificates. Again, if you find that Certbot added directives meant for the Let’s Encrypt ssl VH file, then move those over by cutting, pasting, and restarting Apache. Your ssl VH file should be populated with some or all of the following information (VH files vary depending on local needs):

<IfModule mod_ssl.c>
<VirtualHost *:443>
  <IfVersion >= 2.4>
   Define instance "library2"
  </IfVersion>
   Include ...
#  Include ...
  Include ...
   Include ...

   ServerName library.craigbutosi.ca
   ServerAlias www.library.craigbutosi.ca
  DocumentRoot ...
   SetEnv KOHA_CONF "..."
   #SetEnv MEMCACHED_SERVERS "..."
   #SetEnv MEMCACHED_NAMESPACE "..."
   AssignUserID ...

   ErrorLog    ...
#  TransferLog ...
#  RewriteLog  ...
ScriptAlias ...
ScriptAlias ...
Alias /plugin "..."
Alias /sitemapindex.xml ...
# The stanza below is needed for Apache 2.4+
<Directory ...>
      Options ...
      AllowOverride ...
      Require all ...
</Directory>


SSLEngine ...
SSLProtocol ...
Include ...
SSLCertificateFile ...
SSLCertificateKeyFile ...
SSLCertificateFile ...
SSLCertificateKeyFile ...
SSLCipherSuite ...
SSLHonorCipherOrder ...
SSLCompression ...
SSLSessionTickets ...

</VirtualHost>
</IfModule>

The stanzas beginning from SSLEngine through to SSLSessionTickets are the key stanzas for SSL/https. Be sure that at least the SSLEngine and SSLCertificate directives are there.

Step 3. Open up your firewall to https traffic

At this point, if everything is set-up correctly, you could try to access Koha over https by going to a browser and typing in https://YourKohaURL.xxx; however, if you’re running a firewall whose default is to always have ports closed, you won’t get through.

I’m running UFW, or Uncomplicated FireWall. If you are too then you can run the following command to open up port 443, which is the default SSL/https port:

sudo ufw allow https

OR

sudo ufw allow 443

Either command will do the same thing. You can then check your firewall rules by running:

sudo ufw status numbered

If you see port 443 set to “ALLOW IN” from “Anywhere”, you should be able to access your Koha over https now. Try it!

Step 4. Redirect all http traffic going to Koha to https

Now that you can successfully get to your Koha instance over https, you might have also noticed that your Koha instance is still available over http. This is not ideal. Duplicate content (i.e., the same website offered up in both http and https) is not advisable for many reasons, mostly to avoid confusion among users and for search engine indexing.

In order to ensure that all of your traffic now goes to https, include a redirect in your original Koha VH file. You’re not disabling anything, but instead telling Web traffic to always go to the https site, even if someone tries to access your site over http or by your public IP address.

There are several ways in which you can define a redirect. Apache recommends including a Redirect directive in your VH file. (This is different than the Rewrite directive, which is also acceptable but more cumbersome; it requires knowledge of regular expressions, which is beyond the scope of this post.)

Navigate to your original Koha VH file. In my case,

/etc/apach2/sites-available/library2.conf

Be sure to place the following line somewhere between the <VirtualHost *:80> tag and the </VirtualHost> tag:

Redirect permanent / https://library.craigbutosi.ca/

You are telling Apache to redirect all requests from http (i.e., on Port 80) to https (i.e., Port 443). Save the file. Restart Apache. Clear your browser cache. (Again, the only Web app I am running is Koha. The redirect above assumes you are too, so if you are not, then you may have to define a specific server directory in this directive to tell Apache to only forward contents within that particular directory to https.)

Now, when you try to access your Koha site from http or by public IP address, it should automatically be redirected to https. Note: It is important to include the “permanent” string in the directive. Placing a temporary redirect in your VH for a long period of time has consequences for Google indexing. Plus, it isn’t logical.

Step 5. Change your OPAC base url to https

Navigate to your staff client and search Administration for OPACBaseURL. Once you find it, change the URL there from http:// … to https:// …

The problem of mixed content

Mixed content refers to images, widgets, iframes, and other embedded content within an https page whose sources are http. Best practice is to avoid mixed content by ensuring that all your embedded content is coming from an https source for security reasons. Mixed content on a page is akin to locking your doors tightly, but keeping your windows open. For example, before I moved my library to https, my Koha header logo had an <a href> link with a value of “http://library.craigbutosi.ca/opacheader.jpg”. Not a problem with http, but definitely a problem with https.

In fact, the browser will tell you about the presence of mixed content. If you see a lock symbol next to your url in the address bar that has either a yellow warning triangle (Firefox) or a “Not Secure” statement (Chrome), then you’re probably dealing with a mixed content issue. The first step to resolving this is to identify all of your embedded content and move its source from http to https if possible.

If your embedded content is coming from a third-party, see if the same content is available under https. If it is, update your links within your https environment accordingly. Once done, and there are no other issues with your https environment, you should see the lock symbol (Firefox) or a secure statement (Chrome) in your browser’s address bar

The gray lock symbol in Firefox means your connection is fully secured with SSL (https)

Coce book cover caching server

For those running a local instance of Frédéric Demians’ Coce book cover cache server (which is a fantastic service to compliment Koha!), you probably set this up under http. If you have, then you will also have mixed content on your freshly minted https Koha site.

After some research, it looks like Mark Alexander adapted Demians’ Coce server to work under https. To him, I am grateful because this was just thing I needed to keep Coce going under an https environment. Setting up Coce to work under https is outlined in a separate post.

Even quicker, ByWater Solutions offers a free Coce book cover cache server that runs over https:

https://coce.bywatersolutions.com/

Plug this link into your Koha system preference and voila:

Use the above link to maintain Coce’s book cover cache server in an https environment

Coverflow plugin

Like Coce, if you’re also running Kyle Hall’s coverflow plugin, which allows you to place a carousel of book cover images on your Koha landing page (this plugin is completely separate from Coce), you will also have to change the source URL of your default image when no image is found to https to avoid the mixed content warning, as in:

Change your Image Options in the coverflow plugin to https.

Bonus: Moving Koha Intranet (staff client) to https

The following assumes that you installed your client on port 8080, which is the default location for a package installation:

  1. Navigate to /etc/apache2/ports.conf
  2. You should see an entry like Listen 8080
  3. Change this to Listen 8080 https
  4. Save the file
  5. Navigate to your Koha library’s (non-https) virtual host file, in my case library2.conf
  6. Move your entire Intranet virtual host stanza (i.e., <VirtualHost *:8080> ... </VirtualHost>) to your https virtual host file, in my case library2-le-ssl.conf
  7. Be sure to add your SSL directives as found under the port 443 virtual host section as above to this section
  8. Your https virtual host file should now look like:
<IfModule mod_ssl.c>
<VirtualHost *:443>
  
...

</VirtualHost>

# Intranet
<VirtualHost *:8080>
  
...

</VirtualHost>

</IfModule>
  1. Adding the following line to your :8080 stanza (between the <VirtualHost *:8080> and </VirtualHost> tags), will redirect all http traffic going to :8080 to https:
ErrorDocument 400 https://library.craigbutosi.ca:8080
  1. Navigate to your staff client and search Administration for IntranetBaseURL. Once you find it, change the URL there from http:// … to https:// …
  1. Restart Apache
  2. Clear your browser cache

Congratulations! Both your OPAC and your Staff Client should now be accessible via https!

Conclusion

Moving your Koha OPAC over to https is a more secure way to offer up your library’s holdings online. It provides an added layer of protection that you can use in your toolbox of online information security and privacy tactics that complements (but does not replace) due diligence, correct server hardening, and information privacy/security best practices. If you’re having your patrons logging into Koha to check their profiles, then https would be recommended. I’ve provided but one way to get your Koha instance up and running in an https environment. Here’s the breakdown:

  1. Download a free SSL certificate from Let’s Encrypt using Certbot
  2. Ensure that the newly created SSL virtual host Let’s Encrypt created has all the necessary directives that point to your installed certificates
  3. Ensure that your firewall allows traffic coming in and going out from port 443
  4. Ensure that your original Koha virtual host file has a permanent redirect pointing all non-https Koha traffic to https
  5. Remove mixed content in your https environment
  6. (Optional) When running Coce book cover cache server, be sure to set-it up to run over https (this will be handled in another post soon!). Until you do, you will get a mixed content warning.

Craig Butosi
Library professional of ten years, with six years of library management and administration experience. Graduate of critical media studies and music. Autodidact and lover all things that inch us closer to the good life.