Koha on ubuntu - packages long
Introduction
These instructions have been tested with Ubuntu 12.04 LTS and Ubuntu 13.04 specifically. We strongly recommend an LTS release, though anything higher should work.
The current supported versions of Koha include newer libraries, which are not easily available under previous LTS releases. So please, do not attempt to install Koha on anything prior to Ubuntu 12.04 LTS. Your success may vary, and you will not be supported.
From time to time you will see the word "nano." This is a generic text editor that works inside a terminal session. Please feel free to substitute your favourite editor (vi, emacs, gedit, or etc.) If a desktop version of Ubuntu is installed, which is not recommended, and you are unfamiliar with linux editors, the GUI gedit may be the preferred user-friendly editor of choice.
For example: The two instructions listed below are the same:
- Type the following command in the terminal window:
- sudo nano myimportantfile.cfg
- Type the following command in the terminal window:
- sudo gedit myimportantfile.cfg
These instructions focus on the recommended koha-common packages installation. Packages effectively do most of the difficult work. The koha-common package will automatically install koha's dependencies if they are not already present on your system. The only exception is that a local MySQL server is installed separately, because there is the possibility of using an external MySQL server. Other Installation methods, such as 'git' for assisting with development and improvements or 'tarball' which is not recommended and only mentioned for historical purposes, will not be discussed in this document. You can read the Debian package instructions for additional information.
If you are able to assist with the development and improvement of Koha and this isn't for a production environment, consider installing a git version. Git is a version control system. Try to learn version control using git!
The packages install, the git install, and the tarball install all have different directory structures. Do not attempt to correct tarball or git problems by following these instructions afterwards.
Pre-Installation Setup
Notation
Lines beginning with # or $ mean the suffix is a command that should be executed on the shell. That is, the part after given prompt. Don't type or copy the # or $ part. For instance:
$ sudo su - ... # echo "Hello world"
means to run the commands sudo su - and echo "Hello world".
Lines beginning with > mean the suffix is a command that should be run within a MySQL shell. For example,
> SHOW DATABASES;
will show the available databases on a MySQL server.
Koha is released monthly, so keeping documentation up to date is difficult. Rather than saying 3.8.1, 3.8.2, 3.8.3, 3.8.4, or any other specific number, the convention is to replace the last number with an x. For example, the current version is part of the 3.14.x series and the former stable version is the 3.12.x series.
Install Ubuntu
Download and install Ubuntu from the official site.
To keep your Koha installation minimal and to free resources for running, the Server edition is recommended, though the Desktop edition will be easier for beginners.
As Apache and MySQL will be installed in the instructions later, there is no need to select any extra packages during the installation of Ubuntu.
Add A Koha Community Repository
If you installed the Desktop version, Ubuntu defaults to a desktop called Unity. Run your mouse over the icons on the left and find "Dash Home" and left click it. Type "Terminal" on the top line. You will see a Terminal icon appear. Double click that icon. You will now be able to enter the commands in these instructions. Alternatively, you may use CTRL + ALT + 'T' to get the Terminal Screen.
These instructions still function even though the latest version of Debian is wheezy. If the version has changed again, please confirm these instructions on the mailing list or IRC channel.
Getting prompted for a password in the middle of a command line is confusing. To prevent this:
$ sudo ls
Create Repository File
There are three repositories for Debian packages of Koha. They include required dependencies that are missing from Ubuntu. They represent different versions Koha:
- stable release
- old-stable release
- development release
The squeeze repository is the recommended default repository to use. To be a bit more conservative, the old-stable release can be used instead.
To install the current stable release, which is recommended:
$ echo deb http://debian.koha-community.org/koha squeeze main | sudo tee /etc/apt/sources.list.d/koha.list
To use the older stable release:
$ echo deb http://debian.koha-community.org/koha oldstable main | sudo tee /etc/apt/sources.list.d/koha.list
or to use the development release:
$ echo deb http://debian.koha-community.org/koha squeeze-dev main | sudo tee /etc/apt/sources.list.d/koha.list
Install Repository Key
Add the key in gpg.asc to your APT trusted keys to avoid warning messages on installation.
$ wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -
Update Ubuntu
Now that you have added the appropriate repository, check to make sure Ubuntu is up to date. You may be prompted for the password of the user account you are signed in as.
$ sudo apt-get update $ sudo apt-get upgrade $ sudo apt-get clean
This process, particularly the upgrade step, may take a while.
Installation Method
At this point, we are doing a packages installation. It will simplify installation and upgrade steps later. If development and patching will be done, consider using a git installation. For historical purposes, there is a tarball installation method as well.
Download and install the latest Koha release
Do the following command:
$ sudo apt-get install koha-common
Use Upgraded MARC::File::XML
$ wget http://ftp.ubuntu.com/ubuntu/ubuntu/pool/universe/libm/libmarc-xml-perl/libmarc-xml-perl_1.0.1-1_all.deb $ sudo dpkg -i libmarc-xml-perl_1.0.1-1_all.deb
Pre-Web Install Setup
Initial Configuration
To configure your server for use, edit /etc/koha/koha-sites.conf with details about your site. You may need to create this file.
$ sudo nano /etc/koha/koha-sites.conf
Some example content would be:
DOMAIN=".myDNSname.org" # Change this to be your domain. Any instance will be a subdomain of this string. INTRAPORT="80" # TCP listening port for the administration interface INTRAPREFIX="" # For administration interface URL: Prefix to be added to the instance name. INTRASUFFIX="-intra" # For administration interface URL: Suffix to be added to the instance name. DEFAULTSQL="" # a value is generally not needed. OPACPORT="80" # TCP listening port for the users' interface (if you skip this, the apache default of 80 will be used) OPACPREFIX="" # For users' interface URL: Prefix to be added to the instance name. OPACSUFFIX="" # For users' interface URL: Suffix to be added to the instance name. ZEBRA_MARC_FORMAT="marc21" # Specifies format of MARC records to be indexed by Zebra. Possible values are 'marc21', 'normarc' and 'unimarc' ZEBRA_LANGUAGE="en" # Primary language for Zebra indexing. Possible values are 'en', 'fr' and 'nb'
Please see your Network Administrator to clarify any uncertainties for the DOMAIN entry.
If you follow the example without changing anything, you will get a working Koha system set up as http://library.myDNSname.org for the OPAC client and http://library-intra.myDNSname.org for the Staff client.
Should you be unable to get a domain name, change the INTRAPORT to 8080. Then access will be possible via the http://IPaddress:8080/ for the staff client and http://IPaddress/ for the OPAC client. The above sample represents the recommended settings, because library-intra.myDNS.org:8080 is an example of poor network configuration.
Instance Creation
Now you need to create your first koha instance. This instance will need a database. It can be external or local.
If you will be using a local database:
This may already be installed depending on what options were selected when installing Ubuntu. Run this anyways:
$ sudo apt-get install mysql-server
The koha-create command writes out Apache configuration files. It requires the Apache mod_rewrite module to be enabled:
$ sudo a2enmod rewrite $ sudo service apache2 restart
Replace "library" with the name of your library. If you want to have library.myDNSname.org, then instancename can probably be "library". Use the following command, which rarely needs changes, to create a local database to create an instance called library:
$ sudo koha-create --create-db library
If you will be using an external database refer to the documentation
Ubuntu MySQL Security Tweak
There is a security risk in Ubuntu's MySQL default set up. Type the following commands:
$ mysql -u root -p > USE mysql; > SELECT host,user FROM user;
Under Ubuntu, newer versions of MySQL include anonymous connections. This is a security risk. They are listed with no username. Continue entering MySQL commands.
> DELETE FROM user WHERE user=''; > SELECT host,user FROM user;
The anonymous connections should be removed now. Continue entering MySQL commands.
> FLUSH PRIVILEGES; > QUIT
The anonymous connections are removed.
Configuring Apache
Setup Default Ports
Then type the following command:
$ sudo nano /etc/apache2/ports.conf
Make sure there is an uncommented line like this in the ports.conf file (do not add it twice!):
Listen 80
If you use a different set of port numbers in the INTRAPORT and OPACPORT back in the Initial_Configuration step, you will need to have a "Listen {INTRAPORT}" and "Listen {OPACPORT}", ensuring to change {INTRAPORT} and {OPACPORT} to the port numbers you chose.
Remember you chose an OPAC prefix or suffix and an Intranet prefix or suffix in an earlier step. This is how port 80 knows which files to access, because it uses named virtual hosts.
Make sure the NameVirtualHost line is uncommented like the following (do not add it twice!):
NameVirtualHost *:80
If you use a different set of port numbers in the INTRAPORT and OPACPORT back in the Initial_Configuration step, you will need to have a "NamedVirtualHost *:{INTRAPORT}" and "NamedVirtualHost *:{OPACPORT}", ensuring to change {INTRAPORT} and {OPACPORT} to the port numbers you chose.
Disable or Edit Default Site
If you are running Drupal or any other web service on the same machine, do not disable the default site! If you are unsure, do not disable the default site! When in doubt, always talk with your system administrator, network administrator, or IT Department. The following is intentionally not boxed to prevent problems arising from improperly disabling the default site. If and only if Koha is the only thing on this server, then feel free to run this to disable the default site: sudo a2dissite 000-default
You may wish to change the port number of the default site, but again always talk with your system administrator, network administrator, or IT Department. This can be done with: sudo nano /etc/apache2/sites-enabled/000-default
And then change the port number it uses: <VirtualHost *:4080>
4080 is an arbitrary port number. These commands should be used after consulting with your system administrator, network administrator, or IT Department.
Enable Modules and Site
Now enable the apache modules this config needs, enable koha's configuration, and restart apache. Replace "library" with the name of your library that you used in the "Instance Creation" section when you ran koha-create..
$ sudo a2enmod deflate $ sudo a2ensite library $ sudo service apache2 restart
Determining an IP Address
Assumptions
In a home or corporate LAN, it is quite likely that your network setup has been configured with DHCP. If you are being hosted externally however, your machine likely has been given a static IP address, or it may be behind a reverse proxy. Because of the many possible complex configurations of networking involved, these instructions will attempt to guide you in the former simpler case.
If you are unable to get to the Web Installation step, please consult your system administrator, network administrator, or IT Department. We are unable to assist everyone with their networking configurations.
Private IP Addresses
The following IP ranges will not be available via the Internet:
- 10.0.0.0 - 10.255.255.255
- 172.16.0.0 - 172.31.255.255
- 192.168.0.0 - 192.168.255.255
Also, IP addresses in the range of 169.254.0.0 -169.254.255.255 are reserved for Automatic Private IP Addressing.
If you have a computer on the same network (as in the general home or corporate LAN scenario), you can use a nice graphical browser and the IP Address we determine to run the web install steps, and use Koha afterwards. If you have a hosted site with a fully qualified domain name, you may be able to use that. Otherwise, your scenario requires assistance from your hosting provider or network administrator. Regardless, the instructions as given and written will work to set up Koha.
Determine Address
Determine if there is at least one network card in it. Type the following:
$ sudo ifconfig
This should give output like:
eth0 Link encap:Ethernet HWaddr 08:00:27:14:22:6c
inet addr:192.168.69.38 Bcast:192.168.69.255 Mask:255.255.255.0
inet6 addr: fe80::a00:27ff:fe14:226c/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:24087 errors:0 dropped:0 overruns:0 frame:0
TX packets:29550 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:2968198 (2.9 MB) TX bytes:4828089 (4.8 MB)
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:16436 Metric:1
RX packets:11 errors:0 dropped:0 overruns:0 frame:0
TX packets:11 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:3794 (3.7 KB) TX bytes:3794 (3.7 KB)
In this example, there is "eth0" and "lo". "lo" is not accessible from another machine. "eth0" has an "inet addr" (IP Address) of "192.168.69.38".
If this IP address was not listed in the private IP addresses section above, it may be possible to use it as well. So when the web install steps are reached, instead of installing lynx and using it, Firefox (or any other browser) can be used from another machine by typing "http://" plus the name you have set for the intranet client (staff client) into the address bar. This is an external address. Attempt external addresses before private ones.
This example has a private IP address: "192.168.69.38". So when the web install steps are reached, instead of installing lynx and using it, Firefox (or any other browser) can be used from another machine on the same network by typing "http://library-intra.myDNSname.org/" into the address bar. This is because you will have put the address (eg. 192.168.69.38) and the fully qualified domain name into the /etc/hosts file of that other machine.
If there is more than one network card (e.g. eth1, eth2, etc.), attempt the IP Addresses in order until you have success or all fail. A typical failure is some sort of "time out" page. Eventually, you may just have to do a local install using 127.0.0.1, because other machines could not reach it.
Tweak Hosts File
The default configuration for the packages installation is based on fully qualified domain name set up. Since your fully qualified domain name may not be active yet, edit the /etc/hosts file to include it:
$ sudo nano /etc/hosts
Add (do not replace!) at the bottom, and the address you determined and what should be the fully qualified domain name. For example, the two lines added (one for the OPAC client, and one for the Staff Client) could look like this:
127.0.0.1 library.myDNSname.org 127.0.0.1 library-intra.myDNSname.org
If you were able to determine an IP address in the previous step, edit the other machine's /etc/hosts file with that IP address instead of 127.0.0.1.
Fully Qualified Domain Name
If you are hosted and you happen to know the fully qualified domain name (e.g. library-intra.myDNSname.org), you can attempt "http://library-intra.myDNSname.org:80/". This should not fail, if you have put the correct information into the hosts file.
Web Installation
Now you can visit your admininstration website to continue with the Koha web installer.
The user name to log in with will be koha_library and the password will be near the end of /etc/koha/sites/library/koha-conf.xml, where library is the instance name used by the koha-create command in the Instance Creation section. Make sure to replace library with your instance name. You will need to be root to view this You could also use this command:
$ sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/library/koha-conf.xml
to print it out.
Do this by navigating to your staff client page. The INTRAPREFIX, instance name, and INTRASUFFIX you used followed by the DOMAIN, a colon, and the INTRAPORT you gave in the Initial Configuration section make up the url. For example: http://library-intra.myDNSname.org:80
You can do this by installing lynx and going there on your koha machine:
$ sudo apt-get install lynx $ lynx http://library-intra.myDNSname.org:80
Lynx navigational keys include: tab to go between fields, enter (when not on text fields) to toggle or click, space to change pages (when not on text fields), Q to quit (when not on text fields). Arrows also work.
Web Installer Step 1
Choose Language
Use en for English.
Click Next
It will check to make sure all dependencies are installed. You will have to install
all items listed here, before you can continue.
It should say: All dependencies installed.
Click Next.
Web Installer Step 2
This shows the "Database settings".
Click Next
It will check to make sure it can connect to mysql, that the kohadata database
exists, and the user koha has all of the required privileges on the database
koha_library.
It should say:
Connection established.
Database koha_library exists.
User koha_library has all required privileges on database koha_library.
Click Next.
Web Installer Step 3
We are now ready to create the database tables and fill them with some default data.
Click Next.
It should say:
Success
*Database tables created
Click Next.
We are ready to do some basic configuration. Please install basic configuration settings to continue the installation.
Click on the link install basic configuration settings.
Select your MARC flavour.
Select Marc21.
Click Next.
Select Default Settings.
(Select everything, if you are testing.)
You may find it helpful to select all of the optional MARC frameworks.
One option that would be better to leave unchecked and to setup yourself in Koha is (sample_libraries). It adds about 10 sample libraries to koha. It is easy to enter your Library’s information in Koha and you will need to do that anyway.
Click Import.
It shows a list of items added and will report any errors here as well.
Click Finish.
Congratulations , Setup Complete.
Your page will be redirected to the login page after completing installation.
Setup Your Library in Koha
After the web install, you should be redirected to the staff client login screen.
Login with koha user name and password.
Click on the More dropdown menu.
Select Administration.
Select Libraries, branches and groups under the “Basic Parameters” heading.
Click New Library and enter your information into the form.
Click Submit.
Your Library is now setup in Koha.
Base Install Finished
The staff client, or administrative page, can be accessed at:
http://{INTRAPREFIX}{InstanceName}{INTRASUFFIX}{DOMAIN}:{INTRAPORT}
The OPAC, or client page, can be accessed at:
http://{OPACPREFIX}{InstanceName}{OPACSUFFIX}{DOMAIN}:{OPACPORT}
Where the values of {DOMAIN}, {INTRAPORT}, {INTRAPREFIX}, {INTRASUFFIX}, {OPACPORT}, {OPACPREFIX}, and {OPACSUFFIX} were defined in the Initial Configuration step, and {InstanceName} was defined in the Instance Creation step, though the example given said library.
You should now have a functional Koha Installation
Upgrade Instructions
If you are running in another language other than English, please switch to English before doing the upgrade, the templating system has changed and the templates will need to be regenerated. Once you have upgraded, please regenerate your templates in your chosen languages.
$ sudo apt-get update $ sudo apt-get upgrade
This should generally upgrade your koha-common. However, in special cases, you may have to:
$ sudo apt-get dist-upgrade
Because the dependencies for koha have increased.
Koha 3.4.x or later no longer stores items in biblio records. If you are upgrading from a version older than Koha 3.4.x, run the following command which may take a long time (several hours) to complete for large databases: koha-upgrade-to-3.4
It is always safest to run a full reindex after an upgrade, where {instance} is the name of your instance:
$ koha-rebuild-zebra -v -f {instance}
Uninstall Instructions
The package installation method is unique in that a removal command is already provided. Determine what instances you have:
$ koha-list
And then for each instance:
$ sudo koha-remove {instance}
If you encounter any problems, please request help on the mailing list or IRC channel.
After uninstalling all the instances, uninstall the koha-common package:
$ sudo apt-get remove koha-common
Home > Documentation
Home > Documentation > Installation
Home > Documentation > Installation > Debian Packages
Home > Koha Versions > 3.10
Home > Koha Versions > 3.12
Home > Koha Versions > 3.4
Home > Koha Versions > 3.6
Home > Koha Versions > 3.8
Koha > Technical > Administration
Koha > Technical > Administration