How to set up a domain name for Koha

Set up a Koha domain and configure the defaults

You can either access your Koha installation using an IP address, or using a domain. The latter is almost always preferable and is the situation dealt with here. Using the domain name method means that you must either be told what the domain name of your Koha server is, probably by your network administrator, or you must create and configure one for it.

Creating and configuring a domain can be done in one of two ways:

• DNS - Either internal to the intranet or public to the world
• The /etc/hosts file - Local to each PC which should be able to see Koha

If you are on a large network there will very often be a DNS server on that network that allocates human-friendly domain names to IP addresses. If you are the admin for the DNS server, you will know how to do this and will be able to allocate a domain name to your Koha server. If you do not administer the DNS server then you need to talk to the administrator who does, and ask them to allocate a domain name, or tell you what it is if one already exists. When you are given the domain name, you can configure Koha to use it, following the instructions below. Remember that changes to DNS servers can take up to 24 hours to take effect.

On very small networks there is another possibility that consists in using your Koha server’s /etc/hosts file (and the same file on any other computers on your network that will need to access Koha). You can use this method if you are sure that your network does not have its own DNS server and as long as you know that the domain name you choose will not conflict with one specified for any other computer on your network. This method is adequate, therefore, for test installations and for installations on very small networks. It is not an appropriate method for Koha servers accessed from the internet.

By default, the Koha installation process creates two apache sub-domains, the first of which will be given the same name as the library name you specify when you issue the koha-create command later on. The second sub-domain will be given the same name as the library, but followed by an arbitrary suffix: -intra by default. So decide now what you are going to call your library, if you haven’t done so already.

If you called your library libraryname and if your domain was peredur.cym, the two sub‑domains would be called:

libraryname.peredur.cym

and:

libraryname‑intra.peredur.cym

The following instructions cover using /etc/hosts for the domain and assume that you will use the domain peredur.cym. You can skip this and move straight on to editing the koha‑sites.config file if your Koha server has been allocated a domain using DNS.

You can call the domain anything you want as long as it does not conflict with anything else on your local network. We will continue to use peredur.cym in the examples that follow.

Editing /etc/hosts

Before editing the /etc/hosts file you need to know your Koha server’s IP address.

Your Koha server, like every computer on your network, has an IP address. If you don’t know what it is, you can find it by issuing the following command in a terminal:

$ ip addr show

Depending on whether you are connected to your network via a wired connection or a wireless connection, you will usually see the IP address against either eth0 or wlan0 in the output. It will be an IP address in dotted quad notation, usually looking much like 192.168.x.x where x represents a number. So, for example, it could be 192.168.1.136. This is the output from the ip addr show command on my laptop:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1

   link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
   valid_lft forever preferred_lft forever

2: eth0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc pfifo_fast state DOWN group default qlen 1000

   link/ether d0:bf:9c:86:10:09 brd ff:ff:ff:ff:ff:ff

3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000

   link/ether 38:b1:db:f9:6d:75 brd ff:ff:ff:ff:ff:ff
inet 192.168.1.98/24 brd 192.168.1.255 scope global dynamic wlan0
   valid_lft 170987sec preferred_lft 170987sec
inet6 fe80::3ab1:dbff:fef9:6d75/64 scope link
   valid_lft forever preferred_lft forever

The laptop’s IP address is given against wlan0 and is 192.168.1.98.

Now you have the IP address you need, you can configure the /etc/hosts file. Do the following either as root or via sudo. I assume you can use sudo in the following instructions and that you have the gedit text editor installed. If you don’t have gedit then either install it or substitute the name of your favourite text editor for gedit in the instructions below. If you are not a sudoer, then you must either make yourself one, as root, or run your text editor as root.

In a terminal window, at the prompt, type:

$ sudo gedit /etc/hosts

The text in your /etc/hosts file will look something like the following if you are on a default Debian install:

127.0.0.1	localhost
127.0.1.1	name-of-your-server

# The following lines are desirable for IPv6 capable hosts
::1     ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

Assuming that the IP address of your Koha server is 192.168.1.136 and assuming you are going to call your library libraryname, then after the line for localhost, insert two new lines that say:

192.168.1.136 libraryname.peredur.cym
192.168.1.136 libraryname-intra.peredur.cym

This ensures that all requests to the two sub-domains will be sent to the server with the IP address 192.168.1.136 (your Koha server).

Save the /etc/hosts file.

NOTE: if you use the /etc/hosts file to define your domain, you will need to make entries like the ones above in the /etc/hosts files of all the computers that need to access Koha; not just the one on the Koha server. That’s why it’s only a good solution for small networks!

Editing koha-sites.conf

In gedit (or your favourite text editor) open the /etc/koha/koha-sites.conf file for editing. Remember to open it using sudo:

$ sudo gedit /etc/koha/koha-sites.conf

or as root.

Koha’s defaults are contained in this file. You need to make some alterations to the virtual hosts creation variables section to make Koha work on your network. By default, this section looks like:

#Apache virtual hosts creation variables

DOMAIN=".myDNSname.org" 
INTRAPORT="80" # use 8080 for an IP-based install. 
INTRAPREFIX="" 
INTRASUFFIX="-intra" 
OPACPORT="80" 
OPACPREFIX="" 
OPACSUFFIX="" 

The only line that is of interest for a basic installation is the DOMAIN line. Assuming your domain is called peredur.cym, then change this line to:

DOMAIN=".peredur.cym" 

Note the full stop at the start of the domain name.

The INTRASUFFIX defines the suffix used to access the staff site. It can be anything you want, but if you change it, remember to change the name of the sub-domain, via DNS or the /etc/hosts file(s), to match.