Table of Contents
Installing Evergreen 1.4.0.6 on Ubuntu or Debian
The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit) architectures. There may be differences between the Desktop and Server editions of Ubuntu. These instructions assume the Server edition.
If you are starting with a clean install of Ubuntu or Debian, you are strongly recommended not to install the packaged PostgreSQL server. This can confuse port numbers and system configuration. Evergreen 1.4 requires PostgreSQL 8.2.
- Note: As the PostgreSQL server is usually a standalone server in multi-server production systems, the prerequisite installer Makefile does not install the PostgreSQL server by default. You must install the PostgreSQL server yourself prior to running the prerequisite installer Makefile (Makefile.install); either on the same system as Evergreen itself, or on another system on the network.
- Note: Only PostgreSQL 8.2 is officially supported for new installations of Evergreen 1.4; PostgreSQL 8.1 is deprecated, though existing installations upgrading from Evergreen 1.2 or before will work fine, and PostgreSQL 8.3+ is not yet supported. As Debian Etch does not provide packages for PostgreSQL 8.2, we offer a cheat sheet for installing it from source.
In the following instructions, you are asked to perform certain steps as either the root user, the opensrf user, or the postgres user. To become the root user, issue the sudo su -
command. To switch from the root user to a different user, issue the su - <username>
command; for example, su - opensrf
. Once you have become a non-root user, to become the root user again simply issue the exit
command.
- Evergreen is an application that has been built on top of the Open Service Request Framework (OpenSRF). Start by installing OpenSRF 1.0.7. Follow the steps and run the test to ensure that OpenSRF is properly installed before continuing with any further Evergreen installation steps.
- Download and build Evergreen:
- As the opensrf user, download and extract the latest version of Evergreen (http://evergreen-ils.org/downloads/Evergreen-ILS-1.4.0.6.tar.gz):
wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.4.0.6.tar.gz tar xzf Evergreen-ILS-1.4.0.6.tar.gz
- As the root user, install the prerequisites. Replace <distribution> below with one of these values for your actual distribution:
debian-etch
for Debian Etch (4.0)debian-lenny
for Debian Lennyubuntu-hardy
for Ubuntu Hardy Heron (8.04)ubuntu-intrepid
for Ubuntu Intrepid Ibex (8.10)cd /home/opensrf/Evergreen-ILS-1.4.0.6 make -f Open-ILS/src/extras/Makefile.install <distribution>
- As the root user, add
/usr/local/lib
and/usr/local/lib/dbd
to the system dynamic library path and make Ubuntu recognize the newly installed libraries. Then restart PostgreSQL to avoid a problem whereplperl.so
cannot be found:- Create a file named
/etc/ld.so.conf.d/eg.conf
containing the following lines:/usr/local/lib /usr/local/lib/dbd
- Run the following commands:
ldconfig /etc/init.d/postgresql-8.2 restart
- As the opensrf user, configure and compile Evergreen:
cd /home/opensrf/Evergreen-ILS-1.4.0.6 ./configure --prefix=/openils --sysconfdir=/openils/conf make
- As the root user, install the code. Set the
STAFF_CLIENT_BUILD_ID
variable to match the version of the staff client you will use to connect to the Evergreen server. Copy the example OpenSRF configuration files into place. This will replace the OpenSRF configuration files that you set up while installing and testing OpenSRF; you might want to backup the old files for troubleshooting purposes. Finally, change the ownership on the installed files to the opensrf user:cd /home/opensrf/Evergreen-ILS-1.4.0.6 make STAFF_CLIENT_BUILD_ID=rel_1_4_0_6 install cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml chown -R opensrf:opensrf /openils/
- As the postgres user on your PostgreSQL server, create the Evergreen database.
- Issue the following commands on your PostgreSQL server, adjusting the path for the contrib repository to match your PostgreSQL server layout. For example, if you built PostgreSQL from source following the cheat sheet, the contrib directory will be located at
/usr/local/share/contrib
; if you installed the PostgreSQL 8.2 packages on Ubuntu 8.04, the contrib directory will be at/usr/share/postgresql/8.2/contrib/
.createdb -E UNICODE evergreen createlang plperl evergreen createlang plperlu evergreen createlang plpgsql evergreen psql -f /usr/local/share/contrib/tablefunc.sql evergreen psql -f /usr/local/share/contrib/tsearch2.sql evergreen psql -f /usr/local/share/contrib/pgxml.sql evergreen
- As the postgres user on the PostgreSQL server, create a PostgreSQL user named
evergreen
for the database cluster:createuser -P -s evergreen exit
- Enter the password for the new PostgreSQL superuser ("evergreen")
- As the root user, create the database schema and configure your system with the corresponding database authentication details for the database user that you just created; on most systems, <hostname> will be
localhost
and <port> will be5432
:cd /home/opensrf/Evergreen-ILS-1.4.0.6 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ --service all --create-schema --create-bootstrap --create-offline \ --user <user> --password <password> --hostname <hostname> --port <port> \ --database <dbname>
- As the root user, set up Apache:
a2enmod ssl # enable mod_ssl a2enmod rewrite # enable mod_rewrite a2enmod expires # enable mod_expires cd /home/opensrf/Evergreen-ILS-1.4.0.6 cp Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/ cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/ cp Open-ILS/examples/apache/startup.pl /etc/apache2/ # Now setting up SSL mkdir /etc/apache2/ssl cd /etc/apache2/ssl # Step 7 openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key # Step 8 vi /etc/apache2/sites-available/eg.conf
- The openssl command cuts a new SSL key for your Apache server. For a production server, you should purchase a signed SSL certificate, but we can just use a self-signed certificate and accept the warnings in the staff client and browser during testing and development:
- The last code line opens
/etc/apache2/sites-available/eg.conf
for editing:- Comment out
Allow from 10.0.0.0/8
and addAllow from all
(to enable access to the configuration CGI scripts from any workstation on any network - note that you must secure this for a production instance, preferably by locking down the allowed IP addresses and adding authentication, because you don't want just anyone adding and deleting libraries from your Evergreen instance!) - Delete the line
Listen 443
as it conflicts with the same declaration in/etc/apache2/ports.conf
. Debian etch users - do not do this!
- This step is still necessary to keep the logs functioning, but may break other Apache applications on your server. We hope to make this unnecessary soon. Change the user for the Apache server:
- Ubuntu Hardy/Debian Etch: As the root user, edit
/etc/apache2/apache2.conf
:- Change
User www-data
toUser opensrf
- Ubuntu Intrepid/Debian Lenny: As the root user, edit
/etc/apache2/envvars
:- Change
export APACHE_RUN_USER=www-data
toexport APACHE_RUN_USER=opensrf
- OPTIONAL: As the root user, edit
/etc/apache2/apache2.conf
:- Change
KeepAliveTimeout
to1
- Change
MaxKeepAliveRequests
to100
- Update the prefork configuration section to suit your environment. The following settings apply to a busy system:
<IfModule mpm_prefork_module> StartServers 20 MinSpareServers 5 MaxSpareServers 15 MaxClients 150 MaxRequestsPerChild 1000 </IfModule>
- Still as the root user, enable the Evergreen site:
a2dissite default # OPTIONAL: disable the default site (i.e., the "It Works" page). a2ensite eg.conf
- As the opensrf user, edit
/openils/conf/opensrf_core.xml
:- Edit
/openils/conf/opensrf_core.xml
to change the Jabber usernames and passwords as follows. I'm using XPath syntax on the left-hand side to indicate the position in the XML file:/config/opensrf/username
= opensrf/config/opensrf/passwd
= password for private.localhost opensrf user/config/gateway/username
= opensrf/config/gateway/passwd
= password for public.localhost opensrf user/config/routers/router/transport
- first entry, wheretransport/server
== public.localhost :username
= routerpassword
= password for public.localhost router user
/config/routers/router/transport
- second entry, wheretransport/server
== private.localhost :username
= routerpassword
= password for private.localhost router user
- We also need to specify the domains from which we'll accept and to which we'll make connections. If you are installing Evergreen on a single server and using the "private.localhost" / "public.localhost" domains, these will already be set to the correct values. Otherwise, search and replace to match your customized values.
- Copy
/openils/conf/srfsh.xml.example
to.srfsh.xml
in the home directory of each user you want to use to run the srfsh command line client for testing OpenSRF, and edit.srfsh.xml
as follows:domain
is the router hostname (following our domain examples,private.localhost
will give your srfsh access to all OpenSRF services, whilepublic.localhost
will only give you access to those OpenSRF services that are publicly exposed)username
andpassword
must match youropensrf
ejabber user for the chosen domainlogfile
is the full path for a log file to which that user has write access<?xml version="1.0"?> <!-- This file follows the standard bootstrap config file layout found in opensrf_core.xml --> <srfsh> <router_name>router</router_name> <domain>private.localhost</domain> <username>opensrf</username> <passwd>evergreen</passwd> <port>5222</port> <logfile>/tmp/srfsh.log</logfile> <loglevel>4</loglevel> </srfsh>
- As the opensrf user, make the cgi-bins executable, and add an environmental variable to opensrf's
.bashrc
file:chmod 755 /openils/var/cgi-bin/*.cgi echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc exit
- Note: in a multi-server (brick) environment, put the ~/.bashrc modifications at the top of the file, before
[ -z "$PS1" ] && return
This will allow headless (scripted) logins to load the correct environment.
- (Optional): Load translations such as Armenian (hy-AM), Canadian French (fr-CA), and others into the database to complete the translations available in the OPAC and staff client. See these instructions for details.
Starting Evergreen
- As the root user, start the memcached and ejabberd services (if they aren't already running):
/etc/init.d/ejabberd start /etc/init.d/memcached start
- As the opensrf user, start Evergreen:
osrf_ctl.sh -l -a start_all
- If you receive the error message bash: osrf_ctl.sh: command not found, then your environment variable PATH does not include the
/openils/bin
directory; this should have been set by.bashrc
when you logged in as theopensrf
user, based on step 19 above, but you can manually set it using the following command:export PATH=$PATH:/openils/bin
- If you receive the error message Can't locate OpenSRF/System.pm in @INC … BEGIN failed–compilation aborted, then your environment variable PERL5LIB does not include the
/openils/lib/perl5
directory; this should have been set by.bashrc
when you logged in as theopensrf
user, based on step 19 above, but you can manually set it using the following command:export PERL5LIB=$PERL5LIB:/openils/lib/perl5
- As the opensrf user, generate the Web files needed by the staff client and catalogue and update the organization unit proximity (you need to do this each time you change the library hierarchy in config.cgi):
cd /openils/bin ./autogen.sh -c /openils/conf/opensrf_core.xml -u
Testing connections to Evergreen
Once you have installed and started Evergreen, test your connection to Evergreen via srfsh
:
- Start
srfsh
and try logging onto the Evergreen server using the default administrator user ID and password:/openils/bin/srfsh srfsh% login admin open-ils
You should see a result like:
Received Data: "250bf1518c7527a03249858687714376" ------------------------------------ Request Completed Successfully Request Time in seconds: 0.045286 ------------------------------------ Received Data: { "ilsevent":0, "textcode":"SUCCESS", "desc":" ", "pid":21616, "stacktrace":"oils_auth.c:304", "payload":{ "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a", "authtime":420 } } ------------------------------------ Request Completed Successfully Request Time in seconds: 1.336568 ------------------------------------
If this does not work, it's time to do some troubleshooting. As the opensrf user, run the
settings-tester.pl
script to see if it finds any system configuration problems. The script is found atOpen-ILS/src/support-scripts/settings-tester.pl
in the Evergreen source tree. If the output ofsettings-tester.pl
does not help you find the problem, please do not make any significant changes to your configuration. If you have followed the entire set of installation steps listed here closely, you are probably extremely close to a working system. Gather your configuration files and log files and contact the Evergreen development mailing list for assistance before making any drastic changes to your system configuration.
Running the staff client on Linux
You can run the staff client on Linux, but you are advised to download a XULRunner 1.8.1.3 build from the Mozilla project directly; there are known incompatibilities with XULRunner packages on most distributions.
- Ensure that you have the rather outdated, but required by XULRunner 1.8,
libstdc++.so.5
library installed on your Linux desktop machine by running the following command as root:aptitude install libstdc++5
- Download and unpack the Mozilla project XULRunner package:
wget http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases/1.8.1.3/contrib/linux-i686/xulrunner-1.8.1.3.en-US.linux-i686.tar.gz tar xzf xulrunner-1.8.1.3.en-US.linux-i686.tar.gz
- Start up the staff client by passing the full path to both your locally unpacked XULRunner package and the
application.ini
file for the source files of the local build of the Evergreen staff client. For example, if you extracted the XULRunner package in the/home/evergreen/
directory, and the source files for your Evergreen installation are in the/home/opensrf/Evergreen-ILS-1.4.0.6/
directory, you would issue the following command:/home/evergreen/xulrunner/xulrunner /home/opensrf/Evergreen-ILS-1.4.0.6/Open-ILS/xul/staff_client/build/application.ini
Note: ensure that you pass the full path to the location of your locally unpacked XULRunner package.
Starting the Web server
Once you've started Evergreen and confirmed that a basic login attempt works, you can start up the Web server:
- As the root user, test and start Apache. The restart command will ensure that it loads the new Evergreen modules even if Apache is already running:
apache2ctl configtest && /etc/init.d/apache2 restart
If there are any problems with your configuration file(s), they will be displayed.
Stopping Evergreen
- As the opensrf user, stop Evergreen:
osrf_ctl.sh -l -a stop_all
Setting up support for reports
Evergreen reports are extremely powerful, but some configuration is required.
- As the opensrf user, create a symbolic link named
server
in/openils/var/web/xul/
to the/server/
subdirectory of your staff client build. For example:cd /openils/var/web/xul ln -sf rel_1_4_0_6/server server
- If the Evergreen services were already running when you configured the reporter, you will have to restart the Perl services and Apache:
- As the opensrf user:
osrf_ctl.sh -l -a restart_perl
- As the root user:
/etc/init.d/apache2 stop /etc/init.d/apache2 start
Starting the reporter daemon
Once the open-ils.reporter
process is running and enabled on the gateway, you have to start the reporter daemon. The reporter daemon periodically checks for requests for new reports or scheduled reports and gets them running.
To start the reporter daemon, run the following command as the opensrf user:
clark-kent.pl --daemon
You can also specify other options:
- sleep=interval : number of seconds to sleep between checks for new reports to run; defaults to 10
- lockfile=filename : where to place the lockfile for the process; defaults to
/tmp/reporter-LOCK
- concurrency=integer : number of reporter daemon processes to run; defaults to 1
- boostrap=filename : OpenSRF bootstrap configuration file; defaults to
/openils/conf/opensrf_core.xml
Stopping the reporter daemon
To stop the reporter daemon, you have to kill the process and remove the lockfile. Assuming you're running just a single process and that the lockfile is in the default location, perform the following commands as the opensrf user:
kill `ps wax | grep "Clark Kent" | grep -v grep | cut -b1-6` rm /tmp/reporter-LOCK