From 5ed0506599405e41b63a0a6d19055f5f1dfc574d Mon Sep 17 00:00:00 2001 From: Steve Sheppard Date: Sun, 17 Apr 2011 13:47:57 -0400 Subject: [PATCH] updates to section 'Installing Evergreen 2.x On Fedora'; --- 2.0/admin/serversideinstallation_2.0.xml | 4259 ++++++++++++---------- 1 file changed, 2425 insertions(+), 1834 deletions(-) diff --git a/2.0/admin/serversideinstallation_2.0.xml b/2.0/admin/serversideinstallation_2.0.xml index 7b1b1bd8da..c768d91696 100644 --- a/2.0/admin/serversideinstallation_2.0.xml +++ b/2.0/admin/serversideinstallation_2.0.xml @@ -1,1834 +1,2425 @@ - - - - Server-side Installation of Evergreen Software - - This section describes installation of the Evergreen server-side software and its associated components. - Installation, configuration, testing and verification - of the software is straightforward if you follow some simple directions. - - - Installing, configuring and testing the Evergreen server-side software is straightforward with the current - stable software release. See for instructions tailored to - installing on some particular distributions of the Linux operating - system. - The current version of the Evergreen server-side software runs as a native application on any of several - well-known Linux distributions - (e.g., Ubuntu and Debian). - It does not currently run as a native application on the Microsoft Windows - operating system (e.g., WindowsXP, WindowsXP - Professional, Windows7), but the software can still be - installed and run on Windows via a so-called - virtualized Linux-guest Operating System (using, for example, - "VirtualBox" or "VMware" - to emulate a Linux - environment). It can also be installed to run on other Linux - systems via virtualized environments (using, for example, "VirtualBox" or - "VMware"). More information on virtualized environments can be found in - . - Installation of the Evergreen Staff Client software is reviewed in . - The Evergreen server-side software has dependencies on particular versions of certain major software - sub-components. Successful installation of Evergreen software requires that software versions agree with those - listed here: - - - Evergreen Software Dependencies - - Evergreen software dependencies - - - - - - - - Evergreen - OpenSRF - PostgreSQL - - - - - 2.0 - 1.6.3 - 8.4 - - - 1.6.1.x - 1.4.0 - 8.2 / 8.3 - - - 1.6.0.x - 1.2 - 8.2 / 8.3 - - - 1.4.x - 1.0 - 8.1 / 8.2 - - - 1.2.x - 0.9 - 8.1 / 8.2 - - - -
-
- Installing Server-Side Software - This section describes the installation of the major components of Evergreen server-side software. - As far as possible, you should perform the following steps in the exact order given since the - success of many steps relies on the successful completion of earlier steps. You should make backup - copies of files and environments when you are instructed to do so. In the event of installation problems - those copies can allow you to back out of a step gracefully and resume the installation from a known - state. See for further information. - Of course, after you successfully complete and test the entire Evergreen installation you should - take a final snapshot backup of your system(s). This can be the first in the series of regularly - scheduled system backups that you should probably also begin. -
- - OpenSRF - installation - - Installing OpenSRF 1.6.3 On <systemitem class="osname">Ubuntu</systemitem> or - <systemitem class="osname">Debian</systemitem> - - Linux - Debian - - - Linux - Ubuntu - - This section describes the installation of the latest version of the Open Service Request - Framework (OpenSRF), a major component of the Evergreen server-side software, on - Ubuntu or Debian - systems. Evergreen software is integrated with and depends on the OpenSRF software - system. - Follow the steps outlined here and run the specified tests to ensure that OpenSRF is - properly installed and configured. Do not - continue with any further Evergreen installation steps - until you have verified that OpenSRF has been successfully installed and tested. - - The following steps have been tested on the x86 (32-bit) architecture of - Debian Squeeze (6.0), - Ubuntu Lucid Lynx (10.04), and on - Fedora 13 and - Fedora 14. - In the following instructions, you are asked to perform certain steps as - either the root user, the - opensrf user, or the - postgres user. - - - Debian -- To become the - root user, issue the command - su - and enter the password of the - root user. - - - Ubuntu -- To become the - root user, issue the command - sudo su - and enter the password of the - root user. - - - To switch from the root user to a - different user, issue the command su - USERNAME. For example, to - switch from the root user to the - opensrf user, issue the command - su - opensrf. Once you have become a non-root user, to become - the root user again, simply issue the command - exit. - - - - Add New <systemitem class="username">opensrf</systemitem> User - As the root user, add the - opensrf user to the system. - In the following example, the default shell for the - opensrf user is automatically set - to /bin/bash to inherit a reasonable environment: - - - # as the root user: - useradd -m -s /bin/bash opensrf - passwd opensrf - - - - Download and Unpack Latest OpenSRF Version - - OpenSRF - download - - The latest version of OpenSRF can be found here: - . - As the opensrf user, change to - the directory /home/opensrf then download - and extract OpenSRF. The new subdirectory - /home/opensrf/OpenSRF-1.6.3 will be created: - - - # as the opensrf user: - cd /home/opensrf - wget http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz - tar zxf OpenSRF-1.6.3.tar.gz - - - - Install Prerequisites to Build OpenSRF - In this section you will install and configure a set of prerequisites that will be - used to build OpenSRF. In a following step you will actually build the OpenSRF software - using the make utility. - As the root user, enter the commands show - below to build the prerequisites from the software distribution that you just downloaded - and unpacked. Remember to replace [DISTRIBUTION] in the following - example with the keyword corresponding to the name of one of the - Linux distributions listed in the - distribution keywords table . - For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would - enter this command: make -f src/extras/Makefile.install ubuntu-lucid . - - - # as the root user: - cd /home/opensrf/OpenSRF-1.6.3 - make -f src/extras/Makefile.install [DISTRIBUTION] - - - - Keyword Targets for OpenSRF <application>"make"</application> Command - - - - - - Keyword - Linux Version - - - - - debian-squeeze - Debian "Squeeze" (6.0) - - - debian-etch - Debian "Etch" (4.0) - - - debian-lenny - Debian "Lenny" (5.0) - - - ubuntu-hardy - Ubuntu "Hardy Heron" (8.04) - - - ubuntu-karmic - Ubuntu "Karmic Koala" (9.10) - - - ubuntu-lucid - Ubuntu "Lucid Lynx" (10.04) - - - fedora13 - Fedora "Goddard" (13) - - - fedora13 - Fedora "Laughlin" (14) - - - centos - CentOS 5 - - - rhel - Red Hat Enterprise Linux 5 - - - gentoo - Gentoo - - - -
- LinuxDebian - LinuxFedora - LinuxUbuntu - LinuxCentOS - LinuxRed Hat - LinuxGentoo - This will install a number of packages on the system that are required by OpenSRF, - including some Perl modules from CPAN. You can say No to the initial - CPAN configuration prompt to allow it to automatically configure itself to download and - install Perl modules from CPAN. The CPAN installer will ask you a number of times whether - it should install prerequisite modules - say Yes. - - - Build OpenSRF - In this section you will configure, build and install the OpenSRF - components that support other Evergreen services. - - - Configure OpenSRF - - OpenSRF - configure - - As the opensrf - user, return to the new OpenSRF build directory and use the - configure utility to prepare for the next - step of compiling and linking the software. If you wish to - include support for Python and Java, add the configuration - options and - , respectively: - - - # as the opensrf user: - cd /home/opensrf/OpenSRF-1.6.3 - ./configure --prefix=/openils --sysconfdir=/openils/conf - make - - This step will take several minutes to complete. - - - Compile, Link and Install OpenSRF - As the root - user, return to the new OpenSRF build directory and use the - make utility to compile, link and install - OpenSRF: - - - # as the root user: - cd /home/opensrf/OpenSRF-1.6.3 - make install - - This step will take several minutes to complete. - - - Update the System Dynamic Library Path - You must update the system dynamic library path to force - your system to recognize the newly installed libraries. As the - root user, do this by - creating the new file - /etc/ld.so.conf.d/osrf.conf containing two - new library paths, then execute the command - ldconfig to automatically read the file and - modify the system dynamic library path: - - - # as the root user: - echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf - echo "/usr/local/lib >> /etc/ld.so.conf.d/osrf.conf - ldconfig - - - - Define Public and Private OpenSRF Domains - For security purposes, OpenSRF uses Jabber domains to separate services - into public and private realms. On a single-server system the easiest way to - define public and private OpenSRF domains is to define separate host names by - adding entries to the file /etc/hosts. - In the following steps we will use the example domains - public.localhost for the public - domain and private.localhost - for the private domain. In an upcoming step, you will configure two special - ejabberd users - to handle communications for these two domains. - As the root user, edit the file - /etc/hosts and add the following example domains: - - Jabber - - - - # as the root user: - 127.0.1.2 public.localhost public - 127.0.1.3 private.localhost private - - - - Change File Ownerships - Finally, as the root - user, change the ownership of all files installed in the - directory /openils to the - user opensrf: - - - # as the root user: - chown -R opensrf:opensrf /openils - - - - - - Stop the <systemitem class="service">ejabberd</systemitem> Service - - ejabberd - - Before continuing with configuration of ejabberd - you must stop that service. As the root user, - execute the following command to stop the service: - - - # as the root user: - /etc/init.d/ejabberd stop - - If ejabberd reports that it - is already stopped, there may have been a problem when it started back - in the installation step. If there are any remaining daemon processes such as - beam or - epmd - you may need to perform the following commands to kill them: - - - # as the root user: - epmd -kill - killall beam; killall beam.smp - rm /var/lib/ejabberd/* - echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd - - - - Edit the <systemitem class="service">ejabberd</systemitem> configuration - You must make several configuration changes for the - ejabberd service before - it is started again. - As the root user, edit the file - /etc/ejabberd/ejabberd.cfg and make the following changes: - - - Change the line: - {hosts, ["localhost"]}. - to instead read: - {hosts, ["localhost", "private.localhost", "public.localhost"]}. - - - - Change the line for older versions of ejabberd: - {max_user_sessions, 10} - to instead read: - {max_user_sessions, 10000} - - Change the line for newer versions of ejabberd: - {access, max_user_sessions, [{10, all}]} - to instead read: - {access, max_user_sessions, [{10000, all}]} - - - Change all three occurrences of: - max_stanza_size - to instead read: - 2000000 - - - Change both occurrences of: - maxrate - to instead read: - 500000 - - - Comment out the line: - {mod_offline, []} - by placing two % comment signs in front - so it instead reads: - %%{mod_offline, []} - - - - - Restart the <systemitem class="service">ejabberd</systemitem> service - As the root user, restart the - ejabberd service to test the - configuration changes and to register your users: - - - # as the root user: - /etc/init.d/ejabberd start - - - - Register <systemitem class="username">router</systemitem> and - <systemitem class="username">opensrf</systemitem> as - <systemitem class="service">ejabberd</systemitem> users - The two ejabberd users - router and - opensrf must be registered - and configured to manage OpenSRF router service and communications - for the two domains public.localhost and - private.localhost that you added to the file - /etc/hosts in a previous step - (see ). - The users include: - - - the router user, - to whom all requests to connect to an OpenSRF service will be - routed; - - - the opensrf user, - which clients use to connect to OpenSRF services (you may name - the user anything you like, but we use - opensrf in these examples) - - - As the root user, execute the - ejabberdctl utility as shown below to register and create passwords - for the users router and - opensrf on each domain (remember to replace - NEWPASSWORD with the appropriate password): - - - # as the root user: - # Note: the syntax for registering a user with ejabberdctl is: - # ejabberdctl register USER DOMAIN PASSWORD - ejabberdctl register router private.localhost NEWPASSWORD - ejabberdctl register router public.localhost NEWPASSWORD - ejabberdctl register opensrf private.localhost NEWPASSWORD - ejabberdctl register opensrf public.localhost NEWPASSWORD - - The users router and - opensrf and their respective passwords - will be used again in when - we modify the OpenSRF configuration file /openils/conf/opensrf_core.xml . - - - There appears to be a problem with ejabberdctl in - that it does not escape input correctly, so a password like - '0P3N$SRF' will be created as '0P3N'. - A bug against ejabberd has been filed. To register a password using - ejabberdctl with special shell characters until such - time as that bug is resolved, the workaround is to specify a - double-escaped character at the command line, for example, - '0P3N\\\\$RF' . - - - - Create OpenSRF configuration files - As the opensrf user, - execute the following commands to create the new configuration files - /openils/conf/opensrf_core.xml and - /openils/conf/opensrf.xml from the example templates: - - - # as the opensrf user: - cd /openils/conf - cp opensrf.xml.example opensrf.xml - cp opensrf_core.xml.example opensrf_core.xml - - - - Update usernames and passwords in the OpenSRF configuration file - As the opensrf user, edit the - OpenSRF configuration file /openils/conf/opensrf_core.xml - and update the usernames and passwords to match the values shown in the - following table. The left-hand side of - shows common XPath syntax to indicate the approximate position within the XML - file that needs changes. The right-hand side of the table shows the replacement - values: - - - Sample XPath syntax for editing "opensrf_core.xml" - - - - - - XPath location - Value - - - - - /config/opensrf/username - - opensrf - - - - /config/opensrf/passwd - private.localhost - password for - opensrf user - - - - /config/gateway/username - - opensrf - - - - /config/gateway/passwd - public.localhost - password for - opensrf user - - - - /config/routers/router/transport/username, - first entry where server == public.localhost - - router - - - - /config/routers/router/transport/password, - first entry where server == public.localhost - public.localhost - password for - router user - - - - /config/routers/router/transport/username, - second entry where server == private.localhost - - router - - - - /config/routers/router/transport/password, - second entry where server == private.localhost - private.localhost - password for - router user - - - - -
- You may also need to modify the file to specify the domains from which - OpenSRF will accept connections, - and to which it will make connections. - If you are installing OpenSRF on a single server - and using the private.localhost and - public.localhost domains, - these will already be set to the correct values. Otherwise, search and replace - to match values for your own systems. - - - Set the location of the persistent database - As the opensrf user, edit the - file /openils/conf/opensrf.xml, then find and verify that - the element dbfile (near the end of the file) is set to the - location of the persistent database. If necessary, change the default line: - /openils/var/persist.db - to instead read: - /tmp/persist.db - Following is a sample modification of that portion of the file: - - - - /tmp/persist.db - - -]]> - - - Create configuration files for users needing <command>srfsh</command> - In this section you will set up a special configuration file for each user - who will need to run the srfsh (pronounced surf - shell) utility. - - srfsh - - The software installation will automatically create the utility - srfsh, a command line diagnostic tool for testing and - interacting with OpenSRF. It will be used - in a future step to complete and test the Evergreen installation. See - for further information. - As the root user, copy the - sample configuration file /openils/conf/srfsh.xml.example - to the home directory of each user who will use srfsh. - For instance, do the following for the - opensrf user: - - - # as the root user: - cp /openils/conf/srfsh.xml.example /home/opensrf/.srfsh.xml - - Edit each user's file ~/.srfsh.xml and make the - following changes: - - - Modify domain to be the router hostname - (following our domain examples, - private.localhost will give - srfsh access to all OpenSRF services, while - public.localhost - will only allow access to those OpenSRF services that are - publicly exposed). - - - Modify username and - password to match the - opensrf Jabber user for the chosen - domain - - - Modify logfile to be the full path for - a log file to which the user has write access - - - Modify loglevel as needed for testing - - - Change the owner of the file to match the owner of the home directory - - - Following is a sample of the file: - - - - -router -private.localhost -opensrf -SOMEPASSWORD -5222 -/tmp/srfsh.log - -4 - -]]> - - - Modify the environmental variable <envar>PATH</envar> for the - <systemitem class="username">opensrf</systemitem> user - As the opensrf user, modify the - environmental variable PATH by adding a new file path to the - opensrf user's shell configuration - file ~/.bashrc: - - - # as the opensrf user: - echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc - - - - Start OpenSRF - As the root user, start the - ejabberd and - memcached services: - - - # as the root user: - /etc/init.d/ejabberd start - /etc/init.d/memcached start - - Then as the opensrf user, - start OpenSRF as follows: - - - # as the opensrf user: - osrf_ctl.sh -l -a start_all - - The flag forces Evergreen to use - localhost (your current system) - as the hostname. The flag starts the - OpenSRF router , - Perl , and - C services. - - - You can also start Evergreen without the - flag, but the osrf_ctl.sh - utility must know the fully qualified domain name for the system - on which it will execute. That hostname was probably specified - in the configuration file opensrf.xml which - you configured in a previous step. - - - If you receive an error message similar to - osrf_ctl.sh: command not found, then your - environment variable PATH does not include the - directory /openils/bin. - As the opensrf user, - edit the configuration file ~/.bashrc and - add the following line: - export PATH=$PATH:/openils/bin - - - - - Test connections to OpenSRF - Once you have installed and started OpenSRF, as the - root user test your connection to - OpenSRF with the srfsh - utility and try to call the add method on the OpenSRF - math service: - - - # as the root user: - /openils/bin/srfsh - - srfsh# request opensrf.math add 2 2 - - Received Data: 4 - ------------------------------------ - Request Completed Successfully - Request Time in seconds: 0.007519 - ------------------------------------ - - For other srfsh commands, type in - help at the prompt. - - - Stop OpenSRF - After OpenSRF has started, you can stop it at any time by using the - osrf_ctl.sh again. As the - opensrf - user, stop OpenSRF as follows: - - - # as the opensrf user: - osrf_ctl.sh -l -a stop_all - - - -
-
- Installing Evergreen 2.0 On <systemitem class="osname">Ubuntu</systemitem> or - <systemitem class="osname">Debian</systemitem> - - Linux - Debian - - - Linux - Ubuntu - - This section outlines the installation process for the latest stable version of - Evergreen. - In this section you will download, unpack, install, configure and test the Evergreen - system, including the Evergreen server and the PostgreSQL database system. You will make several - configuration changes and adjustments to the software, including updates to configure the system - for your own locale, and some updates needed to work around a few known issues. - - 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. - In the following instructions, you are asked to perform certain steps as - either the root user, the - opensrf user, or the - postgres user. - - - Debian -- To become the - root user, issue the command - su - and enter the password of the - root user. - - - Ubuntu -- To become the - root user, issue the command - sudo su - and enter the password of the - root user. - - - To switch from the root user to a - different user, issue the command su - USERNAME. For example, to - switch from the root user to the - opensrf user, issue the command - su - opensrf. Once you have become a non-root user, to become the - root user again, simply issue the command - exit. - - - - Install OpenSRF - Evergreen software is integrated with and depends on the Open Service - Request Framework (OpenSRF) software system. For further information on - installing, configuring and testing OpenSRF, see - . - Follow the steps outlined in that section and run the specified tests to - ensure that OpenSRF is properly installed and configured. Do - not continue with - any further Evergreen installation steps until you have verified that OpenSRF - has been successfully installed and tested. - - - Download and Unpack Latest Evergreen Version - The latest version of Evergreen can be found here: - . - As the opensrf user, change to - the directory /home/opensrf then download - and extract Evergreen. The new subdirectory - /home/opensrf/Evergreen-ILS-2.0.4 will be created: - - - # as the opensrf user: - cd /home/opensrf - wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz - tar zxf Evergreen-ILS-2.0.4.tar.gz - - - - Install Prerequisites to Build Evergreen - In this section you will install and configure a set of prerequisites that will be - used later in and - to build the Evergreen software - using the make utility. - As the root user, enter the commands show - below to build the prerequisites from the software distribution that you just downloaded - and unpacked. Remember to replace [DISTRIBUTION] in the following - example with the keyword corresponding to the name of one of the - Linux distributions listed in the following - distribution list. - For example, to install the prerequisites for Ubuntu version 10.05 (Lucid Lynx) you would - enter this command: make -f Open-ILS/src/extras/Makefile.install - ubuntu-lucid. - - - # as the root user: - cd /home/opensrf/Evergreen-ILS-2.0.4 - make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION] - - - - - for Debian Squeeze (6.0) - - - - for Ubuntu Lucid Lynx - (10.04) - - - - - (OPTIONAL) Install the PostgreSQL Server - - databases - PostgreSQL - - Since the PostgreSQL server is usually a standalone server in multi-server - production systems, the prerequisite installer Makefile in the previous section - (see ) - does not automatically install PostgreSQL. You must install the PostgreSQL server - yourself, either on the same system as Evergreen itself or on another system. - If your PostgreSQL server is on a different system, just skip this step. - If your PostgreSQL server will be on the same system as your Evergreen - software, you can install the required PostgreSQL server packages as described - in , or you can visit the official - web site http://www.postgresql.org - for more information. - - PostgreSQL version 8.4 is the minimum supported version to work - with Evergreen 2.0. If you have an older version of PostgreSQL, - you should upgrade before installing Evergreen. To find your current version - of PostgreSQL, as the postgres - user execute the command psql, then type - SELECT version(); to get detailed information - about your version of PostgreSQL. - - - - Install Perl Modules on PostgreSQL Server - If PostgreSQL is running on the same system as your Evergreen software, - then the Perl modules will automatically be available. Just skip this step. - Otherwise, continue if your PostgreSQL server is running on another system. - You will need to install several Perl modules on the other system. As the - root user install the following Perl - modules: - as the root user, ensure the gcc compiler is installed: - - aptitude install gcc libxml-libxml-perl libxml-libxslt-perl - - then install the Perl modules: - - perl -MCPAN -e shell - cpan> Business::ISBN - cpan> install JSON::XS - cpan> Library::CallNumber::LC - cpan> install MARC::Record - cpan> install MARC::File::XML - cpan> cpan UUID::Tiny - - For more information on installing Perl Modules vist the official - CPAN site. - - Perl - CPAN - - - - Update the System Dynamic Library Path - You must update the system dynamic library path to force your system to recognize - the newly installed libraries. As the root user, - do this by creating the new file /etc/ld.so.conf.d/osrf.conf - containing a new library path, then run the command ldconfig to - automatically read the file and modify the system dynamic library path: - - - # as the root user: - echo "/usr/local/lib" >> /etc/ld.so.conf.d/osrf.conf - echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf - ldconfig - - - - Restart the PostgreSQL Server - If PostgreSQL is running on the same system as the rest of Evergreen, as - the root user you must restart - PostgreSQL to re-read the new library paths just configured. If PostgreSQL is - running on another system, you may skip this step. - As the opensrf user, - execute the following command (remember to replace - PGSQL_VERSION with your installed PostgreSQL version, - for example 8.4): - - - # as the opensrf user: - /etc/init.d/postgresql-PGSQL_VERSION restart - - - - Configure Evergreen - In this step you will use the configure and - make utilities to configure Evergreen so it can be compiled - and linked later in . - As the opensrf user, return to - the Evergreen build directory and execute these commands: - - - # as the opensrf user: - cd /home/opensrf/Evergreen-ILS-2.0.4 - ./configure --prefix=/openils --sysconfdir=/openils/conf - make - - - - Compile, Link and Install Evergreen - In this step you will actually compile, link and install Evergreen and the - default Evergreen Staff Client. - As the root user, return to the - Evergreen build directory and use the make utility as shown below: - - - # as the root user: - cd /home/opensrf/Evergreen-ILS-2.0.4 - make STAFF_CLIENT_BUILD_ID=rel_2_0_4 install - - The Staff Client will also be automatically built, but you must remember - to set the variable STAFF_CLIENT_BUILD_ID to match the version of the - Staff Client you will use to connect to the Evergreen server. - The above commands will create a new subdirectory - /openils/var/web/xul/rel_2_0_4 - containing the Staff Client. - To complete the Staff Client installation, as the - root user execute the following commands to - create a symbolic link named server in the head of the Staff Client - directory /openils/var/web/xul that points to the - subdirectory /server of the new Staff Client - build: - - - # as the root user: - cd /openils/var/web/xul - ln -sf rel_2_0_4/server server - - - - Copy the OpenSRF Configuration Files - In this step you will replace some OpenSRF configuration files that you set up in - when you installed and - tested OpenSRF. - You must copy several example OpenSRF configuration files into place after first - creating backup copies for troubleshooting purposes, then change all the file ownerships - to opensrf. - As the root user, execute the following - commands: - - - # as the root user: - cd /openils/conf - cp opensrf.xml opensrf.xml.BAK - cp opensrf_core.xml opensrf_core.xml.BAK - cp opensrf.xml.example opensrf.xml - cp opensrf_core.xml.example opensrf_core.xml - cp oils_web.xml.example oils_web.xml - chown -R opensrf:opensrf /openils/ - - - - Create and Configure PostgreSQL Database - - databases - PostgreSQL - - In this step you will create the Evergreen database. In the commands - below, remember to adjust the path of the contrib - repository to match your PostgreSQL server - layout. For example, if you built PostgreSQL from source the path would be - /usr/local/share/contrib , and if you - installed the PostgreSQL 8.4 server packages on Ubuntu, - the path would be - /usr/share/postgresql/8.4/contrib/ . - - - - Create and configure the database - - As the postgres - user on the PostgreSQL system create the PostgreSQL database, - then set some internal paths: - - - # as the postgres user: - createdb evergreen -E UTF8 -T template0 - createlang plperl evergreen - createlang plperlu evergreen - createlang plpgsql evergreen - - Continue as the postgres user - and execute the SQL scripts as shown below (remember to adjust the paths as needed, - where PGSQL_VERSION is your installed PostgreSQL - version, for example 8.4). - - - # as the postgres user: - psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen - psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen - psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen - - - - Create <systemitem class="username">evergreen</systemitem> PostgreSQL user - As the postgres - user on the PostgreSQL system, create a new PostgreSQL user - named evergreen and - assign a password (remember to replace NEWPASSWORD - with an appropriate new password): - - - # as the postgres user: - createuser -P -s evergreen - - Enter password for new role: NEWPASSWORD - Enter it again: NEWPASSWORD - - - - Create database schema - In this step you will create the database schema and configure your - system with the corresponding database authentication details for the - evergreen database user that you just created in - . - As the root user, enter - the following commands and replace HOSTNAME, PORT, - PASSWORD and DATABASENAME with appropriate - values: - -cd /home/opensrf/Evergreen-ILS-2.0.4 -perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ ---service all --create-schema --create-offline \ ---hostname HOSTNAME --port PORT \ ---user evergreen --password PASSWORD \ ---database DATABASENAME --admin-user ADMIN-USER \ ---admin-pass ADMIN-PASSWORD - - On most systems, HOSTNAME will be - localhost and - PORT will be 5432. - Of course, values for PASSWORD and - DATABASENAME must match the values you used in - . The and options will - specify the Evergreen administrator account's username and password. This was - changed for security reasons, it was previously admin/open-ils - As the command executes, you may see warnings similar to: - ERROR: schema SOMENAME does not exist (in fact, - you may see one warning per schema) but they can be safely ignored. - If you are entering the above command on a single line, do not - include the \ (backslash) characters. If you are using - the bash shell, 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. - - - - - Configure the Apache web server - - web server - Apache - - In this step you will configure the Apache web server to support Evergreen - software. - First, you must enable some built-in Apache modules and install some - additional Apache configuration files. Then you will create a new Security - Certificate. Finally, you must make several changes to the Apache configuration - file. - - - Enable the required Apache Modules - As the root - user, enable some modules in the Apache server, then copy the - new configuration files to the Apache server directories: - - Apache modules - - - - # as the root user: - a2enmod ssl # enable mod_ssl - a2enmod rewrite # enable mod_rewrite - a2enmod expires # enable mod_expires - - As the commands execute, you may see warnings similar to: - Module SOMEMODULE already enabled but you can - safely ignore them. - - - Copy Apache configuration files - You must copy the Apache configuration files from the - Evergreen installation directory to the Apache directory. As the - root user, perform the - following commands: - - - # as the root user: - cd /home/opensrf/Evergreen-ILS-2.0.4 - 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/ - - - - Create a Security Certificate - In this step you will create a new Security Certificate (SSL Key) - for the Apache server using the openssl command. For a - public production server you must configure or purchase a signed SSL - certificate, but for now you can just use a self-signed certificate and - accept the warnings in the Staff Client and browser during testing and - development. As the root user, - perform the following commands: - - - # as the root user: - mkdir /etc/apache2/ssl - cd /etc/apache2/ssl - openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key - - You will be prompted for several items of information; enter - the appropriate information for each item. The new files - server.crt and server.key will - be created in the directory - /etc/apache2/ssl . - This step generates a self-signed SSL certificate. You must install - a proper SSL certificate for a public production system to avoid warning - messages when users login to their account through the OPAC or when staff - login through the Staff Client. For further information on - installing a proper SSL certificate, see - . - - - Update Apache configuration file - You must make several changes to the new Apache - configuration file - /etc/apache2/sites-available/eg.conf . - As the root user, - edit the file and make the following changes: - - - In the section - <Directory "/openils/var/cgi-bin"> - replace the line: - Allow from 10.0.0.0/8 - with the line: - Allow from all - This change allows access to your configuration - CGI scripts from any workstation on any network. This is - only a temporary change to expedite testing and should be - removed after you have finished and successfully tested - the Evergreen installation. See - - for further details on removing this change after the - Evergreen installation is complete. - - - - Comment out the line: - Listen 443 - since it conflicts with the same declaration in - the configuration file: - /etc/apache2/ports.conf. - - - The following updates are needed to allow the logs - to function properly, but it may break other Apache - applications on your server: - - Edit the Apache configuration file and change the lines: - -export APACHE_RUN_USER=www-data -export APACHE_RUN_GROUP=www-data - - to instead read: - - - export APACHE_RUN_USER=opensrf - export APACHE_RUN_GROUP=opensrf - - - - As the - root user, - edit the Apache configuration file - /etc/apache2/apache2.conf and - modify the value for KeepAliveTimeout - and MaxKeepAliveRequests to match - the following: - - - KeepAliveTimeout 1 - MaxKeepAliveRequests 100 - - - - Further configuration changes to Apache may be - necessary for busy systems. These changes increase the - number of Apache server processes that are started to - support additional browser connections. - As the - root user, - edit the Apache configuration file - /etc/apache2/apache2.conf, locate - and modify the section related to prefork - configuration to suit the load on your - system: - - StartServers 20 - MinSpareServers 5 - MaxSpareServers 15 - MaxClients 150 - MaxRequestsPerChild 10000 - -]]> - - - - - Enable the Evergreen web site - Finally, you must enable the Evergreen web site. As the - root user, execute the - following Apache configuration commands to disable the default - It Works web page and enable the Evergreen - web site, and then restart the Apache server: - - - # as the root user: - # disable/enable web sites - a2dissite default - a2ensite eg.conf - # restart the server - /etc/init.d/apache2 reload - - - - - - Update the OpenSRF Configuration File - As the opensrf user, edit the - OpenSRF configuration file /openils/conf/opensrf_core.xml - to update the Jabber usernames and passwords, and to specify the domain from - which we will accept and to which we will 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. - The left-hand side of - shows common XPath syntax to indicate the approximate position within the XML - file that needs changes. The right-hand side of the table shows the replacement - values: - - - Sample XPath syntax for editing "opensrf_core.xml" - - - - - - XPath location - Value - - - - - /config/opensrf/username - - opensrf - - - - /config/opensrf/passwd - private.localhost - password for - opensrf user - - - - /config/gateway/username - - opensrf - - - - /config/gateway/passwd - public.localhost - password for - opensrf user - - - - /config/routers/router/transport/username, - first entry where server == public.localhost - - router - - - - /config/routers/router/transport/password, - first entry where server == public.localhost - public.localhost - password for - router user - - - - /config/routers/router/transport/username, - second entry where server == private.localhost - - router - - - - /config/routers/router/transport/password, - second entry where server == private.localhost - private.localhost - password for - router user - - - - -
- - - (OPTIONAL) Create Configuration Files for Users Needing <command>srfsh</command> - When OpenSRF was installed in , the - software installation automatically created a utility named srfsh (surf - shell). This is a command line diagnostic tool for testing and interacting with - OpenSRF. It will be used in a future step to complete and test the Evergreen installation. - Earlier in you also created a configuration - file ~/.srfsh.xml for each user that might need to use the utility. - See for further information. - - - Modify the OpenSRF Environment - In this step you will make some minor modifications to the OpenSRF environment: - - - As the opensrf user, - modify the shell configuration file ~/.bashrc for - user opensrf by adding a Perl - environmental variable, then execute the shell configuration file to load - the new variables into your current environment. - In a multi-server environment, you must add any - modifications to ~/.bashrc to the top of the file - before the line [ -z "$PS1" ] && - return . This will allow headless (scripted) logins to load the - correct environment. - - - # as the opensrf user: - echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc - . ~/.bashrc - - - - - - (OPTIONAL) Enable and Disable Language Localizations - You can 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. For further information, see - . - - -
-
- Installing Evergreen 2.x On <systemitem class="osname">Fedora 13</systemitem> or - <systemitem class="osname">Fedora 14</systemitem> -
-
- Starting Evergreen - In this section you will learn how to start the Evergreen services. - For completeness, instructions for stopping Evergreen can be found later in - . - - - As the root - user, start the ejabberd and - memcached services as follows: - - - # as the root user: - /etc/init.d/ejabberd start - /etc/init.d/memcached start - - - - As the opensrf user, - start the OpenSRF router service as follows: - - - # as the opensrf user: - osrf_ctl.sh -l -a start_all - - The flag forces Evergreen to use - localhost (your current system) - as the hostname. The flag starts the - OpenSRF router , - Perl , and - C services. - - - You can also start Evergreen without the - flag, but the osrf_ctl.sh - utility must know the fully qualified domain name for the system - on which it will execute. That hostname was probably specified - in the configuration file opensrf.xml which - you configured in a previous step. - - - If you receive an error message similar to - osrf_ctl.sh: command not found, then your - environment variable PATH does not include the - directory /openils/bin. - As the opensrf user, - edit the configuration file ~/.bashrc and - add the following line: - export PATH=$PATH:/openils/bin - - - If you receive an error message similar to Can't - locate OpenSRF/System.pm in @INC ... BEGIN failed--compilation - aborted, then your environment variable - PERL5LIB does not include the - directory /openils/lib/perl5. - As the opensrf user, - edit the configuration file ~/.bashrc and - add the following line: - export PERL5LIB=$PERL5LIB:/openils/lib/perl5 - - - - - In this step you will generate the Web files needed by the Staff Client - and catalog, and update the proximity of locations in the Organizational Unit - tree (which allows Holds to work properly). - You must do this the first time you start Evergreen and after making any - changes to the library hierarchy. - As the opensrf user, execute the - following command and review the results: - - - # as the opensrf user: - cd /openils/bin - ./autogen.sh -c /openils/conf/opensrf_core.xml -u - - Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml' - Updating fieldmapper - Updating web_fieldmapper - Updating OrgTree - removing OrgTree from the cache for locale hy-AM... - removing OrgTree from the cache for locale cs-CZ... - removing OrgTree from the cache for locale en-CA... - removing OrgTree from the cache for locale en-US... - removing OrgTree from the cache for locale fr-CA... - removing OrgTree from the cache for locale ru-RU... - Updating OrgTree HTML - Updating locales selection HTML - Updating Search Groups - Refreshing proximity of org units - Successfully updated the organization proximity - Done - - - - As the root user, restart the - Apache Web server: - - - # as the root user: - /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 into the OPAC or Staff - Client until the Apache Web server has been restarted. - - -
-
- Testing Your Evergreen Installation - This section describes several simple tests you can perform to verify that the Evergreen - server-side software has been installed and configured properly and is running as - expected. - - Testing Connections to Evergreen - Once you have installed and started Evergreen, test your connection to Evergreen. Start the - srfsh application and try logging onto the Evergreen server using the default - administrator username and password. Following is sample output generated by executing - srfsh after a successful Evergreen installation. For help with - srfsh commands, type help at the prompt. - As the opensrf user, - execute the following commands to test your Evergreen connection: - - - # as the opensrf user: - /openils/bin/srfsh - - srfsh% login admin open-ils - 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, try the following: - - - As the opensrf user, run the - settings-tester.pl utility to review your Evergreen - installation for any system configuration problems: - - - # as the opensrf user: - cd /home/opensrf - ./Evergreen-ILS-2.0.4/Open-ILS/src/support-scripts/settings-tester.pl - - 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 in - . - - - 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 - list for assistance before making any drastic changes to your system - configuration. - - - - - Testing the Staff Client on Linux - In this section you will confirm that a basic login on the Staff Client works - properly. - Run the Evergreen Staff Client on a Linux system by using the application - XULRunner (installed automatically and by default with Firefox - version 3.0 and later on Ubuntu and Debian distributions). - As the root user, start the Staff Client - as shown: - - - # as the root user: - xulrunner /home/opensrf/Evergreen-ILS-v/Open-ILS/xul/staff_client/build/application.ini - - A login screen for the Staff Client similar to this should appear: - - Logging into the Staff Client - - - - - First, add the name of your Evergreen server to the field - Hostname in the Server section. You will probably - want to use 127.0.0.1. After adding the server name, click Re-Test - Server. You should now see the messages 200:OK in the fields - Status and Version. - Because this is the initial run of the Staff Client, you will see a warning in the - upper-right saying: Not yet configured for the specified - server. To continue, you must assign a workstation name. - Try to log into the Staff Client with the admin username and password you created during installation. If the login is successful, - you will see the following screen: - - Logging into the Staff Client - - - - - Otherwise, you may need to click 'Add SSL Exception' in the - main window. You should see a popup window titled Add Security Exception: - - Adding an SSL Exception in the Staff Client - - - - - Click 'Get Certificate', then click 'Confirm - Security Exception', then click 'Re-Test Server' in the - main window and try to log in again. - - - Testing the Apache Web Server - In this section you will test the Apache configuration file(s), then restart the - Apache web server. - As the root user, execute the following - commands. Note the use of restart to force the new Evergreen - modules to be reloaded even if the Apache server is already running. Any problems found - with your configuration files should be displayed: - - - # as the root user: - apache2ctl configtest && /etc/init.d/apache2 restart - - - - Stopping Evergreen - In you learned how to start the - Evergreen services. For completeness, following are instructions for stopping the - Evergreen services. - As the opensrf user, stop all Evergreen - services by using the following command: - - - # as the opensrf user - # stop the server; use "-l" to force hostname to be "localhost" - osrf_ctl.sh -l -a stop_all - - You can also stop Evergreen services without the - flag, but the osrf_ctl.sh utility must know the - fully qualified domain name for the system on which it will execute. That hostname may - have been specified in the configuration file opensrf.xml, which - you configured in a previous step. - -
-
- Post-Installation Chores - There are several additional steps you may need to complete after Evergreen has been - successfully installed and tested. Some steps may not be needed (e.g., setting up support for - Reports). -
- Remove temporary Apache configuration changes - You modified the Apache configuration file - /etc/apache2/sites-available/eg.conf in an earlier step as a - temporary measure to expedite testing (see - for further information). - Those changes must now be reversed in order to deny unwanted access to your - CGI scripts from users on other public networks. - - - This temporary network update was done to expedite - testing. You must correct - this for a public production system. - - - As the root user, edit the configuration - file again and comment out the line Allow from all and uncomment the - line Allow from 10.0.0.0/8, then change it to match your network - address scheme. -
-
- Configure a permanent SSL key - You used the command openssl in an earlier step to - temporarily create a new SSL key for the Apache server (see - for further - information). This self-signed security certificate was adequate during - testing and development, but will continue to generate warnings in the Staff - Client and browser. For a public production server you should configure or - purchase a signed SSL certificate. - There are several open source software solutions that provide schemes to - generate and maintain public key security certificates for your library - system. Some popular projects are listed below; please review them for - background information on why you need such a system and how you can provide - it: - - - http://www.openca.org/projects/openca/ - - - http://sourceforge.net/projects/ejbca/ - - - http://pki.fedoraproject.org - - - - - The temporary SSL key was only created to expedite - testing. You should install a proper SSL certificate for a public - production system. - - -
-
- (OPTIONAL) IP-Redirection - By default, Evergreen is configured so searching the OPAC always starts in the - top-level (regional) library rather than in a second-level (branch) library. Instead, - you can use "IP-Redirection" to change the default OPAC search location to use the IP - address range assigned to the second-level library where the seach originates. You must - configure these IP ranges by creating the configuration file - /openils/conf/lib_ips.txt and modifying the Apache startup script - /etc/apache2/startup.pl. - First, copy the sample file - /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/examples/lib_ips.txt.example - to /openils/conf/lib_ips.txt. The example file contains the single - line: "MY-LIB 127.0.0.1 127.0.0.254". You must modify the file to use - the IP address ranges for your library system. Add new lines to represent the IP address - range for each branch library. Replace the values for MY-LIB with the - values for each branch library found in the table - actor.org_unit. - Finally, modify the Apache startup script - /etc/apache2/startup.pl by uncommenting two lines as shown, then - restarting the Apache server: - -# - e.g. LIB123 10.0.0.1 10.0.0.254 -use OpenILS::WWW::Redirect qw(/openils/conf/opensrf_core.xml); -OpenILS::WWW::Redirect->parse_ips_file('/openils/conf/lib_ips.txt'); -]]> -
-
- (OPTIONAL) Set Up Support For Reports - Evergreen reports are extremely powerful but require some simple configuration. - See for information on starting and - stopping the Reporter daemon processes. -
-
-
- + + + + Server-side Installation of Evergreen Software + + This section describes installation of the Evergreen server-side software and + its associated components. Installation, configuration, testing and verification of + the software is straightforward if you follow some simple directions. + + + Installing, configuring and testing the Evergreen server-side software is straightforward with the current + stable software release. See for instructions tailored to + installing on some particular distributions of the Linux operating + system. + The current version of the Evergreen server-side software runs as a native application on any of several + well-known Linux distributions + (e.g., Ubuntu and Debian). + It does not currently run as a native application on the Microsoft Windows + operating system (e.g., WindowsXP, WindowsXP + Professional, Windows7), but the software can still be + installed and run on Windows via a so-called + virtualized Linux-guest Operating System (using, for example, + "VirtualBox" or "VMware" + to emulate a Linux + environment). It can also be installed to run on other Linux + systems via virtualized environments (using, for example, "VirtualBox" or + "VMware"). More information on virtualized environments can be found in + . + Installation of the Evergreen Staff Client software is reviewed in . + The Evergreen server-side software has dependencies on particular versions of certain major software + sub-components. Successful installation of Evergreen software requires that software versions agree with those + listed here: + + + Evergreen Software Dependencies + + Evergreen software dependencies + + + + + + + + Evergreen + OpenSRF + PostgreSQL + + + + + 2.0 + 1.6.3 + 8.4 + + + 1.6.1.x + 1.4.0 + 8.2 / 8.3 + + + 1.6.0.x + 1.2 + 8.2 / 8.3 + + + 1.4.x + 1.0 + 8.1 / 8.2 + + + 1.2.x + 0.9 + 8.1 / 8.2 + + + +
+
+ Installing Server-Side Software + This section describes the installation of the major components of Evergreen server-side software. + As far as possible, you should perform the following steps in the exact order given since the + success of many steps relies on the successful completion of earlier steps. You should make backup + copies of files and environments when you are instructed to do so. In the event of installation problems + those copies can allow you to back out of a step gracefully and resume the installation from a known + state. See for further information. + Of course, after you successfully complete and test the entire Evergreen installation you should + take a final snapshot backup of your system(s). This can be the first in the series of regularly + scheduled system backups that you should probably also begin. +
+ + OpenSRF + installation + + Installing OpenSRF 1.6.x On <systemitem class="osname">Ubuntu</systemitem> or + <systemitem class="osname">Debian</systemitem> + + Linux + Debian + + + Linux + Ubuntu + + This section describes the installation of the latest version of the Open Service Request + Framework (OpenSRF), a major component of the Evergreen server-side software, on + Ubuntu or Debian + systems. Evergreen software is integrated with and depends on the OpenSRF software + system. + Follow the steps outlined here and run the specified tests to ensure that OpenSRF is + properly installed and configured. Do not + continue with any further Evergreen installation steps + until you have verified that OpenSRF has been successfully installed and tested. + + The following steps have been tested on the x86 (32-bit) architecture of + Debian Squeeze (6.0), + Ubuntu Lucid Lynx (10.04), and on + Fedora 13 and + Fedora 14. + In the following instructions, you are asked to perform certain steps as + either the root user, the + opensrf user, or the + postgres user. + + + Debian -- To become the + root user, issue the command + su - and enter the password of the + root user. + + + Ubuntu -- To become the + root user, issue the command + sudo su - and enter the password of the + root user. + + + To switch from the root user to a + different user, issue the command su - USERNAME. For example, to + switch from the root user to the + opensrf user, issue the command + su - opensrf. Once you have become a non-root user, to become + the root user again, simply issue the command + exit. + + + + Add New <systemitem class="username">opensrf</systemitem> User + As the root user, add the + opensrf user to the system. + In the following example, the default shell for the + opensrf user is automatically set + to /bin/bash to inherit a reasonable environment: + + + # as the root user: + useradd -m -s /bin/bash opensrf + passwd opensrf + + + + Download and Unpack Latest OpenSRF Version + + OpenSRF + download + + The latest version of OpenSRF can be found here: + . + As the opensrf user, change to + the directory /home/opensrf then download + and extract OpenSRF. The new subdirectory + /home/opensrf/OpenSRF-1.6.3 will be created: + + + # as the opensrf user: + cd /home/opensrf + wget http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz + tar zxf OpenSRF-1.6.3.tar.gz + + + + Install Prerequisites to Build OpenSRF + In this section you will install and configure a set of prerequisites that will be + used to build OpenSRF. In a following step you will actually build the OpenSRF software + using the make utility. + As the root user, enter the commands show + below to build the prerequisites from the software distribution that you just downloaded + and unpacked. Remember to replace [DISTRIBUTION] in the following + example with the keyword corresponding to the name of one of the + Linux distributions listed in the + distribution keywords table . + For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would + enter this command: make -f src/extras/Makefile.install ubuntu-lucid . + + + # as the root user: + cd /home/opensrf/OpenSRF-1.6.3 + make -f src/extras/Makefile.install [DISTRIBUTION] + + + + Keyword Targets for OpenSRF <application>"make"</application> Command + + + + + + Keyword + Linux Version + + + + + debian-squeeze + Debian "Squeeze" (6.0) + + + debian-etch + Debian "Etch" (4.0) + + + debian-lenny + Debian "Lenny" (5.0) + + + ubuntu-hardy + Ubuntu "Hardy Heron" (8.04) + + + ubuntu-karmic + Ubuntu "Karmic Koala" (9.10) + + + ubuntu-lucid + Ubuntu "Lucid Lynx" (10.04) + + + fedora13 + Fedora "Goddard" (13) + + + fedora13 + Fedora "Laughlin" (14) + + + centos + CentOS 5 + + + rhel + Red Hat Enterprise Linux 5 + + + gentoo + Gentoo + + + +
+ + Linux + Debian + + + Linux + Fedora + + + Linux + Ubuntu + + + Linux + CentOS + + + Linux + Red Hat + + + Linux + Gentoo + + This will install a number of packages on the system that are required by OpenSRF, + including some Perl modules from CPAN. You can say No to the initial + CPAN configuration prompt to allow it to automatically configure itself to download and + install Perl modules from CPAN. The CPAN installer will ask you a number of times whether + it should install prerequisite modules - say Yes. + + + Build OpenSRF + In this section you will configure, build and install the OpenSRF + components that support other Evergreen services. + + + Configure OpenSRF + + OpenSRF + configure + + As the opensrf + user, return to the new OpenSRF build directory and use the + configure utility to prepare for the next + step of compiling and linking the software. If you wish to + include support for Python and Java, add the configuration + options and + , respectively: + + + # as the opensrf user: + cd /home/opensrf/OpenSRF-1.6.3 + ./configure --prefix=/openils --sysconfdir=/openils/conf + make + + This step will take several minutes to complete. + + + Compile, Link and Install OpenSRF + As the root + user, return to the new OpenSRF build directory and use the + make utility to compile, link and install + OpenSRF: + + + # as the root user: + cd /home/opensrf/OpenSRF-1.6.3 + make install + + This step will take several minutes to complete. + + + Update the System Dynamic Library Path + You must update the system dynamic library path to force + your system to recognize the newly installed libraries. As the + root user, do this by + creating the new file + /etc/ld.so.conf.d/osrf.conf containing two + new library paths, then execute the command + ldconfig to automatically read the file and + modify the system dynamic library path: + + + # as the root user: + echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf + echo "/usr/local/lib >> /etc/ld.so.conf.d/osrf.conf + ldconfig + + + + Define Public and Private OpenSRF Domains + For security purposes, OpenSRF uses Jabber domains to separate services + into public and private realms. On a single-server system the easiest way to + define public and private OpenSRF domains is to define separate host names by + adding entries to the file /etc/hosts. + In the following steps we will use the example domains + public.localhost for the public + domain and private.localhost + for the private domain. In an upcoming step, you will configure two special + ejabberd users + to handle communications for these two domains. + As the root user, edit the file + /etc/hosts and add the following example domains: + + Jabber + + + + # as the root user: + 127.0.1.2 public.localhost public + 127.0.1.3 private.localhost private + + + + Change File Ownerships + Finally, as the root + user, change the ownership of all files installed in the + directory /openils to the + user opensrf: + + + # as the root user: + chown -R opensrf:opensrf /openils + + + + + + Stop the <systemitem class="service">ejabberd</systemitem> Service + + ejabberd + + Before continuing with configuration of ejabberd + you must stop that service. As the root user, + execute the following command to stop the service: + + + # as the root user: + /etc/init.d/ejabberd stop + + If ejabberd reports that it + is already stopped, there may have been a problem when it started back + in the installation step. If there are any remaining daemon processes such as + beam or + epmd + you may need to perform the following commands to kill them: + + + # as the root user: + epmd -kill + killall beam; killall beam.smp + rm /var/lib/ejabberd/* + echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd + + + + Edit the <systemitem class="service">ejabberd</systemitem> configuration + You must make several configuration changes for the + ejabberd service before + it is started again. + As the root user, edit the file + /etc/ejabberd/ejabberd.cfg and make the following changes: + + + Change the line: + {hosts, ["localhost"]}. + to instead read: + {hosts, ["localhost", "private.localhost", "public.localhost"]}. + + + + Change the line for older versions of + ejabberd: + {max_user_sessions, 10} + to instead read: + {max_user_sessions, 10000} + + Change the line for newer versions of + ejabberd: + {access, max_user_sessions, [{10, all}]} + to instead read: + {access, max_user_sessions, [{10000, all}]} + + + Change all three occurrences of: + max_stanza_size + to instead read: + 2000000 + + + Change both occurrences of: + maxrate + to instead read: + 500000 + + + Comment out the line: + {mod_offline, []} + by placing two % comment signs in front + so it instead reads: + %%{mod_offline, []} + + + + + Restart the <systemitem class="service">ejabberd</systemitem> service + As the root user, restart the + ejabberd service to test the + configuration changes and to register your users: + + + # as the root user: + /etc/init.d/ejabberd start + + + + Register <systemitem class="username">router</systemitem> and + <systemitem class="username">opensrf</systemitem> as + <systemitem class="service">ejabberd</systemitem> users + The two ejabberd users + router and + opensrf must be registered + and configured to manage OpenSRF router service and communications + for the two domains public.localhost and + private.localhost that you added to the file + /etc/hosts in a previous step + (see ). + The users include: + + + the router user, + to whom all requests to connect to an OpenSRF service will be + routed; + + + the opensrf user, + which clients use to connect to OpenSRF services (you may name + the user anything you like, but we use + opensrf in these examples) + + + As the root user, execute the + ejabberdctl utility as shown below to register and create passwords + for the users router and + opensrf on each domain (remember to replace + NEWPASSWORD with the appropriate password): + + + # as the root user: + # Note: the syntax for registering a user with ejabberdctl is: + # ejabberdctl register USER DOMAIN PASSWORD + ejabberdctl register router private.localhost NEWPASSWORD + ejabberdctl register router public.localhost NEWPASSWORD + ejabberdctl register opensrf private.localhost NEWPASSWORD + ejabberdctl register opensrf public.localhost NEWPASSWORD + + The users router and + opensrf and their respective passwords + will be used again in when + we modify the OpenSRF configuration file + /openils/conf/opensrf_core.xml . + + + There appears to be a problem with ejabberdctl in + that it does not escape input correctly, so a password like + '0P3N$SRF' will be created as '0P3N'. + A bug against ejabberd has been filed. To register a password using + ejabberdctl with special shell characters until such + time as that bug is resolved, the workaround is to specify a + double-escaped character at the command line, for example, + '0P3N\\\\$RF' . + + + + Create OpenSRF configuration files + As the opensrf user, + execute the following commands to create the new configuration files + /openils/conf/opensrf_core.xml and + /openils/conf/opensrf.xml from the example templates: + + + # as the opensrf user: + cd /openils/conf + cp opensrf.xml.example opensrf.xml + cp opensrf_core.xml.example opensrf_core.xml + + + + Update usernames and passwords in the OpenSRF configuration file + As the opensrf user, edit the + OpenSRF configuration file /openils/conf/opensrf_core.xml + and update the usernames and passwords to match the values shown in the + following table. The left-hand side of + shows common XPath + syntax to indicate the approximate position within the XML file that needs + changes. The right-hand side of the table shows the replacement values: + + + Sample XPath syntax for editing 'opensrf_core.xml' + + + + + + XPath location + Value + + + + + /config/opensrf/username + + opensrf + + + + /config/opensrf/passwd + private.localhost + password for + opensrf user + + + + /config/gateway/username + + opensrf + + + + /config/gateway/passwd + public.localhost + password for + opensrf user + + + + /config/routers/router/transport/username, + first entry where server == public.localhost + + router + + + + /config/routers/router/transport/password, + first entry where server == public.localhost + public.localhost + password for + router user + + + + /config/routers/router/transport/username, + second entry where server == private.localhost + + router + + + + /config/routers/router/transport/password, + second entry where server == private.localhost + private.localhost + password for + router user + + + + +
+ You may also need to modify the file to specify the domains from which + OpenSRF will accept connections, + and to which it will make connections. + If you are installing OpenSRF on a single server + and using the private.localhost and + public.localhost domains, + these will already be set to the correct values. Otherwise, search and replace + to match values for your own systems. + + + Set the location of the persistent database + As the opensrf user, edit the + file /openils/conf/opensrf.xml, then find and verify that + the element dbfile (near the end of the file) is set to the + location of the persistent database. If necessary, change the default line: + /openils/var/persist.db + to instead read: + /tmp/persist.db + Following is a sample modification of that portion of the file: + + + + /tmp/persist.db + + +]]> + + + Create configuration files for users needing <command>srfsh</command> + In this section you will set up a special configuration file for each user + who will need to run the srfsh (pronounced surf + shell) utility. + + srfsh + + The software installation will automatically create the utility + srfsh, a command line diagnostic tool for testing and + interacting with OpenSRF. It will be used + in a future step to complete and test the Evergreen installation. See + for further information. + As the root user, copy the + sample configuration file /openils/conf/srfsh.xml.example + to the home directory of each user who will use srfsh. + For instance, do the following for the + opensrf user: + + + # as the root user: + cp /openils/conf/srfsh.xml.example /home/opensrf/.srfsh.xml + + Edit each user's file ~/.srfsh.xml and make the + following changes: + + + Modify domain to be the router hostname + (following our domain examples, + private.localhost will give + srfsh access to all OpenSRF services, while + public.localhost + will only allow access to those OpenSRF services that are + publicly exposed). + + + Modify username and + password to match the + opensrf Jabber user for the chosen + domain + + + Modify logfile to be the full path for + a log file to which the user has write access + + + Modify loglevel as needed for testing + + + Change the owner of the file to match the owner of the + home directory + + + Following is a sample of the file: + + + + +router +private.localhost +opensrf +SOMEPASSWORD +5222 +/tmp/srfsh.log + +4 + +]]> + + + Modify the environmental variable <envar>PATH</envar> for the + <systemitem class="username">opensrf</systemitem> user + As the opensrf user, modify the + environmental variable PATH by adding a new file path to the + opensrf user's shell configuration + file ~/.bashrc: + + + # as the opensrf user: + echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc + + + + Start OpenSRF + As the root user, start the + ejabberd and + memcached services: + + + # as the root user: + /etc/init.d/ejabberd start + /etc/init.d/memcached start + + Then as the opensrf user, + start OpenSRF as follows: + + + # as the opensrf user: + osrf_ctl.sh -l -a start_all + + The flag forces Evergreen to use + localhost (your current system) + as the hostname. The flag starts the + OpenSRF router , + Perl , and + C services. + + + You can also start Evergreen without the + flag, but the osrf_ctl.sh + utility must know the fully qualified domain name for the system + on which it will execute. That hostname was probably specified + in the configuration file opensrf.xml which + you configured in a previous step. + + + If you receive an error message similar to + osrf_ctl.sh: command not found, then your + environment variable PATH does not include the + directory /openils/bin. + As the opensrf user, + edit the configuration file ~/.bashrc and + add the following line: + export PATH=$PATH:/openils/bin + + + + + Test connections to OpenSRF + Once you have installed and started OpenSRF, as the + root user test your connection to + OpenSRF with the srfsh + utility and try to call the add method on the OpenSRF + math service: + + + # as the root user: + /openils/bin/srfsh + + srfsh# request opensrf.math add 2 2 + + Received Data: 4 + ------------------------------------ + Request Completed Successfully + Request Time in seconds: 0.007519 + ------------------------------------ + + For other srfsh commands, type in + help at the prompt. + + + Stop OpenSRF + After OpenSRF has started, you can stop it at any time by using the + osrf_ctl.sh again. As the + opensrf + user, stop OpenSRF as follows: + + + # as the opensrf user: + osrf_ctl.sh -l -a stop_all + + + +
+
+ Installing Evergreen 2.x On <systemitem class="osname">Ubuntu</systemitem> or + <systemitem class="osname">Debian</systemitem> + + Linux + Debian + + + Linux + Ubuntu + + This section outlines the installation process for the latest stable + version of Evergreen on Ubuntu or + Debian systems. See + for description of a similar + installation on a Fedora 14 system. + In this section you will download, unpack, install, configure and test the Evergreen + system, including the Evergreen server and the PostgreSQL database system. You will make several + configuration changes and adjustments to the software, including updates to configure the system + for your own locale, and some updates needed to work around a few known issues. + + 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. + In the following instructions, you are asked to perform certain steps as + either the root user, the + opensrf user, or the + postgres user. + + + Debian -- To become the + root user, issue the command + su - and enter the password of the + root user. + + + Ubuntu -- To become the + root user, issue the command + sudo su - and enter the password of the + root user. + + + To switch from the root user to a + different user, issue the command su - USERNAME. For example, to + switch from the root user to the + opensrf user, issue the command + su - opensrf. Once you have become a non-root user, to become the + root user again, simply issue the command + exit. + + + + Install OpenSRF + Evergreen software is integrated with and depends on the Open Service + Request Framework (OpenSRF) software system. For further information on + installing, configuring and testing OpenSRF, see + . + Follow the steps outlined in that section and run the specified tests to + ensure that OpenSRF is properly installed and configured. Do + not continue with + any further Evergreen installation steps until you have verified that OpenSRF + has been successfully installed and tested. + + + Download and Unpack Latest Evergreen Version + The latest version of Evergreen can be found here: + . + As the opensrf user, change to + the directory /home/opensrf then download + and extract Evergreen. The new subdirectory + /home/opensrf/Evergreen-ILS-2.0.4 + will be created: + + + # as the opensrf user: + cd /home/opensrf + wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz + tar zxf Evergreen-ILS-2.0.4.tar.gz + + + + Install Prerequisites to Build Evergreen + In this section you will install and configure a set of prerequisites that will be + used later in and + to build the Evergreen software + using the make utility. + As the root user, enter the commands show + below to build the prerequisites from the software distribution that you just downloaded + and unpacked. Remember to replace [DISTRIBUTION] in the following + example with the keyword corresponding to the name of one of the + Linux distributions listed in the following + distribution list. + For example, to install the prerequisites for Ubuntu version 10.05 (Lucid Lynx) you would + enter this command: make -f Open-ILS/src/extras/Makefile.install + ubuntu-lucid. + + + # as the root user: + cd /home/opensrf/Evergreen-ILS-2.0.4 + make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION] + + + + (OPTIONAL) Install the PostgreSQL Server + + databases + PostgreSQL + + Since the PostgreSQL server is usually a standalone server in multi-server + production systems, the prerequisite installer Makefile in the previous section + (see ) + does not automatically install PostgreSQL. You must install the PostgreSQL server + yourself, either on the same system as Evergreen itself or on another system. + If your PostgreSQL server is on a different system, just skip this step. + If your PostgreSQL server will be on the same system as your Evergreen + software, you can install the required PostgreSQL server packages as described + in , or you can visit the official + web site http://www.postgresql.org + for more information. + + PostgreSQL version 8.4 is the minimum supported version to work + with Evergreen 2.0. If you have an older version of PostgreSQL, + you should upgrade before installing Evergreen. To find your current version + of PostgreSQL, as the postgres + user execute the command psql, then type + SELECT version(); to get detailed information + about your version of PostgreSQL. + + + + Install Perl Modules on PostgreSQL Server + If PostgreSQL is running on the same system as your Evergreen software, + then the Perl modules will automatically be available. Just skip this step. + Otherwise, continue if your PostgreSQL server is running on another system + and install several Perl modules there. As the + root user, ensure the gcc compiler + is installed, then install the following Perl modules: + + + aptitude install gcc libxml-libxml-perl libxml-libxslt-perl + perl -MCPAN -e shell + cpan> Business::ISBN + cpan> install JSON::XS + cpan> Library::CallNumber::LC + cpan> install MARC::Record + cpan> install MARC::File::XML + cpan> cpan UUID::Tiny + + For more information on installing Perl Modules vist the official + CPAN site. + + Perl + CPAN + + + + Update the System Dynamic Library Path + You must update the system dynamic library path to force your system to recognize + the newly installed libraries. As the root user, + do this by creating the new file /etc/ld.so.conf.d/osrf.conf + containing two new library paths, then run the command ldconfig to + automatically read the file and modify the system dynamic library path: + + + # as the root user: + echo "/usr/local/lib" > /etc/ld.so.conf.d/osrf.conf + echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf + ldconfig + + + + Restart the PostgreSQL Server + If PostgreSQL is running on the same system as the rest of Evergreen, as + the root user you must restart + PostgreSQL to re-read the new library paths just configured. If PostgreSQL is + running on another system, you may skip this step. + As the opensrf user, + execute the following command (remember to replace + PGSQL_VERSION with your installed PostgreSQL version, + for example 8.4): + + + # as the opensrf user: + /etc/init.d/postgresql-PGSQL_VERSION restart + + + + Configure Evergreen + In this step you will use the configure and + make utilities to configure Evergreen so it can be compiled + and linked later in . + As the opensrf user, return to + the Evergreen build directory and execute these commands: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-2.0.4 + ./configure --prefix=/openils --sysconfdir=/openils/conf + make + + + + Compile, Link and Install Evergreen + In this step you will actually compile, link and install Evergreen and the + default Evergreen Staff Client. + As the root user, return to the + Evergreen build directory and use the make utility as shown + below: + + + # as the root user: + cd /home/opensrf/Evergreen-ILS-2.0.4 + make STAFF_CLIENT_BUILD_ID=rel_2_0_4 install + + The Staff Client will also be automatically built, but you must remember + to set the variable STAFF_CLIENT_BUILD_ID to match the version of the + Staff Client you will use to connect to the Evergreen server. + The above commands will create a new subdirectory + /openils/var/web/xul/rel_2_0_4 + containing the Staff Client. + To complete the Staff Client installation, as the + root user execute the following commands to + create a symbolic link named server in the head of the Staff Client + directory /openils/var/web/xul that points to the + subdirectory /server of the new Staff Client + build: + + + # as the root user: + cd /openils/var/web/xul + ln -sf rel_2_0_4/server server + + + + Copy the OpenSRF Configuration Files + In this step you will replace some OpenSRF configuration files that you set up in + when you installed and + tested OpenSRF. + You must copy several example OpenSRF configuration files into place after first + creating backup copies for troubleshooting purposes, then change all the file ownerships + to opensrf. + As the root user, execute the following + commands: + + + # as the root user: + cd /openils/conf + cp opensrf.xml opensrf.xml.BAK + cp opensrf_core.xml opensrf_core.xml.BAK + cp opensrf.xml.example opensrf.xml + cp opensrf_core.xml.example opensrf_core.xml + cp oils_web.xml.example oils_web.xml + chown -R opensrf:opensrf /openils/ + + + + Create and Configure PostgreSQL Database + + databases + PostgreSQL + + In this step you will create the Evergreen database. In the commands + below, remember to adjust the path of the contrib + repository to match your PostgreSQL server + layout. For example, if you built PostgreSQL from source the path would be + /usr/local/share/contrib , and if you + installed the PostgreSQL 8.4 server packages on Ubuntu, + the path would be + /usr/share/postgresql/8.4/contrib/ . + + + Create and configure the database + As the postgres + user on the PostgreSQL system create the PostgreSQL database, + then set some internal paths: + + + # as the postgres user: + createdb evergreen -E UTF8 -T template0 + createlang plperl evergreen + createlang plperlu evergreen + createlang plpgsql evergreen + + Continue as the postgres + user and execute the SQL scripts as shown below (remember to adjust the + paths as needed, where PGSQL_VERSION is + your installed PostgreSQL version, for example + "8.4"). + + + # as the postgres user: + psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen + psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen + psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen + + + + Create <systemitem class="username">evergreen</systemitem> + PostgreSQL user + As the postgres + user on the PostgreSQL system, create a new PostgreSQL user + named evergreen and + assign a password (remember to replace NEWPASSWORD + with an appropriate new password): + + + # as the postgres user: + createuser -P -s evergreen + + Enter password for new role: NEWPASSWORD + Enter it again: NEWPASSWORD + + + + Create database schema + In this step you will create the database schema and configure your + system with the corresponding database authentication details for the + evergreen database user that you just created in + . + As the root user, enter + the following commands and replace HOSTNAME, PORT, + PASSWORD and DATABASENAME with appropriate + values: + + + # as the root user: + cd /home/opensrf/Evergreen-ILS-2.0.4 + perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ + --service all --create-schema --create-offline \ + --hostname HOSTNAME --port PORT \ + --user evergreen --password PASSWORD \ + --database DATABASENAME --admin-user ADMIN-USER \ + --admin-pass ADMIN-PASSWORD + + On most systems, HOSTNAME will be + localhost and + PORT will be 5432. + Of course, values for PASSWORD and + DATABASENAME must match the values you used in + . + The and options will + specify the Evergreen administrator account's username and password. This was + changed for security reasons, it was previously admin/open-ils + As the command executes, you may see warnings similar to: + ERROR: schema SOMENAME does not exist (in fact, + you may see one warning per schema) but they can be safely ignored. + If you are entering the above command on a single line, do not + include the \ (backslash) characters. If you are using + the bash shell, 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. + + + + + Configure the Apache web server + + web server + Apache + + In this step you will configure the Apache web server to support Evergreen + software. + First, you must enable some built-in Apache modules and install some + additional Apache configuration files. Then you will create a new Security + Certificate. Finally, you must make several changes to the Apache configuration + file. + + + Enable the required Apache Modules + As the root + user, enable some modules in the Apache server, then copy the + new configuration files to the Apache server directories: + + Apache modules + + + + # as the root user: + a2enmod ssl # enable mod_ssl + a2enmod rewrite # enable mod_rewrite + a2enmod expires # enable mod_expires + + As the commands execute, you may see warnings similar to: + Module SOMEMODULE already enabled but you can + safely ignore them. + + + Copy Apache configuration files + You must copy the Apache configuration files from the + Evergreen installation directory to the Apache directory. As the + root user, perform the + following commands: + + + # as the root user: + cd /home/opensrf/Evergreen-ILS-2.0.4 + 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/ + + + + Create a Security Certificate + In this step you will create a new Security Certificate (SSL Key) + for the Apache server using the openssl command. For a + public production server you must configure or purchase a signed SSL + certificate, but for now you can just use a self-signed certificate and + accept the warnings in the Staff Client and browser during testing and + development. As the root user, + perform the following commands: + + + # as the root user: + mkdir /etc/apache2/ssl + cd /etc/apache2/ssl + openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key + + You will be prompted for several items of information; enter + the appropriate information for each item. The new files + server.crt and server.key will + be created in the directory + /etc/apache2/ssl . + This step generates a self-signed SSL certificate. You must install + a proper SSL certificate for a public production system to avoid warning + messages when users login to their account through the OPAC or when staff + login through the Staff Client. For further information on + installing a proper SSL certificate, see + . + + + Update Apache configuration files + You must make several changes to an Apache configuration file. + As the root user + edit the file /etc/apache2/sites-available/eg.conf + and make the following changes: + + + In the section + <Directory "/openils/var/cgi-bin"> + replace the line: + Allow from 10.0.0.0/8 + with the line: + Allow from all + This change allows access to your configuration + CGI scripts from any workstation on any network. This is + only a temporary change to expedite testing and should be + removed after you have finished and successfully tested + the Evergreen installation. See + + for further details on removing this change after the + Evergreen installation is complete. + + + + Comment out the line: + Listen 443 + since it conflicts with the same declaration in + the configuration file: + /etc/apache2/ports.conf. + + + The following updates are needed to allow the logs + to function properly, but it may break other Apache + applications on your server: + Edit the Apache configuration file and + change the lines: + + export APACHE_RUN_USER=www-data + export APACHE_RUN_GROUP=www-data + + to instead read: + + + export APACHE_RUN_USER=opensrf + export APACHE_RUN_GROUP=opensrf + + + + As the + root user, + edit the Apache configuration file + /etc/apache2/apache2.conf and + modify the value for KeepAliveTimeout + and MaxKeepAliveRequests to match + the following: + + + KeepAliveTimeout 1 + MaxKeepAliveRequests 100 + + + + Further configuration changes to Apache may be + necessary for busy systems. These changes increase the + number of Apache server processes that are started to + support additional browser connections. + As the + root user, + edit the Apache configuration file + /etc/apache2/apache2.conf, locate + and modify the section related to prefork + configuration to suit the load on your + system: + + StartServers 20 + MinSpareServers 5 + MaxSpareServers 15 + MaxClients 150 + MaxRequestsPerChild 10000 + +]]> + + + + + Enable the Evergreen web site + Finally, you must enable the Evergreen web site. As the + root user, execute the + following Apache configuration commands to disable the default + It Works web page and enable the Evergreen + web site, and then restart the Apache server: + + + # as the root user: + # disable/enable web sites + a2dissite default + a2ensite eg.conf + # restart the server + /etc/init.d/apache2 reload + + + + + + Update the OpenSRF Configuration File + As the opensrf user, edit the + OpenSRF configuration file /openils/conf/opensrf_core.xml + to update the Jabber usernames and passwords, and to specify the domain from + which we will accept and to which we will 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. + The left-hand side of + shows common XPath syntax to indicate the approximate position within the XML + file that needs changes. The right-hand side of the table shows the replacement + values: + + + Sample XPath syntax for editing 'opensrf_core.xml' + + + + + + XPath location + Value + + + + + /config/opensrf/username + + opensrf + + + + /config/opensrf/passwd + private.localhost + password for + opensrf user + + + + /config/gateway/username + + opensrf + + + + /config/gateway/passwd + public.localhost + password for + opensrf user + + + + /config/routers/router/transport/username, + first entry where server == public.localhost + + router + + + + /config/routers/router/transport/password, + first entry where server == public.localhost + public.localhost + password for + router user + + + + /config/routers/router/transport/username, + second entry where server == private.localhost + + router + + + + /config/routers/router/transport/password, + second entry where server == private.localhost + private.localhost + password for + router user + + + + +
+ + + (OPTIONAL) Create Configuration Files for Users Needing <command>srfsh</command> + When OpenSRF was installed in , the + software installation automatically created a utility named srfsh (surf + shell). This is a command line diagnostic tool for testing and interacting with + OpenSRF. It will be used in a future step to complete and test the Evergreen installation. + Earlier in you also created a configuration + file ~/.srfsh.xml for each user that might need to use the utility. + See for further information. + + + Modify the OpenSRF Environment + In this step you will make some minor modifications to the OpenSRF environment: + + + As the opensrf user, + modify the shell configuration file ~/.bashrc for + user opensrf by adding a Perl + environmental variable, then execute the shell configuration file to load + the new variables into your current environment. + + + # as the opensrf user: + echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc + . ~/.bashrc + + In a multi-server environment, you must add any + modifications to ~/.bashrc to the top of the file + before the line [ -z "$PS1" ] && + return . This will allow headless (scripted) logins to load the + correct environment. + + + + + (OPTIONAL) Enable and Disable Language Localizations + You can 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. For further information, see + . + + +
+
+ Installing Evergreen 2.x On <systemitem class="osname">Fedora 13</systemitem> or + <systemitem class="osname">Fedora 14</systemitem> + + Linux + Fedora + + This section outlines the installation process for the latest stable version of + Evergreen on a Fedora 14 system. + See for description of a + similar installation on Ubuntu or + Debian systems. + In the following section you will download, unpack, install, configure and test the Evergreen + system, including the Evergreen server and the PostgreSQL database system. You will make several + configuration changes and adjustments to the software, including updates to configure the system + for your own locale, and some updates needed to work around a few known issues. + + 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. + + + Fedora -- To become the + root user, issue the command + su - and enter the password of the + root user. + + + To switch from the root user to a + different user, issue the command su - USERNAME. For example, to + switch from the root user to the + opensrf user, issue the command + su - opensrf. Once you have become a non-root user, to become the + root user again, simply issue the command + exit. + + + + Install OpenSRF + Evergreen software is integrated with and depends on the Open Service + Request Framework (OpenSRF) software system. For further information on + installing, configuring and testing OpenSRF, see + . + Follow the steps outlined in that section and run the specified tests to + ensure that OpenSRF is properly installed and configured. Do + not continue with + any further Evergreen installation steps until you have verified that OpenSRF + has been successfully installed and tested. + + + Download and Unpack Latest Evergreen Version + The latest version of Evergreen can be found here: + . + As the opensrf user, change to + the directory /home/opensrf then + download and extract Evergreen. The new subdirectory + /home/opensrf/Evergreen-ILS-2.0.4 + will be created: + + + # as the opensrf user: + cd /home/opensrf + wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz + tar zxf Evergreen-ILS-2.0.4.tar.gz + + + + Install Prerequisites to Build Evergreen + In this section you will install and configure a set of prerequisites that will be + used later in and + to build the Evergreen software + using the make utility. + As the root user, enter the commands show + below to build the prerequisites from the software distribution that you just downloaded + and unpacked. Remember to replace [DISTRIBUTION] in the following + example with the keyword corresponding to the name of one of the + Linux distributions listed in the following + distribution list. For example, to install the prerequisites for + Fedora 13 or + Fedora 14, you would enter the command: + make -f Open-ILS/src/extras/Makefile.install fedora13. + + + # as the root user: + cd /home/opensrf/Evergreen-ILS-2.0.4 + make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION] + + + + (OPTIONAL) Install the PostgreSQL Server + + databases + PostgreSQL + + Since the PostgreSQL server is usually a standalone server in multi-server + production systems, the prerequisite installer Makefile in the previous section + (see ) + does not automatically install PostgreSQL. You must install the PostgreSQL server + yourself, either on the same system as Evergreen itself or on another system. + If your PostgreSQL server is on a different system, just skip this step. + If your PostgreSQL server will be on the same system as your Evergreen + software, you can install the required PostgreSQL server packages as described + in , or you can visit the official + web site http://www.postgresql.org + for more information. + + PostgreSQL version 8.4 is the minimum supported version to work + with Evergreen 2.0. If you have an older version of PostgreSQL, + you should upgrade before installing Evergreen. To find your current version + of PostgreSQL, as the postgres + user execute the command psql, then type + SELECT version(); to get detailed information + about your version of PostgreSQL. + + + + Install Perl Modules on PostgreSQL Server + If PostgreSQL is running on the same system as your Evergreen software, + then the Perl modules will automatically be available. Just skip this step. + Otherwise, continue if your PostgreSQL server is running on another system, + and install several Perl modules there. As the + root user, ensure the gcc compiler + is installed, then install the following Perl modules: + + + yum install gcc + perl -MCPAN -e shell + cpan> install JSON::XS + cpan> install MARC::Record + cpan> install MARC::File::XML + + For more information on installing Perl Modules vist the official + CPAN site. + + Perl + CPAN + + + + Configure Evergreen + In this step you will use the configure and + make utilities to configure Evergreen so it can be compiled + and linked later in . + As the opensrf user, return to + the Evergreen build directory and execute these commands: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-2.0.4 + ./configure --prefix=/openils --sysconfdir=/openils/conf + make + + + + Compile, Link and Install Evergreen + In this step you will actually compile, link and install Evergreen and the + default Evergreen Staff Client. + As the root user, return to the + Evergreen build directory and use the make utility as shown + below: + + + # as the root user: + cd /home/opensrf/Evergreen-ILS-2.0.4 + make STAFF_CLIENT_BUILD_ID=rel_2_0_4 install + + The Staff Client will also be automatically built, but you must remember + to set the variable STAFF_CLIENT_BUILD_ID to match the version of the + Staff Client you will use to connect to the Evergreen server. + The above commands will create a new subdirectory + /openils/var/web/xul/rel_2_0_4 + containing the Staff Client. + To complete the Staff Client installation, as the + root user execute the following commands + to create a symbolic link named server in the head of the + Staff Client directory /openils/var/web/xul + that points to the subdirectory /server + of the new Staff Client build: + + + # as the root user: + cd /openils/var/web/xul + ln -sf rel_2_0_4/server server + + + + Copy the OpenSRF Configuration Files + In this step you will replace some OpenSRF configuration files that you set up + earlier in when you installed + and tested OpenSRF. + You must copy several example OpenSRF configuration files into place after first + creating backup copies for troubleshooting purposes, then change all the file ownerships + to opensrf. + As the root user, execute the following + commands: + + + # as the root user: + cd /openils/conf + cp opensrf.xml opensrf.xml.BAK + cp opensrf_core.xml opensrf_core.xml.BAK + cp opensrf.xml.example opensrf.xml + cp opensrf_core.xml.example opensrf_core.xml + cp oils_web.xml.example oils_web.xml + chown -R opensrf:opensrf /openils/ + + + + Create and Configure PostgreSQL Database + + databases + PostgreSQL + + In this step you will create the Evergreen database. In the + commands below, remember to adjust the path of the + contrib repository to match your + PostgreSQL server layout. For example, if you built PostgreSQL from + source the path would be + /usr/local/share/contrib + , and if you installed the PostgreSQL 8.4 server packages on + Ubuntu, the path would be + /usr/share/postgresql/8.4/contrib/ . + + + Start the PostgreSQL service + As the root + user on the PostgreSQL system, initialize the PostgreSQL cluster + and start the PostgreSQL service: + + + # as the root user: + service initdb postgresql + /etc/init.d/postgresql start + + + + Create and configure the database + As the postgres + user on the PostgreSQL system create the PostgreSQL database, + then set some internal paths: + + + # as the postgres user: + createdb evergreen -E UTF8 -T template0 + createlang plperl evergreen + createlang plperlu evergreen + createlang plpgsql evergreen + + Continue as the postgres + user and execute the SQL scripts as shown below (remember to adjust the + paths as needed, where PGSQL_VERSION is + your installed PostgreSQL version, for example + "8.4"). + + + # as the postgres user: + psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen + psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen + psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen + + + + Create <systemitem class="username">evergreen</systemitem> + PostgreSQL user + As the postgres + user on the PostgreSQL system, create a new PostgreSQL user + named evergreen and + assign a password (remember to replace NEWPASSWORD + with an appropriate new password): + + + # as the postgres user: + createuser -P -s evergreen + + Enter password for new role: NEWPASSWORD + Enter it again: NEWPASSWORD + + + + Enable IPv4 and IPv6 connections + 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: + + + # as the root user: + + # IPv4 local connections: + host evergreen evergreen 127.0.0.1/32 md5 + # IPv6 local connections: + host evergreen evergreen ::1/128 md5 + + Then, as the root user, restart the PostgreSQL server to + make that configuration take effect: + + + # as the root user: + /etc/init.d/postgresql restart + + + + Create database schema + In this step you will create the database schema and configure your + system with the corresponding database authentication details for the + evergreen database user that you just created in + . + As the root user, enter + the following commands and replace HOSTNAME, PORT, + PASSWORD and DATABASENAME with appropriate + values: + + + # as the root user: + cd /home/opensrf/Evergreen-ILS-2.0.4 + perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ + --service all --create-schema --create-offline \ + --hostname HOSTNAME --port PORT \ + --user evergreen --password PASSWORD \ + --database DATABASENAME --admin-user ADMIN-USER \ + --admin-pass ADMIN-PASSWORD + + On most systems, HOSTNAME will be + localhost and + PORT will be 5432. + Of course, values for PASSWORD and + DATABASENAME must match the values you used in + . + The and options will + specify the Evergreen administrator account's username and password. This was + changed for security reasons, it was previously admin/open-ils + As the command executes, you may see warnings similar to: + ERROR: schema SOMENAME does not exist (in fact, + you may see one warning per schema) but they can be safely ignored. + If you are entering the above command on a single line, do not + include the \ (backslash) characters. If you are using + the bash shell, 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. + + + + + Configure the Apache web server + + web server + Apache + + In this step you will configure the Apache web server to support Evergreen + software. + First, you must install some additional Apache configuration files. Then you will + create a new Security Certificate. Finally, you must make several changes to Apache + configuration files. + + + Copy Apache configuration files + You must copy the Apache configuration files from the + Evergreen installation directory to the Apache directory. As the + root user, perform the + following commands: + + + # as the root user: + cd /home/opensrf/Evergreen-ILS-2.0.4 + 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/ + + + + Create a Security Certificate + In this step you will create a new Security Certificate (SSL Key) + for the Apache server using the openssl command. For a + public production server you must configure or purchase a signed SSL + certificate, but for now you can just use a self-signed certificate and + accept the warnings in the Staff Client and browser during testing and + development. As the root user, + perform the following commands: + + + # as the root user: + mkdir /etc/httpd/ssl + cd /etc/httpd/ssl + openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key + + You will be prompted for several items of information; enter + the appropriate information for each item. The new files + server.crt and server.key will + be created in the directory + /etc/httpd/ssl . + This step generates a self-signed SSL certificate. You must install + a proper SSL certificate for a public production system to avoid warning + messages when users login to their account through the OPAC or when staff + login through the Staff Client. For further information on + installing a proper SSL certificate, see + . + + + Update Apache configuration files + You must make several changes to two Apache configuration files. + As the root + user, edit the file /etc/httpd/conf.d/eg.conf + and make the following changes: + + + Change all instances of apache2 + to httpd . + + + In the section + <Directory "/openils/var/cgi-bin"> + replace the line: + Allow from 10.0.0.0/8 + with the line: + Allow from all + This change allows access to your configuration + CGI scripts from any workstation on any network. This is + only a temporary change to expedite testing and should be + removed after you have finished and successfully tested + the Evergreen installation. See + + for further details on removing this change after the + Evergreen installation is complete. + + + + Comment out the line: + Listen 443 + since it conflicts with the same declaration in + the configuration file: + /etc/httpd/conf.d/ssl.conf. + + + + As the root user, edit the + Apache configuration file /etc/httpd/conf.d/httpd.conf + and make the following changes: + + + Change User apache to + User opensrf + + Change KeepAlive to + On + + Change KeepAliveTimeout to + 1 + + + + + + Update the System Dynamic Library Path + You must update the system dynamic library path to force your + system to recognize the library dbdpgsql.so. As the + root user, do this by creating + the new file /etc/ld.so.conf.d/eg.conf containing two + new library paths, then run the command ldconfig to + automatically read the file and modify the system dynamic library + path: + + + # as the root user: + echo "/usr/lib/dbd" > /etc/ld.so.conf.d/eg.conf + echo "/usr/lib64/dbd/" >> /etc/ld.so.conf.d/eg.conf + ldconfig + + + + Update the OpenSRF Configuration File + As the opensrf user, edit the + OpenSRF configuration file /openils/conf/opensrf_core.xml + and update the Jabber usernames and passwords, and specify the domain from + which we will accept and to which we will 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. + See the table + for examples of the XPath syntax you will find in this XML file. The syntax + indicates the approximate position within the file that needs changes. + + + Modify the OpenSRF Environment + In this step you will make some minor modifications to the OpenSRF environment: + + + As the opensrf user, + modify the shell configuration file ~/.bashrc for + user opensrf by adding a Perl + environmental variable, then execute the shell configuration file to load + the new variables into your current environment: + + + # as the opensrf user: + echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc + . ~/.bashrc + + In a multi-server environment, you must add any + modifications to ~/.bashrc to the top of the file + before the line [ -z "$PS1" ] && + return . This will allow headless (scripted) logins to load the + correct environment. + + + + + Configuring Fedora Security + 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. + + + Disabling the Fedora firewall + To disable the Fedora + firewall until your next reboot, issue the + following command as the root user: + + + # as the root user: + /etc/init.d/iptables stop + + To disable the Fedora + firewall permanently, issue the following + command as the root user: + + + # as the root user: + chkconfig iptables off + + This change will take effect when you reboot your system. + + + Disabling the SELinux policies + To disable the SELinux policies until your next reboot, issue + the following command as the root user: + + + # as the root user: + /usr/sbin/setenforce 0 + + To disable the SELinux policies permanently, as the root user + edit the file /etc/sysconfig/selinux and make the + following change: + + + # as the root user: + SELINUX=permissive + + This change will take effect when you reboot your system. + + + + +
+
+ Starting Evergreen + In this section you will learn how to start the Evergreen services. + For completeness, instructions for stopping Evergreen can be found later in + . + + + As the root user, + start the ejabberd, + memcached, and + PostgreSQL services + (if they aren't already running) as follows: + + + # as the root user: + /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: + + + # as the root user: + chkconfig --levels 2345 ejabberd on + chkconfig --levels 2345 memcached on + chkconfig --levels 2345 postgresql on + + + + As the opensrf user, + start the OpenSRF router , + Perl, and C services. The flag in + the following command is only necessary if you want to force Evergreen to + treat the hostname as 'localhost'. You should not + use the '-l' flag if you configured opensrf.xml + using the real hostname of your machine as returned by: perl + -ENet::Domain 'print Net::Domain::hostfqdn() . “\n”;' . + As the opensrf user, execute this command: + + + # as the opensrf user: + osrf_ctl.sh -l -a start_all + + + + If you receive an error message similar to + osrf_ctl.sh: command not found, then your + environment variable PATH does not include the + directory /openils/bin. + As the opensrf user, + edit the configuration file ~/.bashrc and + add the following line: + export PATH=$PATH:/openils/bin + + + If you receive an error message similar to Can't + locate OpenSRF/System.pm in @INC ... BEGIN failed--compilation + aborted, then your environment variable + PERL5LIB does not include the + directory /openils/lib/perl5. + 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 + + + + + In this step you will generate the Web files needed by the Staff Client + and catalog, as well as update the proximity of locations in the Organizational + Unit tree (which allows Holds to work properly). + You must do this the first time you start Evergreen and after making any + changes to the library hierarchy. + As the opensrf user, execute the + following command and review the results as shown in this example: + + + # as the opensrf user: + cd /openils/bin + ./autogen.sh -c /openils/conf/opensrf_core.xml -u + + Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml' + Updating fieldmapper + Updating web_fieldmapper + Updating OrgTree + removing OrgTree from the cache for locale hy-AM... + removing OrgTree from the cache for locale cs-CZ... + removing OrgTree from the cache for locale en-CA... + removing OrgTree from the cache for locale en-US... + removing OrgTree from the cache for locale fr-CA... + removing OrgTree from the cache for locale ru-RU... + Updating OrgTree HTML + Updating locales selection HTML + Updating Search Groups + Refreshing proximity of org units + Successfully updated the organization proximity + Done + + + + As the root user, restart the + Apache Web server: + + + # as the root user: + /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 into the OPAC or Staff + Client until the Apache Web server has been restarted. + + +
+
+ Testing Your Evergreen Installation + This section describes several simple tests you can perform to verify that the Evergreen + server-side software has been installed and configured properly and is running as + expected. + + Testing Connections to Evergreen + Once you have installed and started Evergreen, test your connection to Evergreen. Start the + srfsh application and try logging onto the Evergreen server using the default + administrator username and password. Following is sample output generated by executing + srfsh after a successful Evergreen installation. For help with + srfsh commands, type help at the prompt. + As the opensrf user, + execute the following command and review the results as shown in this example to test + your Evergreen connection: + + + # as the opensrf user: + /openils/bin/srfsh + + srfsh% login admin open-ils + 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, try the following: + + + As the opensrf user, run the + utility settings-tester.pl to review your Evergreen + installation for any system configuration problems: + + + # as the opensrf user: + cd /home/opensrf + ./Evergreen-ILS-2.0.4/Open-ILS/src/support-scripts/settings-tester.pl + + 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 in + . + + + 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. + + + + + Testing the Staff Client on Linux + In this section you will confirm that a basic login on the Staff Client works + properly. + Run the Evergreen Staff Client on your Fedora + system by using the application + XULRunner (installed automatically and by default with Firefox + version 3.0 and later on Ubuntu and Debian distributions). + As the root user, start the Staff Client + as shown: + + + # as the root user: + xulrunner /home/opensrf/Evergreen-ILS-2.0.4/Open-ILS/xul/staff_client/build/application.ini + + A login screen for the Staff Client similar to this should appear: + + Logging into the Staff Client + + + + + First, add the name of your Evergreen server to the field + Hostname in the Server section. You will + probably want to use 127.0.0.1. After adding the server + name, click Re-Test Server. You should now see the + messages 200:OK in the fields Status and + Version. + Because this is the initial run of the Staff Client, you will see a warning in the + upper-right saying: Not yet configured for the specified + server. To continue, you must assign a workstation name. + Try to log into the Staff Client with the admin username and password you created + during installation. If the login is successful, you will see the following + screen: + + Logging into the Staff Client + + + + + Otherwise, you may need to click 'Add SSL Exception' in the + main window. You should see a popup window titled Add Security Exception: + + Adding an SSL Exception in the Staff Client + + + + + Click 'Get Certificate', then click 'Confirm + Security Exception', then click 'Re-Test Server' in the + main window and try to log in again. + + + Testing the Apache Web Server + In this section you will test the Apache configuration file(s), then restart the + Apache web server. + As the root user, execute the following + commands. The use of restart will force the new Evergreen + modules to be reloaded even if the Apache server is already running. + Any problems found with your configuration files should be displayed: + + + # as the root user: + /etc/init.d/httpd configtest && /etc/init.d/httpd restart + + + + Stopping Evergreen + In you learned how to start the + Evergreen services. For completeness, following are instructions for stopping the + Evergreen services. + As the opensrf user, stop all Evergreen + services by using the following command: + + + # as the opensrf user + # stop the server; use "-l" to force hostname to be "localhost" + osrf_ctl.sh -l -a stop_all + + You can also stop Evergreen services without the + flag, but the osrf_ctl.sh utility must know the + fully qualified domain name for the system on which it will execute. That hostname may + have been specified in the configuration file opensrf.xml, which + you configured in a previous step. + +
+
+ Post-Installation Chores + There are several additional steps you may need to complete after Evergreen has been + successfully installed and tested. Some steps may not be needed (e.g., setting up support for + Reports). +
+ Remove temporary Apache configuration changes + You modified the Apache configuration file + /etc/apache2/sites-available/eg.conf in an earlier step as a + temporary measure to expedite testing (see + for further information). + Those changes must now be reversed in order to deny unwanted access to your + CGI scripts from users on other public networks. + + + This temporary network update was done to expedite + testing. You must correct + this for a public production system. + + + As the root user, edit the configuration + file again and comment out the line Allow from all and uncomment the + line Allow from 10.0.0.0/8, then change it to match your network + address scheme. +
+
+ Configure a permanent SSL key + You used the command openssl in an earlier step to + temporarily create a new SSL key for the Apache server (see + for further + information). This self-signed security certificate was adequate during + testing and development, but will continue to generate warnings in the Staff + Client and browser. For a public production server you should configure or + purchase a signed SSL certificate. + There are several open source software solutions that provide schemes to + generate and maintain public key security certificates for your library + system. Some popular projects are listed below; please review them for + background information on why you need such a system and how you can provide + it: + + + http://www.openca.org/projects/openca/ + + + http://sourceforge.net/projects/ejbca/ + + + http://pki.fedoraproject.org + + + + + The temporary SSL key was only created to expedite + testing. You should install a proper SSL certificate for a public + production system. + + +
+
+ (OPTIONAL) IP-Redirection + By default, Evergreen is configured so searching the OPAC always starts in the + top-level (regional) library rather than in a second-level (branch) library. Instead, + you can use "IP-Redirection" to change the default OPAC search location to use the IP + address range assigned to the second-level library where the seach originates. You must + configure these IP ranges by creating the configuration file + /openils/conf/lib_ips.txt and modifying the Apache startup script + /etc/apache2/startup.pl. + First, copy the sample file + /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/examples/lib_ips.txt.example + to /openils/conf/lib_ips.txt. The example file contains the single + line: "MY-LIB 127.0.0.1 127.0.0.254". You must modify the file to use + the IP address ranges for your library system. Add new lines to represent the IP address + range for each branch library. Replace the values for MY-LIB with the + values for each branch library found in the table + actor.org_unit. + Finally, modify the Apache startup script + /etc/apache2/startup.pl by uncommenting two lines as shown, then + restarting the Apache server: + +# - e.g. LIB123 10.0.0.1 10.0.0.254 +use OpenILS::WWW::Redirect qw(/openils/conf/opensrf_core.xml); +OpenILS::WWW::Redirect->parse_ips_file('/openils/conf/lib_ips.txt'); +]]> +
+
+ (OPTIONAL) Set Up Support For Reports + Evergreen reports are extremely powerful but require some simple configuration. + See for information on starting and + stopping the Reporter daemon processes. +
+
+
+ -- 2.43.2