Please install a more recent supported version of Evergreen using the instructions referenced on this page: http://evergreen-ils.org/downloads/

The following steps have been tested on the x86 (32-bit) and x86_64 (64-bit) architecture of a Fedora 14 image as of 2011-01-27.

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.

1. Install the latest version of OpenSRF 1.6.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.
2. Download and build Evergreen:
   1. As the opensrf user, download and extract the latest version of Evergreen (http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.0.tar.gz):

      wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.0.tar.gz
      tar xzf Evergreen-ILS-2.0.0.tar.gz

   2. As the root user, install the prerequisites. Replace <distribution> below with one of these values for your actual distribution:
      • fedora13 for Fedora 13
      • fedora14 for Fedora 14

        cd /home/opensrf/Evergreen-ILS-2.0.0
        make -f Open-ILS/src/extras/Makefile.install <distribution>

   3. 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:

      # Fedora 13 or 14
      make -f Open-ILS/src/extras/Makefile.install install_fedora_13_pgsql_server

      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:

      yum install gcc
      cpan JSON::XS
      cpan MARC::Record
      cpan MARC::File::XML

      • Note: PostgreSQL 8.4 is the minimum supported version.
   4. As the opensrf user, configure and compile Evergreen:

      cd /home/opensrf/Evergreen-ILS-2.0.0
      ./configure --prefix=/openils --sysconfdir=/openils/conf
      make

   5. 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.0
      make STAFF_CLIENT_BUILD_ID=rel_2_0_0 install
      cd /openils/var/web/xul
      ln -sf rel_2_0_0/server server

   6. 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/

3. As the root user on your PostgreSQL server, initialize the PostgreSQL cluster, then start the PostgreSQL service:

   service initdb postgresql
   /etc/init.d/postgresql start

4. As the postgres user on your PostgreSQL server, create the Evergreen database.
   1. Issue the following commands on your PostgreSQL server, adjusting the path for the contrib repository to match your PostgreSQL server layout.

      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/pgsql/8.4/contrib/tablefunc.sql evergreen
      psql -f /usr/share/pgsql/8.4/contrib/tsearch2.sql  evergreen
      psql -f /usr/share/pgsql/8.4/contrib/pgxml.sql     evergreen

   2. As the postgres user on the PostgreSQL server, create a PostgreSQL user named evergreen for the database cluster:

      createuser -P -s evergreen

   3. Enter the password for the new PostgreSQL superuser ("evergreen")
5. As the root user, enable IPv4 and IPv6 connections to the PostgreSQL server. For a single-server instance, enable password-protected connections from the evergreen user to the evergreen database on localhost by adding the following lines to /var/lib/pgsql/data/pg_hba.conf:

   # IPv4 local connections:
   host    evergreen     evergreen         127.0.0.1/32          md5
   # IPv6 local connections:
   host    evergreen     evergreen         ::1/128               md5

   ; then restart the PostgreSQL server to make that configuration take effect:

   /etc/init.d/postgresql restart

6. 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, <hostname> will be localhost and <port> will be 5432. The <admin-user> and <admin-pass> variables specify the Evergreen administrator account's user name and password, respectively:

   cd /home/opensrf/Evergreen-ILS-2.0.0
   perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
          --service all --create-schema --create-offline \
          --user <user> --password <password> --hostname <hostname> --port <port> \
          --database <dbname> --admin-user <admin-user> --admin-pass <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.

7. As the root user, set up Apache:

   cd /home/opensrf/Evergreen-ILS-2.0.0
   cp Open-ILS/examples/apache/eg.conf       /etc/httpd/conf.d/.
   cp Open-ILS/examples/apache/eg_vhost.conf /etc/httpd/.
   cp Open-ILS/examples/apache/startup.pl    /etc/httpd/.
   # Now setting up SSL
   mkdir /etc/httpd/ssl
   cd /etc/httpd/ssl
   # Step 7
   openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key
   # Step 8
   vi /etc/httpd/conf.d/eg.conf

   1. 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.
   2. The last code line opens /etc/httpd/conf.d/eg.conf for editing:
      1. Change all instances of apache2 to httpd.
      2. Comment out Allow from 10.0.0.0/8 and uncomment 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)
      3. Comment the line Listen 443 as it conflicts with the same declaration in /etc/httpd/conf.d/ssl.conf.
   3. As the root user, edit /etc/conf/httpd.conf:
      1. Change User apache to User opensrf
      2. Change KeepAlive to On
      3. Change KeepAliveTimeout to 1
8. Enable the dbdpgsql.so library to be dynamically loaded by the Evergreen C services. As the root user, create the file /etc/ld.so.conf.d/eg.conf with the following content:

   /usr/lib/dbd
   /usr/lib64/dbd

   ; then run the following command to refresh the dynamic library cache:

   ldconfig

9. As the opensrf user, edit /openils/conf/opensrf_core.xml:
   1. 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, where transport/server == public.localhost :
        • username = router
        • password = password for public.localhost router user
      • /config/routers/router/transport - second entry, where transport/server == private.localhost :
        • username = router
        • password = password for private.localhost router user
   2. 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.
10. 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.

Fedora is a very secure system out of the box, including a very restrictive firewall and an automatically enabled set of SELinux system policies to prevent unauthorized access to system resources. Unfortunately, these secure system policies can interfere with the normal operation of applications like Evergreen.

Until a person with the required SELinux skills can offer a nuanced set of policies appropriate for Evergreen, the simplest way to test and develop against a Fedora server is to completely disable the firewall and SELinux policies.

To disable the Fedora firewall until your next reboot, issue the following command as the root user:

/etc/init.d/iptables stop

To disable the Fedora firewall permanently, issue the following command as the root user:

chkconfig iptables off

. This change will take effect when you reboot your system.

To disable the SELinux policies until your next reboot, issue the following command as the root user:

/usr/sbin/setenforce 0

To disable the SELinux policies permanently, edit /etc/sysconfig/selinux:

SELINUX=permissive

. This change will take effect when you reboot your system.

1. As the root user, start the memcached, ejabberd, and PostgreSQL services (if they aren't already running):

   /etc/init.d/ejabberd start
   /etc/init.d/memcached start
   /etc/init.d/postgresql start

   If you want to have these services run automatically every time you boot your server, issue the following commands as the root user:

   chkconfig --levels 2345 ejabberd on
   chkconfig --levels 2345 memcached on
   chkconfig --levels 2345 postgresql on

2. 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 .bashrc when you logged in as the opensrf 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 the opensrf user, but you can manually set it using the following command:

     export PERL5LIB=$PERL5LIB:/openils/lib/perl5

   • As the opensrf user, attempt to start Evergreen again.

     osrf_ctl.sh -l -a start_all

3. 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):

   cd /openils/bin
   ./autogen.sh -c /openils/conf/opensrf_core.xml -u

4. As the root user, restart the Apache Web server:

   /etc/init.d/httpd 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.

Once you have installed and started Evergreen, test your connection to Evergreen via srfsh:

1. 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 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 "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 Evergreen development mailing list for assistance before making any drastic changes to your system configuration.

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 Fedora distributions.

1. 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.0/ directory, you would issue the following command:

   xulrunner /home/opensrf/Evergreen-ILS-2.0.0/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.0/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

Once you've started Evergreen, confirmed that a basic login attempt works but had to restart Evergreen processes you should restart the Web server:

1. 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:

/etc/init.d/httpd configtest && /etc/init.d/httpd restart

If there are any problems with your configuration file(s), they will be displayed.

1. As the opensrf user, stop Evergreen:

   osrf_ctl.sh -l -a stop_all

Evergreen reports are extremely powerful, but some configuration is required.

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