Koha on Debian
From Koha Wiki
Home > Documentation > Installation
Home > Documentation > Installation > Debian Packages
Home > Documentation > Installation > Installation alternatives
Koha > Technical > Administration
Koha > Technical > Administration
Koha > Technical > Administration
Debian Packages on Koha
The Debian packages are the preferred, and easiest, way to install Koha on Debian based operating systems, including Ubuntu and Mint.
OS versions known to work:
- Debian 8 (Jessie)
- Ubuntu 16.04)1
1 Koha does not work well with MySQL 5.7 which is shipped with Ubuntu 16.04. use MariaDB instead.
Commands that are in a box and start with '$'
$ like this
are intended to be run at the command line of your server (but don't include the '$'.)
Set up package sources
Add the GPG key to your system so that you know that the packages haven't been tampered with:
$ wget -q -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -
Pick what version of Koha you want:
- oldstable (16.05) follows one release behind the current stable release
- stable (16.11) is the current stable release
- unstable (master) follows the current development, this is intended for developers and testers only
If you chose oldstable:
$ echo 'deb http://debian.koha-community.org/koha oldstable main' | sudo tee /etc/apt/sources.list.d/koha.list
If you chose stable:
$ echo 'deb http://debian.koha-community.org/koha stable main' | sudo tee /etc/apt/sources.list.d/koha.list
Update the package list:
$ sudo apt-get update
$ sudo apt-get install koha-common
Aside: a common problem on Ubuntu happens here
If you see this:
Errors were encountered while processing: libapache2-mpm-itk apache2-mpm-itk koha-common
Then do this:
$ sudo a2dismod mpm_event $ sudo apt-get install -f
And everything will fix itself up.
Install the Database
Koha does not work well with MySQL 5.7 which is shipped with Ubuntu 16.04. use MariaDB instead.
If you are planning to run MySQL on the same server that Koha is on, then run:
$ sudo apt-get install mysql-server
Configure the defaults
Edit the file /etc/koha/koha-sites.conf and adjust it to suit the configuration that you'd like.
Set the DOMAIN value to the domain you wish to access this Koha from. Also pay attention to the INTRASUFFIX as your DNS entries will also require this. Instructions for setting up a domain for Koha can be found on the page How to set up a domain name for Koha.
If your catalogue is not MARC21, change ZEBRA_MARC_FORMAT. You may also adapt ZEBRA_LANGUAGE.
Set up Apache
$ sudo a2enmod rewrite $ sudo a2enmod cgi $ sudo service apache2 restart
Create a Koha instance
Only do this if you are running MySQL locally.
Replace libraryname with the name of your library:
$ sudo koha-create --create-db libraryname
For more options see Commands provided by the Debian packages#koha-create.
If you are running MySQL on another server:
- remove /etc/mysql/koha-common.cnf
- create a new file in its place containing the connection information for the server, in the form of a my.cnf file.
- read the man pages for koha-create, paying attention to the information on --request-db and --populate-db.
Access the web interface
You will need to have your DNS set up for this. The default hostnames are:
- libraryname.domain for the public interface
- libraryname-intra.domain for the staff interface
- libraryname is the name provided to koha-create
- domain is the value of DOMAIN that you set in /etc/koha/koha-sites.conf
If you want to change the hostname details of the instance, you can edit /etc/apache2/sites-enabled/libraryname.conf
Open a web browser, and point it to your staff interface, by going to http://libraryname-intra.domain, or whatever you manually configured.
When you see the login for the Koha installer, the username and password are in the koha-conf.xml file for the instance. You can view them:
$ sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/libraryname/koha-conf.xml koha_libraryname $ sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/libraryname/koha-conf.xml randompasswordtext
By default, email is turned off. This is to let you get everything set up before you risk sending unwanted notices to people. To turn email on:
$ sudo koha-email-enable libraryname
Translations can be installed:
$ sudo koha-translate --install language-code
To see all the language codes:
$ sudo koha-translate --list --available
There is a list of Commands provided by the Debian packages. All commands begin with koha-, and have man pages installed, for example:
$ man koha-create
Koha installs a service in /etc/init.d/koha-common. This ensures that the zebra daemon and, if configured, SIP daemon are running. You can use the start, stop, and restart commands to control these.
Koha Packaging Information
The stable package has a new release whenever the release maintainer for the current stable version creates a new version. As soon as a new major version is released, this will be updated with it too (within a couple of days ideally, anyway.)
The oldstable package has a new release whenever the release maintainer creates a new version. If a new major version version is released into stable, this will go up to the next major version that is behind stable. This means that you will get a new major release only after it's been out for several months and hopefully all the bugs have been found.
The unstable package is released whenever:
- the package maintainer remembers to do it (every couple of weeks, typically. More sometimes.)
- the current master branch is able to be built without errors.
How koha-create configures your system
When you create an instance with koha-create, a few things happen. For the sake of example, this assumes that the instance you created is called library.
- A system user is created, called library-koha. All things to do with this instance will be run as this user.
- (If you have a local MySQL) a new MySQL user is created called koha_library
- (If you have a local MySQL) a new MySQL database is created called koha_library
- /var/lib/koha/library is created and populated with a default directory structure.
- The Koha sites directory (/etc/koha/sites/library) is created and populated. In particular, a koha-conf.xml is generated and put there with the passwords that were randomly generated for the database and zebra.
- An apache configuration file is put in /etc/apache2/sites-available/library.conf. Apache is restarted to make the change take effect.
- A Zebra daemon for this instance is started, running as the library-koha system user.
- Using the Index Daemon with the packages
- Newbie guide - to begin the working configuration
- Building Debian Dependencies - what to do if we need to add a new dependency that's not in Debian