From: Steve Sheppard Date: Thu, 18 Nov 2010 22:35:45 +0000 (-0500) Subject: more updates to bring into line with a real installation attempt; X-Git-Tag: sprint4-merge-nov22~4203^2~284 X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=fe1224c952cfe1a54875f916482fb2158908ddbe;p=working%2FEvergreen.git more updates to bring into line with a real installation attempt; add links to previous steps where mentioned; --- diff --git a/1.6/admin/serversideinstallation.xml b/1.6/admin/serversideinstallation.xml index 074da346c6..7ea420ee05 100644 --- a/1.6/admin/serversideinstallation.xml +++ b/1.6/admin/serversideinstallation.xml @@ -1,1836 +1,1842 @@ - - - - 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", or - "VirtualPC" 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 - - - - - 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.4.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) and x86-64 (64-bit) - platforms. OpenSRF 1.4.0 has been tested on Debian Etch - (4.0), Debian Lenny (5.0) and - Ubuntu Lucid Lynx (10.04). - 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 the OpenSRF User - As the root user, add the - opensrf user to the system. The default shell for the new user is automatically - set to /bin/bash to inherit a reasonable environment: - - useradd -m -s /bin/bash opensrf - passwd opensrf - - - - Download and Unpack Latest OpenSRF Version - - OpenSRF - download - - As the opensrf user, change to - the directory /home/opensrf then download - and extract the latest version of OpenSRF. The latest version can be found here: - - - cd /home/opensrf/OpenSRF-1.4.0 - wget http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz - tar zxf OpenSRF-1.4.0.tar.gz - - The new directory - /home/opensrf/OpenSRF-1.4.0 will be created. - - - 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 following - 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 . - - cd /home/opensrf/OpenSRF-1.4.0 - make -f src/extras/Makefile.install [DISTRIBUTION] - - - Keyword Targets for OpenSRF <application>"make"</application> Command - - - - - - Keyword - Linux Version - - - - - 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) - - - centos - Centos - - - rhel - RHEL - - - gentoo - 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 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: - - cd /home/opensrf/OpenSRF-1.4.0 - ./configure --prefix=/openils --sysconfdir=/openils/conf - make - - - - Compile, Link and Install OpenSRF - As the root - user, return to the OpenSRF build directory and use the - make utility to compile, link and install - OpenSRF: - - cd /home/opensrf/OpenSRF-1.4.0 - make install - - - - 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: - - echo "/openils/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 - - - 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: - - 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: - - /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: - - 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: - {hosts, ["localhost", "private.localhost", "public.localhost"]}. - - - Change the line: - {max_user_sessions, 10}. to: - {max_user_sessions, 10000}. - If the line looks something like this: - {access, max_user_sessions, [{10, all}]}. - then change it to: - {access, max_user_sessions, [{10000, all}]} - - - Change all three occurrences of: max_stanza_size - to: 2000000. - - - Change both occurrences of: maxrate to: - 500000. - - - Comment out the line {mod_offline, []} - by placing two % comment signs in front. - - - - - 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: - - /etc/init.d/ejabberd start - - - - Register <systemitem class="username">router</systemitem> and - <systemitem class="username">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: - - - 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: - - # 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 - - Note that the users router and - opensrf and their respective passwords - will be used again in the file /openils/conf/opensrf_core.xml - in the next steps. - - - 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: - - 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 location of the persistent database - As the opensrf user, edit the - file /openils/conf/opensrf.xml, then find and modify the - element dbfile (near the end of the file) to set the - location of the persistent database: - - - - /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 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. - See for further information. - As the root user, copy the short - sample configuration file /openils/conf/srfsh.xml.example - to ~/.srfsh.xml (note the leading dot!), the home - directory of each user who will use srfsh. Finally, edit each - file ~/.srfsh.xml and make the following changes; when you - finish, remember to change the owner of the file to match the owner of the home - directory: - - - 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 - - - - - - -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: - - echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc - - - - Start OpenSRF - As the root user, start the - ejabberd and - memcached services: - - /etc/init.d/ejabberd start - /etc/init.d/memcached start - - As the opensrf user, - start OpenSRF as follows: - - osrf_ctl.sh -l -a start_all - - The flag forces Evergreen to use - localhost (your current system) - as the hostname. The flag starts the other - 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 using the srfsh - utility and trying to call the add method on the OpenSRF - math service: - - /openils/bin/srfsh - srfsh# - request opensrf.math add 2 2 - Received Data: 4 - ------------------------------------ - Request Completed Successfully - Request Time in seconds: 0.007519 - ------------------------------------ - srfsh# - - 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: - - osrf_ctl.sh -l -a stop_all - - - -
-
- Installing Evergreen 1.6.1.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. - 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 - As the opensrf user, download - and extract the latest version of Evergreen. The latest version can be found here: - - - wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz - tar zxf Evergreen-ILS-1.6.1.2.tar.gz - - The new directory - /home/opensrf/Evergreen-ILS-1.6.1.2 - will be created. - - - Install Prerequisites to Build Evergreen - In this section you will install and configure a set of prerequisites that - will be used to build Evergreen. In a following step you will actually 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 - keywords table . For example, - to install the prerequisites for Ubuntu version 9.10 (Karmic Koala) you would enter this - command: make -f Open-ILS/src/extras/Makefile.install ubuntu-karmic. - - cd /home/opensrf/Evergreen-ILS-1.6.1.2 - make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION] - - - Keyword Targets for Evergreen <application>"make"</application> Command - - - - - - Keyword - Linux Version - - - - - debian-etch - Debian "Etch" (4.0) - - - debian-lenny - Debian "Lenny" (5.0) - - - ubuntu-hardy - Ubuntu "Hardy Heron" (8.04) - - - ubuntu-intrepid - Ubuntu "Intrepid Ibex" (8.10) - - - ubuntu-karmic - Ubuntu "Karmic Koala" (9.10) - - - ubuntu-karmic - Ubuntu "Lucid Lynx" (10.04) - - - centos - Centos - - - rhel - RHEL - - - gentoo - Gentoo - - - -
- - - (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 step - 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. - For further information on manually installing PostgreSQL, visit the official - PostgreSQL Site. - If your PostgreSQL server will be on the same system as your Evergreen - software, then as the root user - install the required PostgreSQL server packages: - For Debian Lenny and - Ubuntu Hardy (8.04): - - make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_83 - - For Ubuntu Karmic (9.10) and - Ubuntu Lucid (10.04): - - make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_84 - - - PostgreSQL versions 8.3 or 8.4 are the recommended versions to work - with Evergreen 1.6. If you have an older version of PostgreSQL, you should - upgrade before installing Evergreen. To find the running version of - PostgreSQL, as the postgres - user, run the 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: - - # first, ensure the gcc compiler is installed: - apt-get install gcc - # then install the Perl modules: - 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 - - - - 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: - - 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, where - [PGSQL_VERSION] is your installed PostgreSQL version - (e.g. 8.3): - - /etc/init.d/postgresql-[PGSQL_VERSION] restart - - - - Configure Evergreen - As the opensrf user, return to - the Evergreen build directory and use the configure and - make utilities to configure Evergreen so it can be compiled - and linked in the next step: - - cd /home/opensrf/Evergreen-ILS-1.6.1.2 - ./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: - - cd /home/opensrf/Evergreen-ILS-1.6.1.2 - make STAFF_CLIENT_BUILD_ID=rel_1_6_1_2 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. For further information on manually - building the Staff Client, see - . - The above commands will create a new subdirectory - /openils/var/web/xul/rel_1_6_1_2 - containing the Staff Client. - To complete the Staff Client installation, - as the root user 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: - - cd /openils/var/web/xul - ln -sf rel_1_6_1_2/server server - - - - Copy the OpenSRF Configuration Files - As the root user, execute the - following commands to copy the example OpenSRF configuration files into place - after first creating backup copies of the old files for troubleshooting purposes. - These files replace the configuration files that you set up in a previous step - when you installed and tested OpenSRF. Finally, change the ownership on - the installed files to the opensrf 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; if you - installed the PostgreSQL 8.3 server packages on Ubuntu 8.04, - the path would be - /usr/share/postgresql/8.3/contrib/. - - - - Create and configure the database - - As the postgres - user on the PostgreSQL system create the PostgreSQL database, - then set some internal paths: - - createdb evergreen -E UTF8 -T template0 - createlang plperl evergreen - createlang plperlu evergreen - createlang plpgsql evergreen - - Continue as user postgres - and execute the SQL scripts as shown below, adjusting the paths as needed, where - [PGSQL_VERSION] is your installed PostgreSQL - version (e.g. 8.3). - - 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: - - createuser -P -s evergreen - Enter password for new role: MYNEWPASSWORD - Enter it again: MYNEWPASSWORD - - - - Create database schema - As the root - user, create the database schema and configure your system with - the corresponding database authentication details for the - evergreen database user that you created in - the previous step. - Enter the following commands and replace - HOSTNAME, PORT, PASSWORD and - DATABASENAME with appropriate - values: - - cd /home/opensrf/Evergreen-ILS-1.6.1.2 - perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ - --service all --create-schema --create-bootstrap --create-offline \ - --hostname HOSTNAME --port PORT \ - --user evergreen --password PASSWORD --database DATABASENAME - - 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 - previous step when you created the database and and set a password for the - evergreen user. - 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: - - 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: - - cd /home/opensrf/Evergreen-ILS-1.6.1.2 - 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 - You must 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: - - mkdir /etc/apache2/ssl - cd /etc/apache2/ssl - openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key - - - 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 getting 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 this line: - Allow from 10.0.0.0/8 - with this 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. - Note that Debian - users should not do this - since the conflict does not apply to that - operating system. - - - The following updates are needed to allow - the logs to function properly, but it may break - other Apache applications on your server: - For the Linux - distributions Ubuntu - Hardy or - Debian Etch, - as the root - user, edit the Apache configuration file - /etc/apache2/apache2.conf and - change the line User www-data - to User opensrf. - For the Linux - distributions Ubuntu - Karmic, - Ubuntu Lucid - or Debian Lenny, - as the root - user, edit the Apache configuration file - and change these 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 values 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: - - # 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 - - - - -
- - - Create Configuration Files for Users Needing <command>srfsh</command> - When OpenSRF was installed in a previous step (see - for further information), - 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. See - for further information. - - - Modify the OpenSRF Environment - 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. - - - - 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 . - - -
-
- Starting Evergreen - - - As the root - user, start the ejabberd and - memcached services as follows: - - /etc/init.d/ejabberd start - /etc/init.d/memcached start - - - - As the opensrf user, - start Evergreen as follows: - - osrf_ctl.sh -l -a start_all - - The flag forces Evergreen to use - localhost (your current system) - as the hostname. The flag starts the other - 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 calculate 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 commands: - - 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 - - - - As the root user, restart the - Apache Web server: - - /etc/init.d/apache2 restart - - - If the Apache Web server was running when you started the OpenSRF - services, you might not be able to successfully log 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. - Execute the following commands to test your Evergreen connection: - - /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: - - cd /home/opensrf - ./Evergreen-ILS-1.6.1.2/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. - - - -
-
- 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 - In a previous step, you used the command openssl to temporarily - create a new SSL key for the Apache server. This self-signed 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. - - - The temporary SSL key was only created to expedite - testing. You should install a proper SSL certificate for a public - production system. - - -
-
- Set Up Support For Reports - Evergreen reports are extremely powerful but require some simple configuration. - This section describes starting and stopping the Reporter daemon processes. - - - Starting the Reporter Daemon - Once the open-ils.reporter - process is running and enabled on the gateway, you can start the - Reporter daemon. That process periodically checks for requests for new - or scheduled reports, then starts them as required. - As the opensrf user, - start the Reporter daemon using the following command: - - cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/src/reporter - ./clark-kent.pl --daemon - - You can control how the clark-kent.pl utility behaves - by specifying any of several command-line options: - - : number of seconds - to sleep between checks for new reports to run; defaults to - 10 - : where to place - the lockfile for the process; defaults to - /tmp/reporter-LOCK - : number of - Reporter daemon processes to run; defaults to - 1 - : OpenSRF - bootstrap configuration file; defaults to - /openils/conf/opensrf_core.xml - - - - Stopping the Reporter Daemon - To stop the Reporter daemon, you must kill the process and remove - the lockfile. The daemon may have just a single associated process or - there may be several processes if the daemon was started with the optional - --concurrency switch. It will also have a lockfile - in the default location. - As the opensrf user, - execute the following shell commands: - - # find and kill the process ID number(s) - kill `ps wax | grep "Clark Kent" | grep -v grep | cut -b1-6` - # remove the lock file - rm /tmp/reporter-LOCK - - - -
-
-
- Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments - This section describes the installation of Evergreen software in so-called "virtualized" - software environments. Evergreen software runs as a native application on any of several - well-known x86 (32-bit) and x86-64 (64-bit) Linux - distributions including Ubuntu and - Debian but it does not run as a native application - on the Microsoft Windows operating system. - However, it is possible to execute Evergreen on a Windows - host system by running it within a virtual Linux-guest installation, which itself executes - on the Windows system. - The Linux environment is fully emulated and acts - (within limits) just as if it were executing on a real standalone system. - This technique of emulating a Linux environment on - a Windows host is a practical way to install and run an - Evergreen system if it is not possible to dedicate a physical machine solely as a - Linux host for Evergreen. This architecture is not - recommended for large scale systems since there are performance limitations to running Evergreen - in a virtualized environment. However, it is a reasonable architecture for smaller experimental - systems, as a proof of concept, or as a conference-room pilot. - - Installing Virtualization Software - As described above, Evergreen can be installed on top of an emulated - Linux environment. The - Linux environment, in turn, is installed - on top of a software application such as "VirtualBox", - "VMware" or "VirtualPC" which must - first be installed on the Windows system. This - section contains step-by-step examples that show installing popular virtualization - applications on a Windows host system. Following - this section are further descriptions of installing - Linux and Evergreen systems using that - virtualization software. - - Installing <application>"VirtualBox"</application> Virtualization Software - This section reviews installation of the - "VirtualBox" application on - WindowsXP Professional (SP2). - Download the latest edition of VirtualBox from their official website: - http://virtualbox.org - and follow the on screen instructions to install the software. - - - Installing VMware Virtualization Software - - virtualization software - VMware - - This section reviews installation of the - "VMware" application on - WindowsXP Professional (SP2). - Find and Download the free virtual machine software of from the VMware - official website: - http://downloads.vmware.com - and follow the on-screen instructions. - - - - Installing <systemitem class="osname">Linux</systemitem> / - Evergreen on Virtualization Software - After the virtualization software is installed and running, there are two ways to - continue with installing Linux and Evergreen - software in the new virtualized environment: - - - Download and install a prebuilt software image that contains a - working Linux / Evergreen system - (see for - details) - - - Manually install a Linux - guest system, then manually install Evergreen on it. - - - We review each method in the following sections. - - Download and install a prebuilt software image - You can download a prebuilt software image that, when installed with your - virtualization software, emulates a - Linux guest system containing a running - Evergreen distribution. The image is essentially a snapshot of a hard disk from - a fully configured, functional Linux - system with Evergreen already installed. - We recommend this approach if you wish to get Evergreen running quickly - with minimal attention to configuration. After reviewing only a few - configuration details you can have a working Evergreen system that integrates - smoothly with the rest of your network. See - for a list of prebuilt - software images that are currently available to download and install - DISCLAIMER: The following virtual images have been contributed by members - of the Evergreen community for the purposes of testing, evaluation, training, - and development. - - Linux / Evergreen Virtual Images - - - - - - - - Linux Version - Evergreen Version - Image - Comments - - - - - Debian lenny (5.0) - 1.6.0.1 - - download - - VirtualBox image - - - Ubuntu karmic koala (9.10) - 1.6.0.0 - - download - - VirtualBox image - - - -
- - VirtualBox Example - - virtualization software - VirtualBox - - - Start VirtualBox for the first time and select - FileVirtualBox Media - ManagerAdd - to locate the prebuilt software image just downloaded (the - example shows it was extracted from the original - zip file into a temporary directory - C:\temp). - - - After selecting the file, click Open to import it. - - - Then click OK to save the selection - and return to the VirtualBox Media Manager - - - Click New, then Next to continue - and create a new virtual machine (VM). - - - Create a new name for the VM and set the operating system - type, then click Next. - - - Set the memory size (at least 512Mb), - then click Next. - - - Edit the Virtual Hard Disk configuration settings; click - the radio boxes Boot Hard Disk and - Use existing hard disk - and ensure that the disk name Evergreen1601_DebianLenny.vmdk - is selected. Click Finish to finish the - setup. - - - Install the VirtualBox Guest - Additions (really a required upgrade to - VirtualBox) - - - Return to VirtualBox and see the summary of the VM just - created. Click Start to boot the new VM. - - - See the start of the Linux - boot sequence. Choose Debian Gnu/Linux, kernel - 2.6.26-2-686 from the startup menu and click - Enter to start - Linux and Evergreen. - After some delay you should see the command line prompt - debian-lenny login:. Log in with username - root and password evergreen - to continue. - - - - -
-
- + + + + 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", or + "VirtualPC" 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 + + + + + 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.4.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) and x86-64 (64-bit) + platforms. OpenSRF 1.4.0 has been tested on Debian Etch + (4.0), Debian Lenny (5.0) and + Ubuntu Lucid Lynx (10.04). + 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 the OpenSRF User + As the root user, add the + opensrf user to the system. The default shell for the new user is automatically + set to /bin/bash to inherit a reasonable environment: + + useradd -m -s /bin/bash opensrf + passwd opensrf + + + + Download and Unpack Latest OpenSRF Version + + OpenSRF + download + + As the opensrf user, change to + the directory /home/opensrf then download + and extract the latest version of OpenSRF. The latest version can be found here: + + + cd /home/opensrf/OpenSRF-1.4.0 + wget http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz + tar zxf OpenSRF-1.4.0.tar.gz + + The new directory + /home/opensrf/OpenSRF-1.4.0 will be created. + + + 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 following + 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 . + + cd /home/opensrf/OpenSRF-1.4.0 + make -f src/extras/Makefile.install [DISTRIBUTION] + + + Keyword Targets for OpenSRF <application>"make"</application> Command + + + + + + Keyword + Linux Version + + + + + 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) + + + centos + Centos + + + rhel + RHEL + + + gentoo + 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 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: + + cd /home/opensrf/OpenSRF-1.4.0 + ./configure --prefix=/openils --sysconfdir=/openils/conf + make + + + + Compile, Link and Install OpenSRF + As the root + user, return to the OpenSRF build directory and use the + make utility to compile, link and install + OpenSRF: + + cd /home/opensrf/OpenSRF-1.4.0 + make install + + + + 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: + + echo "/openils/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 + + + 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: + + 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: + + /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: + + 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: + {hosts, ["localhost", "private.localhost", "public.localhost"]}. + + + Change the line: + {max_user_sessions, 10}. to: + {max_user_sessions, 10000}. + If the line looks something like this: + {access, max_user_sessions, [{10, all}]}. + then change it to: + {access, max_user_sessions, [{10000, all}]} + + + Change all three occurrences of: max_stanza_size + to: 2000000. + + + Change both occurrences of: maxrate to: + 500000. + + + Comment out the line {mod_offline, []} + by placing two % comment signs in front. + + + + + 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: + + /etc/init.d/ejabberd start + + + + Register <systemitem class="username">router</systemitem> and + <systemitem class="username">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: + + # 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 + + Note that the users router and + opensrf and their respective passwords + will be used again in the file /openils/conf/opensrf_core.xml + in the next steps. + + + 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: + + 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 location of the persistent database + As the opensrf user, edit the + file /openils/conf/opensrf.xml, then find and modify the + element dbfile (near the end of the file) to set the + location of the persistent database: + + + + /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 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. + See for further information. + As the root user, copy the short + sample configuration file /openils/conf/srfsh.xml.example + to ~/.srfsh.xml (note the leading dot!), the home + directory of each user who will use srfsh. Finally, edit each + file ~/.srfsh.xml and make the following changes; when you + finish, remember to change the owner of the file to match the owner of the home + directory: + + + 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 + + + + + + +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: + + echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc + + + + Start OpenSRF + As the root user, start the + ejabberd and + memcached services: + + /etc/init.d/ejabberd start + /etc/init.d/memcached start + + As the opensrf user, + start OpenSRF as follows: + + osrf_ctl.sh -l -a start_all + + The flag forces Evergreen to use + localhost (your current system) + as the hostname. The flag starts the other + 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 using the srfsh + utility and trying to call the add method on the OpenSRF + math service: + + /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: + + osrf_ctl.sh -l -a stop_all + + + +
+
+ Installing Evergreen 1.6.1.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. + 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 + As the opensrf user, download + and extract the latest version of Evergreen. The latest version can be found here: + + + wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz + tar zxf Evergreen-ILS-1.6.1.2.tar.gz + + The new directory + /home/opensrf/Evergreen-ILS-1.6.1.2 + will be created. + + + Install Prerequisites to Build Evergreen + In this section you will install and configure a set of prerequisites that + will be used to build Evergreen. In a following step you will actually 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 + keywords table . For example, + to install the prerequisites for Ubuntu version 9.10 (Karmic Koala) you would enter this + command: make -f Open-ILS/src/extras/Makefile.install ubuntu-karmic. + + cd /home/opensrf/Evergreen-ILS-1.6.1.2 + make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION] + + + Keyword Targets for Evergreen <application>"make"</application> Command + + + + + + Keyword + Linux Version + + + + + debian-etch + Debian "Etch" (4.0) + + + debian-lenny + Debian "Lenny" (5.0) + + + ubuntu-hardy + Ubuntu "Hardy Heron" (8.04) + + + ubuntu-intrepid + Ubuntu "Intrepid Ibex" (8.10) + + + ubuntu-karmic + Ubuntu "Karmic Koala" (9.10) + + + ubuntu-karmic + Ubuntu "Lucid Lynx" (10.04) + + + centos + Centos + + + rhel + RHEL + + + gentoo + Gentoo + + + +
+ + + (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. + For further information on manually installing PostgreSQL, visit the official + PostgreSQL Site. + If your PostgreSQL server will be on the same system as your Evergreen + software, then as the root user + install the required PostgreSQL server packages: + For Debian Lenny and + Ubuntu Hardy (8.04): + + make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_83 + + For Ubuntu Karmic (9.10) and + Ubuntu Lucid (10.04): + + make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_84 + + + PostgreSQL versions 8.3 or 8.4 are the recommended versions to work + with Evergreen 1.6. If you have an older version of PostgreSQL, you should + upgrade before installing Evergreen. To find the running version of + PostgreSQL, as the postgres + user, run the 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: + + # first, ensure the gcc compiler is installed: + apt-get install gcc + # then install the Perl modules: + 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 + + + + 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: + + 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, where + [PGSQL_VERSION] is your installed PostgreSQL version + (e.g. 8.3): + + /etc/init.d/postgresql-[PGSQL_VERSION] restart + + + + Configure Evergreen + As the opensrf user, return to + the Evergreen build directory and use the configure and + make utilities to configure Evergreen so it can be compiled + and linked in the next step: + + cd /home/opensrf/Evergreen-ILS-1.6.1.2 + ./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: + + cd /home/opensrf/Evergreen-ILS-1.6.1.2 + make STAFF_CLIENT_BUILD_ID=rel_1_6_1_2 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. For further information on manually + building the Staff Client, see + . + The above commands will create a new subdirectory + /openils/var/web/xul/rel_1_6_1_2 + containing the Staff Client. + To complete the Staff Client installation, + as the root user 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: + + cd /openils/var/web/xul + ln -sf rel_1_6_1_2/server server + + + + Copy the OpenSRF Configuration Files + 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. These files replace the + configuration files that you set up in a previous step + (see ) + when you installed and tested OpenSRF. + As the root user, execute the + following commands: + + 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; if you + installed the PostgreSQL 8.3 server packages on Ubuntu 8.04, + the path would be + /usr/share/postgresql/8.3/contrib/. + + + + Create and configure the database + + As the postgres + user on the PostgreSQL system create the PostgreSQL database, + then set some internal paths: + + createdb evergreen -E UTF8 -T template0 + createlang plperl evergreen + createlang plperlu evergreen + createlang plpgsql evergreen + + Continue as user postgres + and execute the SQL scripts as shown below, adjusting the paths as needed, where + [PGSQL_VERSION] is your installed PostgreSQL + version (e.g. 8.3). + + 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: + + createuser -P -s evergreen + Enter password for new role: MYNEWPASSWORD + Enter it again: MYNEWPASSWORD + + + + Create database schema + As the root + user, create the database schema and configure your system with + the corresponding database authentication details for the + evergreen database user that you just created + in the previous step + (see ). + Enter the following commands and replace + HOSTNAME, PORT, PASSWORD and + DATABASENAME with appropriate + values: + + cd /home/opensrf/Evergreen-ILS-1.6.1.2 + perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ + --service all --create-schema --create-bootstrap --create-offline \ + --hostname HOSTNAME --port PORT \ + --user evergreen --password PASSWORD --database DATABASENAME + + 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 + previous step + (see ) + when you created the database and and set a password for the + evergreen user. + 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: + + 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: + + cd /home/opensrf/Evergreen-ILS-1.6.1.2 + 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 + You must 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: + + mkdir /etc/apache2/ssl + cd /etc/apache2/ssl + openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key + + + 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 getting 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 this line: + Allow from 10.0.0.0/8 + with this 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. + Note that Debian + users should not do this + since the conflict does not apply to that + operating system. + + + The following updates are needed to allow + the logs to function properly, but it may break + other Apache applications on your server: + For the Linux + distributions Ubuntu + Hardy or + Debian Etch, + as the root + user, edit the Apache configuration file + /etc/apache2/apache2.conf and + change the line User www-data + to User opensrf. + For the Linux + distributions Ubuntu + Karmic, + Ubuntu Lucid + or Debian Lenny, + as the root + user, edit the Apache configuration file + and change these 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 values 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: + + # 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 + + + + +
+ + + Create Configuration Files for Users Needing <command>srfsh</command> + When OpenSRF was installed in a previous step (see + for further information), + 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. See + for further information. + + + Modify the OpenSRF Environment + 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. + + + + 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 . + + +
+
+ Starting Evergreen + + + As the root + user, start the ejabberd and + memcached services as follows: + + /etc/init.d/ejabberd start + /etc/init.d/memcached start + + + + As the opensrf user, + start Evergreen as follows: + + osrf_ctl.sh -l -a start_all + + The flag forces Evergreen to use + localhost (your current system) + as the hostname. The flag starts the other + 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 calculate 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 commands: + + 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 + + + + As the root user, restart the + Apache Web server: + + /etc/init.d/apache2 restart + + + If the Apache Web server was running when you started the OpenSRF + services, you might not be able to successfully log 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. + Execute the following commands to test your Evergreen connection: + + /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: + + cd /home/opensrf + ./Evergreen-ILS-1.6.1.2/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. + + + +
+
+ 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 + In a previous step (see ) + you used the command openssl to temporarily + create a new SSL key for the Apache server. This self-signed 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. + + + The temporary SSL key was only created to expedite + testing. You should install a proper SSL certificate for a public + production system. + + +
+
+ Set Up Support For Reports + Evergreen reports are extremely powerful but require some simple configuration. + This section describes starting and stopping the Reporter daemon processes. + + + Starting the Reporter Daemon + Once the open-ils.reporter + process is running and enabled on the gateway, you can start the + Reporter daemon. That process periodically checks for requests for new + or scheduled reports, then starts them as required. + As the opensrf user, + start the Reporter daemon using the following command: + + cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/src/reporter + ./clark-kent.pl --daemon + + You can control how the clark-kent.pl utility behaves + by specifying any of several command-line options: + + : number of seconds + to sleep between checks for new reports to run; defaults to + 10 + : where to place + the lockfile for the process; defaults to + /tmp/reporter-LOCK + : number of + Reporter daemon processes to run; defaults to + 1 + : OpenSRF + bootstrap configuration file; defaults to + /openils/conf/opensrf_core.xml + + + + Stopping the Reporter Daemon + To stop the Reporter daemon, you must kill the process and remove + the lockfile. The daemon may have just a single associated process or + there may be several processes if the daemon was started with the optional + --concurrency switch. It will also have a lockfile + in the default location. + As the opensrf user, + execute the following shell commands: + + # find and kill the process ID number(s) + kill `ps wax | grep "Clark Kent" | grep -v grep | cut -b1-6` + # remove the lock file + rm /tmp/reporter-LOCK + + + +
+
+
+ Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments + This section describes the installation of Evergreen software in so-called "virtualized" + software environments. Evergreen software runs as a native application on any of several + well-known x86 (32-bit) and x86-64 (64-bit) Linux + distributions including Ubuntu and + Debian but it does not run as a native application + on the Microsoft Windows operating system. + However, it is possible to execute Evergreen on a Windows + host system by running it within a virtual Linux-guest installation, which itself executes + on the Windows system. + The Linux environment is fully emulated and acts + (within limits) just as if it were executing on a real standalone system. + This technique of emulating a Linux environment on + a Windows host is a practical way to install and run an + Evergreen system if it is not possible to dedicate a physical machine solely as a + Linux host for Evergreen. This architecture is not + recommended for large scale systems since there are performance limitations to running Evergreen + in a virtualized environment. However, it is a reasonable architecture for smaller experimental + systems, as a proof of concept, or as a conference-room pilot. + + Installing Virtualization Software + As described above, Evergreen can be installed on top of an emulated + Linux environment. The + Linux environment, in turn, is installed + on top of a software application such as "VirtualBox", + "VMware" or "VirtualPC" which must + first be installed on the Windows system. This + section contains step-by-step examples that show installing popular virtualization + applications on a Windows host system. Following + this section are further descriptions of installing + Linux and Evergreen systems using that + virtualization software. + + Installing <application>"VirtualBox"</application> Virtualization Software + This section reviews installation of the + "VirtualBox" application on + WindowsXP Professional (SP2). + Download the latest edition of VirtualBox from their official website: + http://virtualbox.org + and follow the on screen instructions to install the software. + + + Installing VMware Virtualization Software + + virtualization software + VMware + + This section reviews installation of the + "VMware" application on + WindowsXP Professional (SP2). + Find and Download the free virtual machine software of from the VMware + official website: + http://downloads.vmware.com + and follow the on-screen instructions. + + + + Installing <systemitem class="osname">Linux</systemitem> / + Evergreen on Virtualization Software + After the virtualization software is installed and running, there are two ways to + continue with installing Linux and Evergreen + software in the new virtualized environment: + + + Download and install a prebuilt software image that contains a + working Linux / Evergreen system + (see for + details) + + + Manually install a Linux + guest system, then manually install Evergreen on it. + + + We review each method in the following sections. + + Download and install a prebuilt software image + You can download a prebuilt software image that, when installed with your + virtualization software, emulates a + Linux guest system containing a running + Evergreen distribution. The image is essentially a snapshot of a hard disk from + a fully configured, functional Linux + system with Evergreen already installed. + We recommend this approach if you wish to get Evergreen running quickly + with minimal attention to configuration. After reviewing only a few + configuration details you can have a working Evergreen system that integrates + smoothly with the rest of your network. See + for a list of prebuilt + software images that are currently available to download and install + DISCLAIMER: The following virtual images have been contributed by members + of the Evergreen community for the purposes of testing, evaluation, training, + and development. + + Linux / Evergreen Virtual Images + + + + + + + + Linux Version + Evergreen Version + Image + Comments + + + + + Debian lenny (5.0) + 1.6.0.1 + + download + + VirtualBox image + + + Ubuntu karmic koala (9.10) + 1.6.0.0 + + download + + VirtualBox image + + + +
+ + VirtualBox Example + + virtualization software + VirtualBox + + + Start VirtualBox for the first time and select + FileVirtualBox Media + ManagerAdd + to locate the prebuilt software image just downloaded (the + example shows it was extracted from the original + zip file into a temporary directory + C:\temp). + + + After selecting the file, click Open to import it. + + + Then click OK to save the selection + and return to the VirtualBox Media Manager + + + Click New, then Next to continue + and create a new virtual machine (VM). + + + Create a new name for the VM and set the operating system + type, then click Next. + + + Set the memory size (at least 512Mb), + then click Next. + + + Edit the Virtual Hard Disk configuration settings; click + the radio boxes Boot Hard Disk and + Use existing hard disk + and ensure that the disk name Evergreen1601_DebianLenny.vmdk + is selected. Click Finish to finish the + setup. + + + Install the VirtualBox Guest + Additions (really a required upgrade to + VirtualBox) + + + Return to VirtualBox and see the summary of the VM just + created. Click Start to boot the new VM. + + + See the start of the Linux + boot sequence. Choose Debian Gnu/Linux, kernel + 2.6.26-2-686 from the startup menu and click + Enter to start + Linux and Evergreen. + After some delay you should see the command line prompt + debian-lenny login:. Log in with username + root and password evergreen + to continue. + + + + +
+
+