Kete.net.nz: Documentation

Topic: Debian Etch Installing Required Software

Topic Type: Topic

Describes the steps necessary for installing Kete's required software on a Debian Etch host.

Originally written by Walter McGinnis, Kete Project Lead for Katipo Communications, Ltd.

Part of the Installation Guide

Install Required Software for Running Kete

Note: all of the commands on this page are run as root, so if you close the console, make sure you 'su' back to root before continuing

First, lets setup a new source where we can grab the latest Git from. We'll need it to grab the source code later on. In a new console run

$ su
root@host: # vim /etc/apt/sources.list

Add to that file the line

deb ftp://ftp.nz.debian.org/backports etch-backports main contrib non-free

Change .nz. to the closest mirror where you live (.uk. for england, .au. for australia etc).

Now install the keyring so you can install from this source.

root@host: # apt-get install debian-backports-keyring

And type 'Y' at the prompt. Then lets jump into what we can grab from debian packages.

root@host: # apt-get update
root@host: # apt-get install apt-utils build-essential ruby1.8-dev rubygems imagemagick librmagick-ruby1.8 librmagick-ruby-doc libmysqlclient15off libmysqlclient15-dev mysql-server mysql-common mysql-client libmysql-ruby1.8 memcached libxslt1-dev libpcre3-dev zlib1g-dev unzip gzip mytop
root@host: # apt-get -t etch-backports install git-core git-svn git-doc

(optional - enables conversion of uploaded HTML, Plain Text, PDF, and Microsoft Word documents to the description of the document)

root@host: # apt-get install wv poppler-utils lynx

Installing the Rails framework

There are two options when it comes to installing Rails. The first is to install it on the ruby installation you setup above using apt-get. However because of a bug in the gem script that is installed with Debian, it requires an extra step to get working. The more secure option is to use Ruby Enterprise Edition, a product from the same people that make mod_rails/Passenger (discussed at the bottom of this page). It's updated a lot more regularly than Debian updates their packages, which means it has more bug and security fixes. It's also optimized to run faster than a standard installation of Ruby. It requires a few extra installation steps, but it's well worth the effort.

Installing Rails on Debian installed Ruby

Install both rails (framework) and mongrel (server) that Kete will run on. You may encounter something like "could not find blah..." when running the following commands. Rubyforge and the gem mirrors can be flaky, just try again and it will usually come right.

root@host: # gem update --system

We have to make to make a slight adjustment in the gem command to be compatible with Debian Etch (and Ubuntu, apparently) as outlined in this blog post. Run

root@host: # vim /usr/bin/gem

and add the line below, after the "require 'rubygems'" line and save

require 'rubygems/gem_runner'

Then back to our installing of software in a 'su' session...

root@host: # gem update
root@host: # gem install rails mongrel mongrel_cluster -y

Installing Rails with Ruby Enterprise Edition

The great thing about Ruby Enterprise Edition (refered to as REE) is that the installer does the installing of Ruby and Rails in one go. It takes less than 15 minutes to setup once downloaded (depending on system speed) and less than 10 minutes to update in the future (depending on the amount of sites you have). Start by following the instructions at http://www.rubyenterpriseedition.com/download.html (download, extract, install). Keep the settings as the default ones REE assigns.

Now add the following to the .bash_profile, and .bashrc filea of any users that'll affect the installation (root, kete, and yourself for example). Be sure to use the correct path for REE; it varies by release. Replace the X's in the string below.

# Use correct Ruby, RubyGem paths
PATH=/opt/ruby-enterprise-1.8.6-2008XXXX/bin:$PATH
export PATH

Then as both root and the kete user, check that we are using the correct RubyGems version:

$ which gem
/opt/ruby-enterprise-1.8.6-2008XXXX/bin/gem # should look something like this with correct date

Additional Setup Instructions

MySQL

If this is the first time MySQL is being used on the system, run the following commands (change [your_new_password] to a password of your choosing) :

root@host: # mysqladmin -u root password [new_password]

Kete also supports unicode characters, so we'll want to adjust mysql to make unicode the default for new databases. Make utf8 he default by editing /etc/my.cnf (as root) and adding this in the [mysqld] section:

# making utf8 the default
init-connect = 'SET NAMES utf8'
character-set-server=utf8
collation-server=utf8_general_ci

Save the file, and restart mysql with

root@host: # /etc/init.d/mysql restart

YAZ and Zebra

Kete relies on specific versions of YAZ and Zebra, so the older versions must be compiled from source.

root@host: #  sudo mkdir /usr/local/src
root@host: # sudo chmod 777 /usr/local/src
root@host: # cd /usr/local/src
root@host: # wget http://ftp.indexdata.dk/pub/yaz/yaz-2.1.54.tar.gz
root@host: # tar xfz yaz-2.1.54.tar.gz
root@host: # wget http://ftp.indexdata.dk/pub/zebra/idzebra-2.0.6.tar.gz
root@host: # tar xfz idzebra-2.0.6.tar.gz
root@host: # cd yaz-2.1.54
root@host: # ./configure --prefix=/usr
root@host: # make
root@host: # sudo make install
root@host: # cd ../idzebra-2.0.6
root@host: # ./configure --prefix=/usr --with-yaz=../yaz-2.1.54 --enable-mod-alvis
root@host: # make
root@host: # sudo make install

ImageMagick

The version of ImageMagick on Debian is too old for the recent rmagik gem, that we'll install later, to work. To get around this, we have to compile the recent version of ImageMagick from scratch. The following steps were borrowed from Urban Puddle blog.

root@host: # apt-get build-dep imagemagick
# Double check all dependencies are installed..
root@host: # apt-get install gcc libjpeg62-dev libbz2-dev libtiff4-dev libwmf-dev libz-dev libpng12-dev libx11-dev libxt-dev libxext-dev libxml2-dev libfreetype6-dev liblcms1-dev libexif-dev perl libjasper-dev libltdl3-dev graphviz gs-gpl pkg-config
root@host: # cd /usr/local/src
# check the ImageMagick website for updates. At the time of writing, 6.4.3 was the most recent
root@host: # wget ftp://ftp.imagemagick.org/pub/ImageMagick/ImageMagick-6.4.3-6.tar.gz
root@host: # tar xvzf ImageMagick-6.4.3-6.tar.gz
root@host: # cd ImageMagick-6.4.3
root@host: # ./configure --with-gs-font-dir=/usr/share/fonts/type1/gsfonts
root@host: # make
root@host: # make install

Add the following to /etc/ld.so.conf.d/libc6.conf: (You may need to create this file.)

# Added because we built ImageMagick from source
/usr/local/lib

Add the following to the root .bashrc and .bash_profile files

# Set LD Lib path
LD_LIBRARY_PATH=/usr/local/lib
export LD_LIBRARY_PATH

And finally, re-link the libraries:

root@host: # ldconfig

HTTP Request Server

For the following section, you have two choices to serve HTTP requests. Nginx ("engine X") or Apache2. Each has their own advantages, so the choice is yours, depending on what you have available to work with.

Note: Neither of these are nessesary when running in development or test mode. You can despense with the http request server when requests are made from the same computer as the application is being run on. When you deploy to production, then you'll want one of these setup.

Nginx

Pros: Nginx allows you to configure how many mongrel servers you want to have and at which IPs. A good choice if you plan to deploy your application around the globe.
Cons: Not Nginx related, but using Nginx requires having multiple mongrels on a single computer, and it can use a lot of memory and can be a pain to manage at deploy time.

Grab the latest tarball from http://sysoev.ru/nginx/download.html and do the following (adjust version numbers accordingly).

root@host: # cd /usr/local/src
root@host: # wget http://sysoev.ru/nginx/nginx-0.6.32.tar.gz
root@host: # tar xfz nginx-0.6.32.tar.gz
root@host: # cd nginx-0.6.32/
root@host: # ./configure --prefix=/usr/local/nginx --sbin-path=/usr/local/sbin --with-http_ssl_module
root@host: # make
root@host: # sudo make install

Lastly grab a /etc/init.d/nginx script for managing the daemon by doing this:

root@host: # sudo wget http://notrocketsurgery.com/files/nginx -O /etc/init.d/nginx
root@host: # sudo chmod 750 /etc/init.d/nginx

You'll probably want to get nginx to start up automatically at boot. To do that, open a new console and run

root@host: # update-rc.d nginx defaults

Important Note: At this point, Nginx is installed but not yet configured for our Kete site. We'll handle that in a separate step once we have Kete installed. Until then, web requests will throw an error until you have actually deployed your Kete application and started a mongrel cluster to match your settings in /usr/local/nginx/conf/nginx.conf

You may want to add /usr/local/sbin to your PATH.

root@host: # exit
$ PATH=/usr/local/sbin/:$PATH
$ export $PATH

Apache2

Pros: Quick to setup, easy to deploy and restart applications. Minimal memory consumption. Simple site configuration.
Cons: Can't deploy across mulitple Apache2 configurations.

Start by install Apache2 from apt-get if you don't already have it.

root@host: # apt-get install apache2 apache2-dev

Then install the passenger gem and install the module.

root@host: # gem install passenger
root@host: # passenger-install-apache2-module

Copy the Apache2 config lines it gives you at the end of the file to the end of your apache2.conf configuration file at /etc/apache2/apache2.conf. The lines look similar to this (paths will be different if using REE):

LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-2.0.3/ext/apache2/mod_passenger.so
PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-2.0.3
PassengerRuby /usr/bin/ruby

If it isn't already, you'll probably want to get Apache2 to start up automatically at boot. To do that, open a new console and run

root@host: # update-rc.d apache2 defaults

Important Note: At this point, Apache2 and Passenger are installed but not yet configured for our Kete site. We'll handle that in a separate step once we have Kete installed. Until then, web requests will throw an error until you have actually deployed your Kete application.

Next step:
Setting Up the Environment