Installing Evergreen ILS

Evergreen is a powerful and open-source Integrated Library System (ILS) in use by many public (and private) libraries.

This example puts all Evergreen services on one server which needs 2G RAM minimum. Larger Evergreen deployments will need to run on multiple servers.

Installing the Prerequesities

Evergreen will require PostgreSQL database, Apache web-server and OpenSRF. The required versions of these packages will vary depending on the version of Evergreen ILS being installed. Run these commands as root (indicated by ~ #)

System Packages

Ensure that you have ithreads enabled for perl, use perl-cleaner if necessasry. The PostgreSQL server environment for Evergreen depends on a number of Perl modules, so those must be installed as well.

PostgreSQL Server

~ # emerge -av postgresql-server dev-db/libdbi
[ebuild  N    ~] dev-perl/MARC-Record-2.0.3  USE="{-test}"
[ebuild  N    ~] dev-perl/MARC-Charset-1.330.0  USE="{-test}"
[ebuild  N    ~] dev-perl/MARC-XML-0.930.0
[ebuild  N    ~] dev-perl/JSON-XS-2.330.0
[ebuild  N     ] dev-perl/XML-LibXSLT-1.770.0
[ebuild  N     ] dev-python/egenix-mx-base-3.1.3
[ebuild  N     ] dev-libs/ossp-uuid-1.6.2  USE="cxx -php"
[ebuild  N     ] dev-db/postgresql-server-9.0.3  USE="-doc nls perl -pg_legacytimestamp python (-selinux) -tcl uuid xml" LINGUAS="-af -cs -de -es -fa -fr -hr -hu -it -ko -nb -pl -pt_BR -ro -ru -sk -sl -sv -tr -zh_CN -zh_TW"
[ebuild  N     ] dev-db/libdbi-0.8.3  USE="-doc"
[ebuild  N     ] dev-db/libdbi-drivers-0.8.3  USE="-bindist -doc (-firebird) -mysql -oci8 postgres -sqlite -sqlite3"
g-cpan --install \
    Business::ISBN \
    Library::CallNumber::LC \

After installing, edit the config file to set PG_INITDB_OPTS as follows:


Then, execute emerge --config to configure the PostgreSQL cluster.

~ # emerge --config =dev-db/postgresql-server-9.0.3
eselect rc add postgresql-9.0 default

Apache, Memcache, eJabberd & Perl Modules

OpenSRF needs the following: eJabberd, rpmforge? autoconf-2.65, libtool-2.2.6b, automake-1.11, libmemcached, libxslt-1.1.22, libxml2-2.6.30, apache-prefork, psmisc, On Praxis/Gentoo system the autoconf, libtool, automake, libxml2 and libxslt2 should already be installed. See how-to on installing ejabberd.

~ # emerge -av \
    dev-libs/libmemcached \
    dev-libs/yaz \
    net-im/ejabberd \
    net-misc/memcached \
    sys-process/psmisc  \
    www-apache/mod_perl \

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild  N    ] dev-libs/libevent-2.0.10  USE="-static-libs -test"
[ebuild   R   ] sys-process/psmisc-22.12  USE="-X ipv6 nls (-selinux)"
[ebuild  N    ] net-misc/memcached-1.4.5  USE="-debug -sasl -slabs-reassign -test"
[ebuild  N    ] virtual/perl-PodParser-1.380.0-r1
[ebuild   R   ] www-servers/apache-2.2.17  USE="-debug -doc -ldap (-selinux) ssl -static -suexec -threads" APACHE2_MODULES="actions alias -asis auth_basic auth_digest authn_alias authn_anon -authn_dbd authn_dbm authn_default authn_file authz_dbm authz_default authz_groupfile authz_host authz_owner authz_user autoindex cache -cern_meta cgi cgid -charset_lite dav dav_fs dav_lock -dbd deflate dir disk_cache -dumpio env expires ext_filter file_cache filter headers -ident -imagemap include info log_config -log_forensic logio mem_cache mime mime_magic negotiation -proxy -proxy_ajp -proxy_balancer -proxy_connect -proxy_ftp -proxy_http -proxy_scgi -reqtimeout rewrite setenvif speling status -substitute unique_id userdir usertrack -version vhost_alias" APACHE2_MPMS="-event -itk -peruser -prefork -worker"
[ebuild  N    ] dev-libs/libmemcached-0.39  USE="-debug -hsieh"
[ebuild  N    ] net-im/jabber-base-0.01
[ebuild  N    ] dev-lang/erlang-13.2.4  USE="-doc -emacs -hipe -java -kpoll -odbc -sctp smp ssl -tk -wxwidgets"
[ebuild  N    ] net-im/ejabberd-2.1.6  USE="-captcha -debug -ldap mod_irc mod_muc -mod_proxy65 mod_pubsub -mod_statsdx -odbc pam ssl web zlib"
[ebuild  N    ] dev-lang/tcl-8.5.9  USE="-debug -threads"
[ebuild  N    ] dev-libs/yaz-3.0.50  USE="-debug icu -tcpd ziffy"
[ebuild  N    ] dev-libx/libxml2- USE="static-libs"

These addons are specifically for Perl, you may want to use CPAN, depends on your environment.

~ # echo "dev-perl/common-sense ~amd64" >> /etc/portage/package.keywords
~ # echo "dev-perl/DateTime-Format-Builder" >> /etc/portage/package.keywords
~ # echo "dev-perl/DateTime-Format-ISO8601 ~amd64" >> /etc/portage/package.keywords
~ # echo "dev-perl/DateTime-Format-Strptime ~amd64" >> /etc/portage/package.keywords
~ # echo "dev-perl/JSON-XS ~amd64" >> /etc/portage/package.keywords

~ # emerge -av dev-perl/Cache-Memcached dev-perl/DBD-Pg dev-perl/DateTime \
  dev-perl/DateTime-Format-ISO8601 dev-perl/FreezeThaw dev-perl/JSON-XS \
  dev-perl/net-server dev-perl/UNIVERSAL-require dev-perl/Unix-Syslog \
  XML-LibXML XML-Parser

[ebuild  N    ] dev-perl/XML-NamespaceSupport-1.11
[ebuild  N    ] dev-perl/IO-Multiplex-1.09
[ebuild  N    ] dev-perl/common-sense-3.400
[ebuild  N    ] dev-perl/Class-Singleton-1.4
[ebuild  N    ] dev-perl/List-MoreUtils-0.21
[ebuild  N    ] dev-perl/string-crc32-1.4
[ebuild  N    ] perl-core/Time-Local-1.19.01
[ebuild  N    ] perl-core/Attribute-Handlers-0.88
[ebuild  N    ] virtual/perl-ExtUtils-MakeMaker-6.56
[ebuild  N    ] dev-perl/FreezeThaw-0.500.100
[ebuild  N    ] dev-perl/UNIVERSAL-require-0.13
[ebuild  N    ] dev-perl/Unix-Syslog-0.100-r1
[ebuild  N    ] dev-perl/XML-SAX-0.16
[ebuild  N    ] dev-perl/Class-Factory-Util-1.7
[ebuild  N    ] virtual/perl-Time-Local-1.19.01
[ebuild  N    ] virtual/perl-Attribute-Handlers-0.88
[ebuild  N    ] dev-perl/Cache-Memcached-1.24
[ebuild  N    ] dev-perl/DBD-Pg-2.17.2
[ebuild  N    ] dev-perl/JSON-XS-2.3  USE="-test"
[ebuild  N    ] dev-perl/net-server-0.97
[ebuild  N    ] dev-perl/Params-Validate-0.95
[ebuild  N    ] dev-perl/XML-LibXML-1.70
[ebuild  N    ] dev-perl/XML-Parser-2.36-r1
[ebuild  N    ] dev-perl/DateTime-Locale-0.45
[ebuild  N    ] dev-perl/DateTime-TimeZone-1.22  USE="-test"
[ebuild  N    ] dev-perl/DateTime-0.55  USE="-test"
[ebuild  N    ] dev-perl/DateTime-Format-Strptime-1.500.0
[ebuild  N    ] dev-perl/DateTime-Format-Builder-0.80  USE="-test"
[ebuild  N    ] dev-perl/DateTime-Format-ISO8601-0.07  USE="-test"

Configure services to start on boot.

~ # eselect rc add memcached default
~ # eselect rc add ejabberd default
~ # eselect rc add apache2 default

Configuring Memcached

The defaults will mostly work out of the box, configure in /etc/conf.d/memcached.


Configure memcached to start on boot

~ # rc-config add memcached default

Configuring eJabberd

Update /etc/jabber/ejabberd.cfg with at least the following:

{hosts, ["localhost", "private.localhost", "public.localhost"]}.
{access, max_user_sessions, [{10000, all}]}.
{acl, admin, {user,"ejabberd","localhost"}}.

Add the OpenSRF users, be careful to not use exotic characters in the Jabber password, they are not handled well by all the scripts/tools.

ejabberdctl register router private.localhost [password]
ejabberdctl register opensrf private.localhost [password]
ejabberdctl register router public.localhost [password]
ejabberdctl register opensrf public.localhost [password]

Installing Evergreen ILS / Open ILS

Download and extract as opensrf user, then configure and make. Install as root.

~ # cd /usr/src
. # wget http://open-ils.org/downloads/Evergreen-ILS-2.1.0a.tar.gz
. # tar -zxf Evergreen-ILS-2.0.6.tar.gz
. # chown -R opensrf:opensrf Evergreen-ILS-2.0.6
. $ su opensrf
. $ cd ./Evergreen-ILS-2.0.6
. $ ./autogen.sh
. $ ./configure \
    --prefix=/openils \
    --with-apache \
    --with-apr=/usr/include/apr-1.0 \
    --with-apxs=/usr/sbin/apxs2 \
    --with-libxml2=/usr/include/libxml2 \
    --with-opensrf-headers=/openils/include \
. $ make
. $ exit
. # make install

Note that if you use the --enable-python option your DNS will have to work properly or you may see some name resolution falures from the Python libs. Unsure if you need the python? You don't.

Building Staff Client Stuff §

On Gentoo making the Staff Client is

echo "=dev-perl/CQL-Parser-1.100.0 ~amd64" >> /etc/portage/package.keywords
echo "=dev-perl/DateTime-Set-0.310.0 ~amd64" >> /etc/portage/package.keywords
echo "=dev-perl/Net-Z3950-ZOOM-1.280.0 ~amd64" >> /etc/portage/package.keywords
echo "=dev-perl/MARC-Charset-1.330.0 ~amd64" >> /etc/portage/package.keywords
echo "=dev-perl/MARC-Record-2.0.3 ~amd64" >> /etc/portage/package.keywords
echo "=dev-perl/MARC-XML-0.930.0 ~amd64" >> /etc/portage/package.keywords
echo "=dev-perl/SQL-Abstract-Limit-0.141.0 ~amd64" >> /etc/portage/package.keywords
echo "=dev-perl/SRU-0.990.0 ~amd64" >> /etc/portage/package.keywords
echo "=dev-perl/String-Tokenizer-0.50.0 ~amd64" >> /etc/portage/package.keywords
echo "=dev-perl/Set-Infinite-0.650.0 ~amd64" >> /etc/portage/package.keywords
echo "dev-perl/JavaScript-SpiderMonkey ~amd64" >> /etc/portage/package.keywords
echo "=dev-perl/XML-Simple-2.200.0 ~amd64" >> /etc/portage/package.keywords
emerge -av \
    dev-libs/yaz \
    dev-perl/JavaScript-SpiderMonkey \
    dev-perl/Class-DBI-AbstractSearch \
    dev-perl/DateTime-Format-Mail \
    dev-perl/DateTime-Set \
    dev-perl/Email-Send \
    dev-perl/GD-Graph3d \
    dev-perl/MARC-Record \
    dev-perl/MARC-XML \
    dev-perl/RPC-XML \
    dev-perl/Spreadsheet-WriteExcel \
    dev-perl/SRU \
    dev-perl/Text-Aspell \
    dev-perl/Text-CSV \
    dev-perl/Text-CSV_XS \
    dev-perl/Text-Glob \
    dev-perl/Tie-IxHash \
    dev-perl/XML-LibXSLT \
    dev-perl/XML-Simple \
    dev-perl/libwww-perl \
g-cpan --install \
    APR::Const APR::Table \
    Business::CreditCard \
    Business::CreditCard::Object \
    Business::ISBN \
    Business::OnlinePayment \
    Library::CallNumber::LC \
    Net::SSH2 \
    Net::HTTPS::Any \
    Net::Z3950::Simple2ZOOM \
    Template::Plugin \
    Template::Plugin::POSIX \

cd /usr/src/Evergreen-ILS-2.1.0a
su opensrf
$ make STAFF_CLIENT_STAMP_ID=rel_2_1_0 install

$ cd Open-ILS/xul/staff_client/
$ make win-client

Configuring Evergreen ILS §

# cd /opt/openils/etc
# mv oils_web.xml.example oils_web.xml
# mv opensrf.xml.example opensrf.xml
# cd /usr/src/Evergreen-ILS-2.1.0a
# cp Open-ILS/examples/apache/eg.conf /etc/apache2/vhosts.d
# cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/
# cp Open-ILS/examples/apache/startup.pl /etc/apache2/

May need to edit some lines in the httpd.conf file that are updated by the previous installers. Generally the Evergreen application is the only web-application running in this environment.

May need to adjust the settings in /etc/conf.d/apache2 APACHE2_OPTS="-D SSL -D PERL"

Running Evergreen ILS Services §

The "server" part of Evergreen is actually multiple components, the XMPP services, memcache, database and web-services. Start them all, and configure to run at default.

NB: a production Evergreen environment generally has these services on different physical hardware.

/etc/init.d/ejabberd restart
/etc/init.d/postgresql-9.0 restart

Initialise §

We use evergreen-su for the database super user and evergreen-aa for the application administrator.

# su postgres
$ createuser --pwprompt --superuser evergreen-su
$ exit
# cd /usr/src/Evergreen-ILS-2.1.0a
# perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
       --service all --create-database --create-schema --create-offline \
       --user evergreen-su --password evergreen-su --hostname localhost --port 5432 \
       --database openils --admin-user evergreen-aa --admin-pass evergreen-aa

Watch this script for errors! There will be many lines of output, some notices (CONTEXT:).

Loading Sample Data

Evergreen comes with a set of sample data called concerto, it can be loaded like this.

psql -U evergreen -h hostname -f Open-ILS/tests/datasets/concerto.sql
psql -U evergreen -h hostname -f Open-ILS/tests/datasets/users_patrons_100.sql
psql -U evergreen -h hostname -f Open-ILS/tests/datasets/users_staff_134.sql

Many scripts won't have the paths properly set. Will need to check/update paths in etc/oils_web.xml, bin/action_trigger_runner.pl, bin/offline-blocked-list.pl, site_perl/OpenILS/Cronscript.pm, eg_vhost.conf, eg.conf, startup.pl

Start the OpenSRF system (ensure that PATH includes /opt/open-ils/bin), run autogen.sh the first time.

# su - opensrf
$ cat .bashrc
$ /opt/open-ils/bin/osrf_ctl.sh -l -a start_all
$ autogen.sh -u
$ exit
# /etc/init.d/apache2 restart

Testing the Configuration §

This script will look for things in /openils, many scripts do.

# su - opensrf
# /usr/src/Evergreen-ILS-2.1.0a/Open-ILS/src/support-scripts/settings-tester.pl

See Also

Loading Comments from Disqus...