README for Evergreen master =========================== 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 Postgres 9 from external repositories. + * On Debian Squeeze, add the following line to `/etc/apt/sources.list`: + [source, bash] ------------------------------------------------------------------------------ deb http://backports.debian.org/debian-backports squeeze-backports main contrib ------------------------------------------------------------------------------ + * On Ubuntu Lucid, add the following line to `/etc/apt/sources.list`: + [source, bash] ------------------------------------------------------------------------------ deb http://archive.ubuntu.com/ubuntu lucid-backports main universe multiverse restricted ------------------------------------------------------------------------------ + * On Fedora 14, follow the http://yum.pgrpms.org/howtoyum.php[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 below: + [source, bash] ------------------------------------------------------------------------------ make -f Open-ILS/src/extras/Makefile.install ------------------------------------------------------------------------------ Note: `centos` and `rhel` are less tested than the `debian`, `fedora`, and `ubuntu` options. Your patches and suggestions for improvement are welcome! 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: [source, bash] ------------------------------------------------------------------------------ ./configure --prefix=/openils --sysconfdir=/openils/conf make ------------------------------------------------------------------------------ Installation instructions: -------------------------- Once you have configured and compiled Evergreen, issue the following command as the root user to install Evergreen: [source, bash] ------------------------------------------------------------------------------ make STAFF_CLIENT_STAMP_ID=rel_trunk install ------------------------------------------------------------------------------ This will install Evergreen, including example configuration files in `/openils/conf/` that you can use as templates for your own configuration files. The `STAFF_CLIENT_STAMP_ID` variable stamps the server-side and client-side files for the staff client to ensure that they match. 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: [source, bash] ------------------------------------------------------------------------------ cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml ------------------------------------------------------------------------------ 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: [source, bash] ------------------------------------------------------------------------------ chown -R opensrf:opensrf /openils ------------------------------------------------------------------------------ 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 [source,bash] ------------------------------------------------------------------------------ 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 [source,bash] ------------------------------------------------------------------------------ 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: + [source,bash] ------------------------------------------------------------------------------ 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. a. 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) b. 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`: a. 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. b. 'Optional': Change `MaxKeepAliveRequests` to `100` c. Update the prefork configuration section to suit your environment. The following settings apply to a busy system: + [source,bash] ------------------------------------------------------------------------------ StartServers 20 MinSpareServers 5 MaxSpareServers 15 MaxClients 150 MaxRequestsPerChild 10000 ------------------------------------------------------------------------------ + 6. (Debian and Ubuntu): As the root user, enable the Evergreen site: + [source,bash] ------------------------------------------------------------------------------ a2dissite default # OPTIONAL: disable the default site (the "It Works" page) a2ensite eg.conf ------------------------------------------------------------------------------ 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. [source, bash] ------------------------------------------------------------------------------ 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 will have 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, will set the database connection information in `opensrf.xml` for you. Creating the Evergreen database: -------------------------------- PostgreSQL 9.0 will be installed on your system by the `Makefile.install` prerequisite installer if packages are available for your distribution, or you will have to compile PostgreSQL 9.0 from source and install it (which is beyond the scope of this document). Once the PostgreSQL database server has been installed, you will need to 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: [source, bash] ------------------------------------------------------------------------------ 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 user named `evergreen`. When prompted, enter the new user's password and answer `yes` to make the new role a superuser: [source, bash] ------------------------------------------------------------------------------ createuser -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 , , , , and with the appropriate values for your PostgreSQL database, and and with the values you want for the default Evergreen administrator account: [source, bash] ------------------------------------------------------------------------------ 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 ------------------------------------------------------------------------------ This will create the database schema and configure 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. Developer instructions: ----------------------- Developers working directly with the source code from the Git repository will also need to 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: [source, bash] ------------------------------------------------------------------------------ ./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: [source, bash] ------------------------------------------------------------------------------ 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/. ------------------------------------------------------------------------------ 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.