====== This page has been deprecated. ======
Please install a more recent supported version of Evergreen using the instructions referenced on this page:
http://evergreen-ils.org/downloads/
----
======Installing Evergreen 2.0 on Debian Squeeze / Ubuntu Lucid======
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 or ''sudo -i'' command. To switch from the **root** user to a different user, issue the ''su - '' command; for example, ''su - opensrf''. Once you have become a non-root user, to become the **root** user again simply issue the ''exit'' command.
- [[zzz_archive:opensrf:2.0:install|Install the latest version of OpenSRF 2.0.x]]. Follow the steps and run the test to ensure that OpenSRF is properly installed before continuing with any further Evergreen installation steps. Evergreen is an application that has been built on top of the Open Service Request Framework (OpenSRF), so if OpenSRF doesn't work, Evergreen isn't going to work.
- Download and build Evergreen:
- As the **opensrf** user, download and extract the latest version of Evergreen (http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.12.tar.gz):
wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.12.tar.gz
tar xzf Evergreen-ILS-2.0.12.tar.gz
- **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. On Debian you can install the required PostgreSQL server packages using '''Makefile.install''' as the **root** user:
# Debian Squeeze (6.0) and Ubuntu Lucid (10.04)
make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_84
You also need to install several Perl modules on your PostgreSQL server to support some functions. If PostgreSQL is running on the same server as the rest of Evergreen, these prerequisites will automatically be available to PostgreSQL. For a standalone PostgreSQL server, you must ensure that the following Perl modules are installed as the **root** user:
aptitude install gcc libxml-libxml-perl libxml-libxslt-perl
cpan Business::ISBN
cpan JSON::XS
cpan Library::CallNumber::LC
cpan MARC::Record
cpan MARC::File::XML
cpan UUID::Tiny
* **Note**: **//PostgreSQL 8.4//** is the minimum supported version.
- As the **root** user, install the prerequisites. Replace below with one of these values for your actual distribution:
* ''debian-squeeze'' for Debian Squeeze (6.0)
* ''ubuntu-lucid'' for Ubuntu Lucid (10.04)
cd /home/opensrf/Evergreen-ILS-2.0.12
make -f Open-ILS/src/extras/Makefile.install
- 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 where ''plperl.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.4 restart (replace 8.4 with correct Postgresql version)
- As the **opensrf** user, configure and compile Evergreen:
cd /home/opensrf/Evergreen-ILS-2.0.12
./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. Create a symbolic link named ''server'' in ''/openils/var/web/xul/'' to the ''/server/'' subdirectory of your staff client build.
cd /home/opensrf/Evergreen-ILS-2.0.12
make STAFF_CLIENT_BUILD_ID=rel_2_0_12 install
cd /openils/var/web/xul
ln -sf rel_2_0_12/server server
- As the **root** user, 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:
cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml
cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.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.4** server packages on Debian Squeeze, the contrib directory will be at ''/usr/share/postgresql/8.4/contrib/''.
createdb -T template0 --lc-ctype=C --lc-collate=C -E UNICODE evergreen
createlang plperl evergreen
createlang plperlu evergreen
createlang plpgsql evergreen
psql -f /usr/share/postgresql/8.4/contrib/tablefunc.sql evergreen
psql -f /usr/share/postgresql/8.4/contrib/tsearch2.sql evergreen
psql -f /usr/share/postgresql/8.4/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
- Enter the password for the new PostgreSQL superuser ("evergreen")
- As the **opensrf** 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, //// will be ''localhost'' and //// will be ''5432''. The //// and //// will specify the **Evergreen administrator account's** username and password. This was changed for security reasons, it was previously admin/open-ils.
cd /home/opensrf/Evergreen-ILS-2.0.12
perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
--service all --create-schema --create-offline \
--user --password --hostname --port \
--database --admin-user --admin-pass
**NOTE**: If you are entering this command on a single line, do not include the ''\'' characters. These should only be used at the end of a line at a bash prompt to indicate that the command is continued on the next line.
- As the **root** user, set up Apache:
cd /home/opensrf/Evergreen-ILS-2.0.12
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 add ''Allow from all'' (to enable access to the offline upload / execute interface from any workstation on any network - note that you must secure this for a production instance)
- Comment the line ''Listen 443'' as it conflicts with the same declaration in ''/etc/apache2/ports.conf''.
- 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:
- As the **root** user, edit ''/etc/apache2/envvars'':
- Change ''export APACHE_RUN_USER=www-data'' to ''export APACHE_RUN_USER=opensrf''
- As the **root** user, edit ''/etc/apache2/apache2.conf'':
- Change ''KeepAliveTimeout'' to ''1''
- OPTIONAL: As the **root** user, edit ''/etc/apache2/apache2.conf'':
- Change ''MaxKeepAliveRequests'' to ''100''
- Update the prefork configuration section to suit your environment. The following settings apply to a busy system:
StartServers 20
MinSpareServers 5
MaxSpareServers 15
MaxClients 150
MaxRequestsPerChild 10000
- 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 (line 53*)
* ''/config/gateway/username'' = opensrf
* ''/config/gateway/passwd'' = password for **public.localhost** opensrf user (line 97*)
* ''/config/routers/router/transport'' - first entry, where ''transport/server'' == **public.localhost** :
* ''username'' = router
* ''password'' = password for **public.localhost** router user (line 131*)
* ''/config/routers/router/transport'' - second entry, where ''transport/server'' == **private.localhost** :
* ''username'' = router
* ''password'' = password for **private.localhost** router user (line 156*)
* (* Note that these line numbers may differ in the future as changes are made to the ''opensrf_core.xml'' file.)
- 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.
- As the **opensrf** user, add an environmental variable to opensrf's ''.bashrc'' file:
echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
. ~/.bashrc # inherit the new environment
* 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.
=====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. The '''-l''' flag in the following command is only necessary if you want to force Evergreen to treat the hostname as '''localhost'''; if you have configured ''opensrf.xml'' using the real hostname of your machine as returned by ''perl -ENet::Domain 'print Net::Domain::hostfqdn() . "\n";''', you should not use the '''-l''' flag.
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 the opensrf user's ''.bashrc'' configuration file. To manually set the **PATH** variable, edit the configuration file ''~/.bashrc'' as the opensrf user and add the following line: 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 the opensrf user's ''.bashrc'' configuration file. To manually set the **PERL5LIB** variable, based on step 13 above, edit the configuration file ''~/.bashrc'' as the opensrf user and add the following line: export PERL5LIB=$PERL5LIB:/openils/lib/perl5
* If you fixed one of the above errors, then as the **opensrf** user, attempt to start Evergreen again.
osrf_ctl.sh -l -a start_all
- 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 the first time you start Evergreen, and after that each time you change the library hierarchy in ''config.cgi''):cd /openils/bin
./autogen.sh -c /openils/conf/opensrf_core.xml -u
- As the **root** user, restart the Apache Web server:/etc/init.d/apache2 restart If the Apache Web server was running when you started the OpenSRF services, you might not be able to successfully log in to the OPAC or staff client until the Apache Web server is restarted.
=====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 administrator username and password [**Set in step 4 of the installation instructions**]:
/openils/bin/srfsh
srfsh% login 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 at ''Open-ILS/src/support-scripts/settings-tester.pl'' in the Evergreen source tree. If the output of ''settings-tester.pl'' does not help you find the problem, please do not make any significant changes to your configuration.
* Follow the steps in the troubleshooting guide [[troubleshooting:checking_for_errors|"checking for errors"]].
* 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 [[http://open-ils.org/listserv.php|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 using a XULRunner 1.9; this is installed by default with Firefox version 3.0 and later on Debian and Ubuntu distributions.
- Start up the staff client by passing the full path to the ''application.ini'' file for the source files of the local build of the Evergreen staff client. For example, if the source files for your Evergreen installation are in the ''/home/opensrf/Evergreen-ILS-2.0.12/'' directory, you would issue the following command:xulrunner /home/opensrf/Evergreen-ILS-2.0.12/Open-ILS/xul/staff_client/build/application.ini
* Note this is on the Linux machine where Evergreen was compiled and installed.
* To run the client on a Linux desktop machine you can grab the /Evergreen-ILS-2.0.12/Open-ILS/xul/staff_client/build directory to your local system say ~/Evergreen and issue the following command:xulrunner ~/Evergreen/Open-ILS/xul/staff_client/build/application.ini
=====Starting the Web server=====
Once you've started Evergreen, confirmed that a basic login attempt works but had to restart Evergreen processes you should restart 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.
====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