This is an old revision of the document!
Table of Contents
This is a Work in Progress. Not usable yet.
Installing prerequisites on Gentoo (x86 64-bit)
Using Gentoo 2008.0, dual-core x86 64-bit processor, emerge synced and world updated 2010/10/29.
Development with OpenSRF 1.6.1 last successfully tested …..
USE flags
As the root user, add the following USE flags to /etc/make.conf
:
USE="-ldap apache2 mpm-prefork perl postgres gif jpeg png urandom web" APACHE2_MPMS="prefork"
Add the opensrf user
The opensrf
user is required to start the OpenSRF services that constitute Evergreen.
- As the root user, issue the following command to create the user and set the password:
useradd -m -s /bin/bash opensrf passwd opensrf
Compile and runtime environment
Gentoo relies on files in /etc/env.d/
to set the system environment. We will create our own file with settings required for Evergreen. Perform the following steps as the root user.
- Open a new file (
/etc/env.d/88evergreen
) in a text editor. The name is actually rather arbitrary, but should start with two digits and must not conflict with any other files in the same directory. - Add the following lines to the file:
LDPATH="/openils/lib" PATH="/openils/bin" PERL5LIB="/openils/lib/perl5:/usr/lib/perl5/site_perl/5.12.2/x86_64-linux:/usr/lib/perl5/vendor_perl/5.12.2/x86_64-linux/Bundle"
You might need to adjust the
PERL5LIB
variable to reflect your own architecture, and eventually a newer version of Perl. - Open another new file (
/etc/env.d/89libdbi
) in a text editor. Add the following line to the file:LDPATH="/usr/local/lib/dbd"
- Run
env-update
to commit the corresponding changes to the system environment.
Installing memcached
Perform the following steps as the root user:
- Install the memcached package:
emerge memcached
- Restrict memcached to only listen to this machines' IP address (might only be necessary for a single-machine instance?) by editing the LISTENON variable in
/etc/conf.d/memcached
:LISTENON="127.0.0.1"
- Start memcached at system boot:
rc-update add memcached default
Installing libmemcache
libmemcache
provides a C API for putting and getting cached values from memcached
.
The current stable version of libmemcache
in Gentoo (1.2.0) is subject to memory corruption problems; therefore, we install the pre-release unstable version of libmemcache
(1.4.0-rc2). Perform the following steps as a root user:
(if /etc/portage directory doesn't exist, create it) echo "dev-libs/libmemcache" >> /etc/portage/package.keywords emerge libmemcache emerge libmemcached
Installing PostgreSQL
Current: postgresql-server-8.4.4-r1
emerge postgresql-server emerge --config =dev-db/postgresql-server-8.4.4-r1 rc-update add postgresql-8.4 default /etc/init.d/postgresql-8.4 start
Create the database
We need to create the database that Open-ILS will use:
createdb -U postgres -E UNICODE evergreen
Add tsearch2, table functions, and extra languages
We need to add tsearch2, table functions, and the plpgsql language to the Open-ILS database:
psql -U postgres evergreen pg# \i /usr/share/postgresql-8.4/contrib/tsearch2.sql pg# \i /usr/share/postgresql-8.4/contrib/tablefunc.sql pg# \q createlang -U postgres plpgsql evergreen createlang -U postgres plperl evergreen createlang -U postgres plperlu evergreen
Change the postgres administrator password
You might as well change the password for the postgres
user in the PostgreSQL database now. Note that this is not the system password stored in /etc/passwd
; this is PostgreSQL's internal user authentication mechanism.
psql -U postgres evergreen pg# alter user postgres password 'postgres'; pg# \q
Installing ejabberd
Check the revision history of this page if you want instructions for using Wildfire as an alternative Jabber server.
Perform the following steps as the root user:
emerge ejabberd rc-update add ejabberd default
Installing Apache2
Perform the following steps as the root user:
- We'll emerge
mod_perl
and let that take care of all of the dependencies, including Apache 2 itself:emerge mod_perl
- Enable mod_perl and SSL by editing
/etc/conf.d/apache2
:APACHE2_OPTS="-D PERL -D SSL -D PROXY -D CACHE"
- Create a symbolic link from
/etc/apache2/httpd.conf
to/etc/apache2/apache2.conf
to enable the Evergreen Apache modules to be installed and configured correctly:ln -sf /etc/apache2/httpd.conf /etc/apache2/apache2.conf
- Enable the Apache process to read the
/openils/var/web
and/openils/var/cgi-bin
files by editing/etc/apache2/httpd.conf
to start the Apache process as theopensrf
user:User opensrf Group opensrf
- Copy
eg.conf
andeg_vhost.conf
fromILS/Open-ILS/examples/apache/
into the/etc/apache2/vhosts.d/
directory. - Modify
eg.conf
to set the appropriateServerName
,ServerAlias
, andAllow from
settings. Here is theeg.conf
file used in the Gentoo VMWare image: eg.conf.txt - Modify the eg_vhost.conf file
SSLCertificateFile
andSSLCertificateKeyFile
settings to point to/etc/apache2/ssl/server.crt
and/etc/apache2/ssl/server.key
respectively. Modify CustomLog to point to a file location to which the apache user can write. - Here is the
eg_vhost.conf
file used in the Gentoo VMWare image: eg_vhost.conf.txt - Add
startup.pl
to/etc/apache2/vhosts.d/eg.conf
: Here is thestartup.pl
file used in the Gentoo VMWare image: startup.pl.txt
Installing Perl modules
Gentoo doesn't provide all of the modules available in CPAN, and certainly not the most interesting ones used by Open-ILS.
We'll use Gentoo's Perl build, but go with CPAN for the rest of the modules.
- The Net::ZOOM Perl module requires
yaz
version 2.1.50 or higher. At the moment, the ebuild foryaz
is 2.1.42 - so we have to build yaz from source. Perform these steps as a regular user, such asopensrf
:wget http://ftp.indexdata.dk/pub/yaz/yaz-2.1.56.tar.gz tar xzf yaz-2.1.56.tar.gz cd yaz-2.1.56 ./configure make
- Perform the following step as the root user:
make install
- We depend on the
aspell-en
ebuild for theText::Aspell
Perl module. If you are starting from Gentoo 2007.0, you might run into a blocking ebuild that requires you to first unmergeaspell-en
, then re-emerge it as the root user:emerge --unmerge aspell-en emerge aspell-en
- We depend on the
spidermonkey
(1.6 or higher) ebuild for theJavaScript::SpiderMonkey
Perl module.spidermonkey-1.6
is the stable ebuild on the~x86
architecture; other architectures may have to use an unstable ebuild or build spidermonkey from source. On~x86
, perform the following step as the root user:emerge spidermonkey
- Now we can install the CPAN modules as the
opensrf
user. We set themakepl_arg
parameter in CPAN to install all of these modules into the/openils/
directory structure, so that we can avoid conflicting with the core versions of the Perl modules that we might have installed via ebuilds. Perform the following steps as the root user:mkdir -p /openils/lib/perl5 chown -R opensrf:opensrf /openils
- Perform the following steps as the
opensrf
user:
export PERL5LIB=/openils/lib/perl5 perl -MCPAN -e shell shell> o conf makepl_arg 'PREFIX=/openils LIB=/openils/lib/perl5' shell> o conf commit shell> install Bundle::CPAN shell> reload cpan shell> install Cache::Memcached DBI DateTime DateTime::Format::ISO8601 FreezeThaw JSON::XS Net::Server UNIVERSAL::require Unix::Syslog XML::LibXML
We need Net::Jabber
to register users with ejabberd. The gsasl ebuild is required for authentication. I found that I had to select no when asked if I wanted to install the optional GSSAPI module for XML::Stream
, one of its underlying modules, to avoid severe test failure. I stopped ejabberd before installing this module to avoid any port conflicts during the Net::Jabber
tests. Finally, a few Net::Jabber
tests failed anyways, so I forced the install of that module.
If the Net::Jabber
install fails for you as well:
- Perform the following steps as the root user:
/etc/init.d/ejabberd stop emerge gsasl
- Perform the following steps as the
opensrf
user:perl -MCPAN -e shell shell> install Authen::SASL XML::Stream Net::XMPP shell> force install Net::Jabber
Installing libdbi and libdbi-drivers
The generic instructions worked well using libdbi-0.8.2 and libdbi-drivers-0.8.2-1 releases. You do not need to specify a directory for the –with-pgsql
option because we're using the ebuild version of PostgreSQL, so the libdbi-drivers step looks like:
./configure --with-pgsql-dir --disable-docs --with-pgsql --enable-libdbi && make all install
Installing OpenSRF
As of Evergreen 1.2.0, you have to download and install OpenSRF separately from Evergreen. Perform the following steps as the opensrf
user:
- Download OpenSRF:
wget http://open-ils.org/downloads/OpenSRF-0.9.tar.gz
- Extract OpenSRF:
tar xzf OpenSRF-0.9.tar.gz
- Change directories into the OpenSRF directory:
cd OpenSRF-0.9
- Open
install.conf
in a text editor and set the default Gentoo settings formake
configuration:export APXS2=/usr/sbin/apxs2 export APACHE2_HEADERS=/usr/include/apache2 export APR_HEADERS=/usr/include/apr-1/ export LIBXML2_HEADERS=/usr/include/libxml2/
- Build OpenSRF:
CFLAGS=-D_LARGEFILE64_SOURCE make
- Install OpenSRF by performing the following step as the root user:
make install
Register OpenSRF users
We have to register the users listed in opensrf_core.xml with our Jabber server. OpenSRF includes a simple script to do this based on Net::Jabber. In our case, we will register two users, "osrf" and "router", each of which uses the password "osrf":
# starting in the OpenSRF directory cd examples perl register.pl localhost 5222 osrf osrf perl register.pl localhost 5222 router osrf
Installing Evergreen
Perform the following steps as the opensrf
user:
- Download Evergreen:
wget http://open-ils.org/downloads/Evergreen-ILS-1.2.0-rc4.tar.gz
- Extract Evergreen:
tar xzf Evergreen-ILS-1.2.0-rc4.tar.gz
- Change directories into the Evergreen directory:
cd Evergreen-ILS-1.2.0-rc4
- Set the configuration for your system; aside from the database name, username, and password, you should only have to change the following settings on Gentoo:
Apache2 apxs binary = /usr/sbin/apxs2 Apache2 headers directory = /usr/include/apache2 Apache2 APR headers directory = /usr/include/apr-1 Libxml2 headers directory = /usr/include/libxml2
- Due to some confusion caused by apxs,
make install
will fail if it cannot find/etc/apache2/apache2.conf
. Perform the following hack as the root user to fix that problem:ln -sf /etc/apache2/httpd.conf /etc/apache2/apache2.conf
- Build Evergreen as the
opensrf
user:CFLAGS=-D_LARGEFILE64_SOURCE make
- Install Evergreen as the root user:
make install
- Change permissions on the Evergreen directories to enable the system to run as the root user:
chown -R opensrf:opensrf /openils chmod -R +x /openils/var/cgi-bin
- Edit the
/etc/apache2/httpd.conf
file to correct the LoadModule directives that were added for the mod_xmlent and osrf_json_gateway modules.apxs2
mistakenly tells Apache to load the modules from thelib/apache2/modules/
directory, when (as of Apache 2.2.4 on Gentoo) the prefix should just bemodules/
. As the root user, adjust the lines to read as follows:LoadModule osrf_json_gateway_module modules/osrf_json_gateway.so LoadModule xmlent_module modules/mod_xmlent.so
- Create symbolic links to support Windows staff clients and versionless staff clients as the
opensrf
user:cd /openils/var/web/xul/ rm HEAD ln -sf /root/Evergreen-ILS-1.2.0-rc4/Open-ILS/xul/staff_client/build/ HEAD ln -sf HEAD sc_v100_rc2 ln -sf HEAD rel_1_2_0_rc4
Starting Evergreen
- Become the
opensrf
user:su - opensrf
- Run the
osrf_ctl.sh
script to start up all of the services. We start the services individually because there is a race condition that can affect the C services if the Perl services have not completely finished initializing:/openils/bin/osrf_ctl.sh -c /openils/conf/opensrf_core.xml -a start_router /openils/bin/osrf_ctl.sh -c /openils/conf/opensrf_core.xml -a start_perl /openils/bin/osrf_ctl.sh -c /openils/conf/opensrf_core.xml -a start_c
- (Required only once): Run the
autogen.sh
script to generate the JavaScript and OrgTree HTML files:cd /openils/bin autogen.sh /openils/conf/opensrf_core.xml
- Become the root user and start Apache (which now depends on the open-ils services before it can start successfully):
exit su - /etc/init.d/apache2 start