1. Installing prerequisites:

Evergreen has a number of prerequisite packages that must be installed before you can successfully configure, compile, and install Evergreen.

  1. Begin by installing the most recent version of OpenSRF (2.0 or later). You can download OpenSRF releases from http://evergreen-ils.org/downloads

  2. On many distributions, it is necessary to install PostgreSQL 9 from external repositories.

    • On Debian Squeeze, add the following line to /etc/apt/sources.list: 

      deb http://backports.debian.org/debian-backports squeeze-backports main contrib

    • On Ubuntu Lucid, add the following line to /etc/apt/sources.list: 

      deb http://archive.ubuntu.com/ubuntu lucid-backports main universe multiverse restricted

    • On Fedora 14, follow the instructions in the Yum HOWTO to enable the PostgreSQL RPM Building Project yum repository.

    • Fedora 15 comes with PostgreSQL 9, so no additional steps are required.

  3. On Debian and Ubuntu, run aptitude update to retrieve the new packages from the backports repository.

  4. On Debian and Ubuntu, the easiest way to install the rest of the prerequisites for Evergreen is to use the Makefile.install prerequisite installer.

  5. Issue the following commands as the root user to install prerequisites using the Makefile.install prerequisite installer, substituting debian-squeeze, fedora15, fedora14, ubuntu-lucid, centos, or rhel for <osname> below: 

    make -f Open-ILS/src/extras/Makefile.install <osname>

    Note: centos and rhel are less tested than the debian, fedora, and ubuntu options. Your patches and suggestions for improvement are welcome!

  6. Add the libdbi-libdbd libraries to the system dynamic library path by issuing the following commands as the root user:

    Debian / Ubuntu
    echo "/usr/local/lib/dbd" > /etc/ld.so.conf.d/eg.conf
ldconfig
    Fedora
    echo "/usr/lib64/dbd" > /etc/ld.so.conf.d/eg.conf
ldconfig

2. Configuration and compilation instructions:

For the time being, we are still installing everything in the /openils/ directory. If you are working with a version of Evergreen taken directly from the Git repository, rather than a packaged version of Evergreen, first see Developer instructions below.

Otherwise, issue the following commands to configure and build Evergreen:

./configure --prefix=/openils --sysconfdir=/openils/conf
make

3. Installation instructions:

  1. Once you have configured and compiled Evergreen, issue the following command as the root user to install Evergreen, build the server portion of the staff client, and copy example configuration files to /openils/conf. Change the value of the STAFF_CLIENT_STAMP_ID variable to match the version of the staff client that you will use to connect to the Evergreen server. 

    make STAFF_CLIENT_STAMP_ID=rel_name install

  2. The server portion of the staff client expects http://hostname/xul/server to resolve. The following command creates a symbolic link pointing to the server subdirectory of the server portion of the staff client that we just built using the staff client ID rel_name: 

    cd /openils/var/web/xul
ln -sf rel_name/server server

4. Create the oils_web.xml configuration file:

Many administration interfaces, such as acquisitions, bookings, and various configuration screens, depend on the correct configuration of HTML templates. Copying the sample configuration file into place should work in most cases:

cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml

5. Change ownership of the Evergreen files:

All files in the /openils/ directory and subdirectories must be owned by the opensrf user. Issue the following command as the root user to change the ownership on the files:

chown -R opensrf:opensrf /openils

6. Configure the Apache Web server:

  1. Use the example configuration files in Open-ILS/examples/apache/ to configure your Web server for the Evergreen catalog, staff client, Web services, and administration interfaces.

    Debian and Ubuntu
    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 set up SSL
mkdir /etc/apache2/ssl
cd /etc/apache2/ssl
    Fedora
    cp Open-ILS/examples/apache/eg.conf       /etc/httpd/sites-available/
cp Open-ILS/examples/apache/eg_vhost.conf /etc/httpd/
cp Open-ILS/examples/apache/startup.pl    /etc/httpd/
# Now set up SSL
mkdir /etc/httpd/ssl
cd /etc/httpd/ssl

  2. Create an SSL key for the Apache server: 

    openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key

    The openssl command cuts a new SSL key for your Apache server. For a production server, you should purchase a signed SSL certificate, but you can just use a self-signed certificate and accept the warnings in the staff client and browser during testing and development

  3. Edit the eg.conf file that you copied into place.

    1. Replace Allow from 10.0.0.0/8 with 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)

    2. Comment the line Listen 443 as it conflicts with the same declaration elsewhere in the Apache configuration files.

  4. Change the user for the Apache server.

    • (Debian and Ubuntu): As the root user, edit /etc/apache2/envvars. Change export APACHE_RUN_USER=www-data to export APACHE_RUN_USER=opensrf.

    • (Fedora): As the root user, edit /etc/httpd/conf/httpd.conf. Change User apache to User opensrf.

  5. Configure Apache with performance settings appropriate for Evergreen:

    • (Debian and Ubuntu): As the root user, edit /etc/apache2/apache2.conf:

    • (Fedora): As the root user, edit /etc/httpd/conf/httpd.conf:

      1. Change KeepAliveTimeout to 1. Higher values reduce the chance of a request timing out unexpectedly, but increase the risk of using up all available Apache child processes.

      2. Optional: Change MaxKeepAliveRequests to 100

      3. 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 10000
</IfModule>

  6. (Debian and Ubuntu): As the root user, enable the Evergreen site: 

    a2dissite default  # OPTIONAL: disable the default site (the "It Works" page)
a2ensite eg.conf

7. Configure OpenSRF for the Evergreen application:

There are a number of example OpenSRF configuration files in /openils/conf/ that you can use as a template for your Evergreen installation.

cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml

When you installed OpenSRF, you created four Jabber users on two separate domains and edited the opensrf_core.xml file accordingly. Please refer back to the OpenSRF README and edit the Evergreen version of the opensrf_core.xml file using the same Jabber users and domains as you used while installing and testing OpenSRF.

eg_db_config.pl, described in the following section, sets the database connection information in opensrf.xml for you.

8. Creating the Evergreen database:

By default, the Makefile.install prerequisite installer does not install the PostgreSQL 9.0 database server required by every Evergreen system; for production use, most libraries install the PostgreSQL database server on a dedicated machine. You can install the packages required by Debian, Ubuntu, or Fedora on the machine of your choice using the following commands:

(Debian / Ubuntu) Installing PostgreSQL 9.0 server packages
make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_90
(Fedora 15) Installing PostgreSQL 9.0 server packages
make -f Open-ILS/src/extras/Makefile.install install_fedora_pgsql_server

For a standalone PostgreSQL server, install the following Perl modules as the root user:

(Debian / Ubuntu) Installing additional Perl modules on a standalone PostgreSQL 9.0 server
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
(Fedora 15) Installing additional Perl modules on a standalone PostgreSQL 9.0 server
yum install gcc perl-XML-LibXML perl-XML-LibXSLT perl-Business-ISBN
cpan JSON::XS
cpan Library::CallNumber::LC
cpan MARC::Record
cpan MARC::File::XML
cpan UUID::Tiny

Once the PostgreSQL database server has been installed, you must create the database and add the appropriate languages and extensions to support Evergreen. Issue the following commands as the postgres user to set up a database called evergreen. Note that the location of the PostgreSQL contrib packages may vary depending on your distribution. In the following commands, we assume that you are working with PostgreSQL 9.0 on a Debian-based system:

createdb --template template0 --lc-ctype=C --lc-collate=C --encoding UNICODE evergreen
createlang plperl evergreen
createlang plperlu evergreen
psql -f /usr/share/postgresql/9.0/contrib/tablefunc.sql -d evergreen
psql -f /usr/share/postgresql/9.0/contrib/tsearch2.sql -d evergreen
psql -f /usr/share/postgresql/9.0/contrib/pgxml.sql -d evergreen
psql -f /usr/share/postgresql/9.0/contrib/hstore.sql -d evergreen

Once you have created the Evergreen database, you need to create a PostgreSQL user to access the database. Issue the following command as the postgres user to create a new PostgreSQL superuser named evergreen. When prompted, enter the new user’s password:

createuser -s -P evergreen

Once you have created the Evergreen database, you also need to create the database schema and configure your configuration files to point at the database server. Issue the following command as root from inside the Evergreen source directory, replacing <user>, <password>, <hostname>, <port>, and <dbname> with the appropriate values for your PostgreSQL database, and <admin-user> and <admin-pass> with the values you want for the default Evergreen administrator account:

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>

This creates the database schema and configures all of the services in your /openils/conf/opensrf.xml configuration file to point to that database. It also creates the configuration files required by the Evergreen cgi-bin administration scripts, and set the user name and password for the default Evergreen administrator account to your requested values.

9. Developer instructions:

Developers working directly with the source code from the Git repository must also install some extra packages and perform one more step before they can proceed with the ./configure step.

Install the following packages:

  • autoconf

  • automake

  • libtool

Run the following command in the source directory to generate the configure script and Makefiles:

./autogen.sh

After running make install, developers also need to install the Dojo Toolkit set of JavaScript libraries. The appropriate version of Dojo is included in Evergreen release tarballs; developers should install the Dojo 1.3.3 version of Dojo as follows:

wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz
tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz
cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/.

10. Starting Evergreen

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

  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 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</code>

    • 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 in 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

  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 in config.cgi): 

    autogen.sh -u

  4. 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.

11. Testing connections to Evergreen

Once you have installed and started Evergreen, test your connection to Evergreen via srfsh. Start srfsh and try to log onto the Evergreen server using the administrator user name and password that you set using the eg_db_config.pl command:

/openils/bin/srfsh
srfsh% login <admin-user> <admin-pass>

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.

  • Follow the steps in the troubleshooting guide.

  • If you have faithfully followed the entire set of installation steps listed here, 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.

12. Getting help:

Need help installing or using Evergreen? Join the mailing lists at http://evergreen-ils.org/listserv.php or contact us on the Freenode IRC network on the #evergreen channel.