From 11a4d7825c04c82903de2b31ae9172af04d5cc54 Mon Sep 17 00:00:00 2001 From: Steve Sheppard Date: Sun, 29 Aug 2010 14:30:00 -0400 Subject: [PATCH] reorganize slightly, merge several short sections into chapter 5; --- 1.6/admin/ServersideInstallation.xml | 314 +++++++++++++-------------- 1 file changed, 156 insertions(+), 158 deletions(-) diff --git a/1.6/admin/ServersideInstallation.xml b/1.6/admin/ServersideInstallation.xml index f7b8d32c6c..ae56b65dc5 100644 --- a/1.6/admin/ServersideInstallation.xml +++ b/1.6/admin/ServersideInstallation.xml @@ -3,18 +3,20 @@ Server-side Installation of Evergreen Software - Specifics in the process of installing server-side software for Evergreen + This section describes installation of the Evergreen server-side software. Installation, configuration, testing and verification of the Evergreen server-side software is straightforward if you follow some simple directions. Installation of the Evergreen Staff Client software is handled in the section "Installing the Evergreen Staff Client" .
Overview - A bare-minimum system Evergreen system requires only a single Server and a single Staff Client (in fact, that is a reasonable system for simple experiments or a proof-of-concept). Another simple system may require only that you install one or more instances of the Staff Client software. For instance, if your consortium already provides the Evergreen Server software or if you are using the hosted version provided by Equinox, you do not need to install the Server software at all. But typical real-world systems will probably consist of at least one or two Servers plus multiple Staff Clients. - The Server software currently runs as a native application on any of several well-known Linux distributions (e.g., Debian and Ubuntu). It does not run as a native application on the Windows operating system (e.g., WindowsXP, WindowsXP Professional, Windows7), but the software can be installed and run on Windows via a virtualized Unix-guest Operating System (using, for example, VirtualBox or VMware to emulate a Linux environment). More information on virtualized environments can be found in the section "Installing in Virtualized Unix Environments" + A bare-minimum system Evergreen system requires only a single Server and a single Staff Client, both residing on a single server machine. In fact, that is a reasonable architecture for simple experiments or as a proof of concept in a conference-room pilot. But typical real-world systems will probably consist of at least one or two Evergreen servers plus multiple Staff Clients. + Another simple system may require only that you install one or more instances of the Staff Client software. For instance, if your consortium already provides the Evergreen server software or if you are using the hosted version provided by Equinox, you do not need to install the Evergreen server-side software at all. + Current versions of Evergreen software run as native applications on any of several well-known Linux distributions (e.g., Ubuntu and Debian). It does not currently run as a native application on the 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 Unix-guest Operating System (using, for example, VirtualBox or VMware to emulate a Linux environment). More information on running Evergreen in virtualized environments can be found in the section "Installing Evergreen in Virtualized Unix Environments".
System Requirements - This section describes processes and events that must occur to install the Evergreen server in all supported operating systems / environments. Please review the section "The Installation Process" for instructions tailored to specific distributions. + This section describes various requirements of the hardware and software environment that must be fulfilled to support a successful Evergreen installation. For a description of the installation process itself and for links to further instructions please review the section "The Installation Process" . The system requirements for running Evergreen really depend on what you want to do with it. For just evaluating the software, or for a very small library (for example, 1 circulation station, a few thousand items, and infrequent online catalog use), any modern desktop or laptop made within the last few years capable of running Linux, FreeBSD, etc. should suffice. We recommend at least 512mb of RAM. + [[ Other hardware and software requirements ]] From Dan Scott on [http://list.georgialibraries.org/pipermail/ @@ -79,83 +81,55 @@
Example System Architectures - [[real-world examples of working systems]] + This sections describes examples of some working Evergreen system architectures, including both server-side software and Staff Client software.
PINES In order to provide load balancing and high-availability at the OPAC and Staff Client level, PINES has implemented a Linux Virtual Server environment with five independent mini-clusters. This allows live updates of the entire system with no perceived downtime or interruption in service. [[ further information on PINES ]]
-
- Other Architectures - [[ further information on OTHER ]] +
+ Sitka + [[ further information on Sitka ]]
-
-
- Installing in Virtualized Unix Environments - [[ Installing in Virtualized Unix Environments ]] -
- VirtualBox - [[ VirtualBox ]] -
-
- VMware - [[ VMware ]] -
-
- VirtualPC - [[ VirtualPC ]] +
+ Other working systems + [[ further information on other working systems ]]
The Installation Process + Installing, configuring and testing the Evergreen server-side software is straightforward with the current stable software release. Earlier software distributions are also available. In the following sections you will find instructions tailored to specific distributions.
- Current stable Release - - Installing Evergreen 1.6.0.x on Ubuntu or Debian + Current Stable Software Release + The current stable release of Evergreen is version 1.6.0.7. Instructions for installing, configuring and testing that version on the Ubuntu or Debian Linux systems are found in the section "Installing Evergreen 1.6.0.7 on Ubuntu or Debian" . - - Installing OpenSRF 1.2.x + This release of Evergreen software is dependent on the OpenSRF software system. The current stable release of OpenSRF is version 1.0.6. Instructions for installing, configuring and testing that version are found in the section "Installing OpenSRF" .
- Previous stable release - - Installing Evergreen 1.4.0.x on Ubuntu or Debian + Previous Software Releases + Earlier releases of Evergreen are also available. Instructions for installing, configuring and testing earlier versions are found in the section Installing Previous Versions of Evergreen . + The most recent previous release of Evergreen is version 1.4.0.6. Instructions for installing, configuring and testing that version are found in the section Installing Evergreen 1.4.0.6 on Ubuntu or Debian . - - Installing OpenSRF 1.0.x - -
-
- Configuring the system - - Organization and Policy Editing + The most recent previous release of OpenSRF is version 1.0.x. Instructions for installing, configuring and testing that version are found in the section Installing OpenSRF 1.0.x . -
- Holds - For holds to work properly, you need to run this command as the user opensrf to calculate the proximity of locations in the Organizational Unit tree: - - $ autogen.sh -u -c /openils/conf/opensrf_core.xml - - This is an expensive operation if you have a large Organizational Unit tree, so don't run it indiscriminately. -
- Installing Evergreen 1.6.0.x On Ubuntu or Debian + Installing Evergreen 1.6.0.7 On Ubuntu or Debian 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. To become the root user, issue the command: su - root. To switch from the root user to a different user, issue a command like: su - USERNAME. For example, to switch from the root user to the opensrf user, issue this command: su - opensrf. Once you have become a non-root user, to become the root user again, simply issue the exit command.
- Install the latest version of OpenSRF - For further information on installing the Open Service Request Framework (OpenSRF), see the section Installing OpenSRF. + Installing the latest version of OpenSRF + For further information on installing the Open Service Request Framework (OpenSRF), see the section "Installing OpenSRF" . Follow the steps outlined in that section, then run the specified test(s) to ensure that OpenSRF is properly installed before continuing with any further Evergreen installation steps. The Evergreen application depends on properly installation of OpenSRF. If OpenSRF does not work correctly, Evergreen will not work properly either.
- Download and Build Evergreen - In this section, you will download, unpack, install and test the Evergreen system, including the Evergreen server and the PostgreSQL database system. You will also 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. - As far as possible, perform the following steps in the order they are 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. - Of course, when you successfully complete and test the entire 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 institute. + Downloading and Building 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. + As far as possible, perform the following steps in the order they are 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. + 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.
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: @@ -192,7 +166,7 @@
(OPTIONAL) Install the PostgreSQL Server 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. If your PostgreSQL server is on a different system, just skip this step. - For further information on installing PostgreSQL, see the section Installing PostgreSQL. + For further information on installing PostgreSQL, see the section "Installing PostgreSQL" . 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:
Commands to install the PostgreSQL server @@ -273,7 +247,7 @@
Link and Install Evergreen - As the root user, link and install the compiled code. In the commands below, 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. Finally, create a symbolic link named server in /openils/var/web/xul to the /server subdirectory of your staff client build: + As the root user, link and install the compiled code. In the commands below, 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. Finally, create a symbolic link named server in /openils/var/web/xul to the /server subdirectory of your Staff Client build:
Commands to link and install Evergreen @@ -384,7 +358,7 @@
Create a Security Certificate (SSL Key) - Use the command openssl to create a new SSL key for your Apache server. For a public production server you should 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: + Use the command openssl to create a new SSL key for your Apache server. For a public production server you should 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:
Commands to create an SSL key @@ -393,7 +367,7 @@ $ openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key
- Warning: This is only a temporary measure to expedite testing. You must get a proper SSL certificate for a public production system. See this section for further comments on setting up a properly signed SSL certificate: + Warning: This is only a temporary measure to expedite testing. You must get a proper SSL certificate for a public production system. See this section for further comments on setting up a properly signed SSL certificate: [[how to get a signed SSL certificate]]
@@ -403,11 +377,13 @@ Comment out the line Allow from 10.0.0.0/8, then uncomment the line Allow from all. This is a temporary measure to expedite testing. - Warning: You must remove these changes after testing is completed. This will enable access to the configuration CGI scripts from any workstation on any network. You must secure this for a public production system, preferably by explicitly specifying the allowed IP addresses and adding proper authentication. + Warning: You must remove these changes after testing is completed. This will enable access to the configuration CGI scripts from any workstation on any network. You must secure this for a public production system, preferably by explicitly specifying the allowed IP addresses and adding proper authentication. - Comment out the line Listen 443 as it conflicts with the same declaration in the configuration file: /etc/apache2/ports.conf . - [[Debian Etch users - do not do this!]] + + Comment out the line Listen 443 as it conflicts with the same declaration in the configuration file: /etc/apache2/ports.conf . + [[Debian Etch users - do not do this!]] +
@@ -487,7 +463,8 @@
Create Private Configuration Files for Certain Users - Copy the file /openils/conf/srfsh.xml.example to the file .srfsh.xml in the home directory of each user you want to use to run the srfsh command line client for testing OpenSRF. Finally, edit each file .srfsh.xml and make the following changes: + The software installation will automatically create a utility named srfsh (surf shell). This is a command line diagnostic tool for interacting with the OpenSRF network software. You must set up a special configuration file for each user who will need to run the utility. + Copy the file /openils/conf/srfsh.xml.example to the file .srfsh.xml in the home directory of each user who will use srfsh. Finally, edit each file .srfsh.xml and make the following changes: Modify domain to be the router hostname (following our domain examples, private.localhost will give the utility 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 @@ -532,7 +509,7 @@
(OPTIONAL) Configuration for Other Languages - 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. See the section Adding Language Localization for details. + 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. See the section "Adding Language Localization" for details.
@@ -580,8 +557,8 @@ - As the opensrf user, generate the Web files needed by the staff client and catalogue, and also update the organization unit proximity. - You need to do this the first time you start Evergreen, and after that each time you change the library hierarchy in ''config.cgi'': + As the opensrf user, generate the Web files needed by the Staff Client and catalogue, 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 any time you change the library hierarchy in the configuration file config.cgi.
Generate web files @@ -605,72 +582,93 @@ $ /etc/init.d/apache2 restart
- If the Apache Web server was running when you started the OpenSRF services, you might not be able to successfully log in to the OPAC or staff client until the Apache Web server is restarted. + If the Apache Web server was running when you started the OpenSRF services, you might not be able to successfully log in to the OPAC or Staff Client until the Apache Web server is restarted.
-
- Testing Connections to Evergreen - Once you have installed and started Evergreen, test your connection to Evergreen by using the utility srfsh. Start the utility and try logging onto the Evergreen server using the default administrator username and password. Following is sample output generated by executing that script during a successful Evergreen installation: -
- Running the srfsh utility +
+ Testing the 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. As the opensrf user start the utility srfsh and try logging onto the Evergreen server using the default administrator username and password. Following is sample output generated by executing that script after a successful Evergreen installation: +
+ Running the srfsh utility + + $ su - opensrf + $ /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 other simple troubleshooting steps: + + + As the opensrf user, run the script settings-tester.pl to see if it finds any system configuration problems. Following is sample output generated by executing that script after a successful Evergreen installation: +
+ Executing the script <emphasis> settings-test.pl</emphasis> + + + + + + + + + + +
+ If the output from the script does not help you find the problem, please do not make any further significant changes to your configuration. Follow the steps in the troubleshooting guide, "Troubleshooting" . + + 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 [[ http://open-ils.org/listserv.php|Evergreen development mailing list ]] for assistance before making any drastic changes to your system configuration. + +
+
+ Testing the Catalog + By default, the OPAC will live at the URL http://my.domain.com/opac/. + Navigate to this URL and the front page of the OPAC should load. There is a basic text entry field with some extra search options. If you have any problems loading this page, check the Apache error logs. If the page loads but does not function correctly, then check for possible javascript errors. We hightly reccommend testing with the Firefox browser because of the helpful javascript debugging tools. + Assuming that the OPAC is functioning and there is data in your database, you can now perform other simple functional tests (e.g., searching the catalog). + [[ other simple functional tests ]] +
+
+ Other Tests with srfsh + There is also a srfsh command called math_bench that sends queries to the math servers. Note that opensrf.math and opensrf.dbmath must be running for this command to work: - $ su - opensrf - $ /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 - ------------------------------------ + srfsh# math_bench 10 + |.........|.........|.........|.........|.........|.........|.........|.........|.........|......... + ++++++++++++++++++++++++++++++++++++++++ + Average round trip time: 0.033425 + srfsh# -
- If this does not work, try some simple troubleshooting steps: - - - As the opensrf user, run the script settings-tester.pl to see if it finds any system configuration problems. Following is sample output generated by executing that script during a successful Evergreen installation: -
- Executing the script <emphasis> settings-test.pl</emphasis> - - - - - - - - - - -
- If the output from the script does not help you find the problem, please do not make any further significant changes to your configuration. Follow the steps in the troubleshooting guide, Troubleshooting . - - 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 [[ http://open-ils.org/listserv.php|Evergreen development mailing list ]] for assistance before making any drastic changes to your system configuration. - + The first argument is how many sets of 4 queries (+ - * /) are sent to opensrf.math. When the response is successful, you will see the string of "+" symbols. If the system is not running correctly, you will either get an exception or no result at all. + For other srfsh commands, type 'help' in at the prompt. +
Running the Staff Client on Linux - Run the Evergreen staff client on a Linux system by using the application XULRunner (installed automatically and by default with Firefox version 3.0 and later on Debian and Ubuntu distributions). - For example, if the source files for the Evergreen installation are in the directory /home/opensrf/Evergreen-ILS-1.6.0.7/, start the staff client as shown in the following command example: + Run the Evergreen Staff Client on a Linux system by using the application XULRunner (installed automatically and by default with Firefox version 3.0 and later on Ubuntu and Debian distributions). + For example, if the source files for the Evergreen installation are in the directory /home/opensrf/Evergreen-ILS-1.6.0.7/, start the Staff Client as shown in the following command example:
- Running the Linux staff client + Running the Linux Staff Client $ su - opensrf $ xulrunner /home/opensrf/Evergreen-ILS-1.6.0.7/Open-ILS/xul/staff_client/build/application.ini @@ -707,7 +705,7 @@
Setting Up Support For Reports - Evergreen reports are extremely powerful, but some configuration is required. See the section Reports for details. + Evergreen reports are extremely powerful, but some configuration is required. See the section "Reports" for details.
Starting the Reporter Daemon @@ -745,49 +743,49 @@
- Installing OpenSRF 1.2.x + Installing OpenSRF [[ Installing OpenSRF 1.2.x ]]
-
- Installing Evergreen 1.4.0.x on Ubuntu or Debian - [[ Installing Evergreen 1.4.0.x on Ubuntu or Debian ]] +
+ Installing Evergreen On Other Linux Systems + [[ Installing on Other Linux Systems ]] +
+
+ Installing Evergreen in Virtualized Unix Environments + Evergreen software currently runs as a native application on any of several well-known Linux distributions (e.g., Ubuntu and Debian). It does not run as a native application on the Windows operating system (e.g., WindowsXP, WindowsXP Professional, Windows7), but the software can be installed and run on Windows via a virtualized Unix-guest Operating System (using, for example, VirtualBox or VMware to emulate a Linux environment). More information on virtualized environments can be found in the section "Installing Evergreen in Virtualized Unix Environments". + [[ Installing Evergreen in Virtualized Unix Environments ]] +
+ VirtualBox + [[ VirtualBox ]] +
+
+ VMware + [[ VMware ]] +
+
+ VirtualPC + [[ VirtualPC ]] +
-
- Installing OpenSRF 1.0.x - [[ Installing OpenSRF 1.0.x ]] +
+ Installing Previous Versions of Evergreen + Earlier releases of Evergreen are available. Instructions for installing, configuring and testing earlier versions are found below. +
+ Installing Evergreen 1.4.0.6 on Ubuntu or Debian + [[ Installing Evergreen 1.4.0.6 on Ubuntu or Debian ]] +
+
+ Installing OpenSRF 1.0.x + [[ Installing OpenSRF 1.0.x ]] +
Organization and Policy Editing [[ Organization and Policy Editing ]]
-
- Testing the Installation -
- Testing with srfsh - Installing OpenILS will place an executable called 'srfsh' (surf shell) into the BINDIR directory. This is a command line diagnostic tool for interacting with the OpenSRF network. - For starters, there is a command called math_bench in srfsh that sends queries to the math servers. Note that opensrf.math and opensrf.dbmath must be running for this command to work: - - srfsh# math_bench 10 - |.........|.........|.........|.........|.........|.........|.........|.........|.........|......... - - ++++++++++++++++++++++++++++++++++++++++ - Average round trip time: 0.033425 - srfsh# - - The first argument is how many sets of 4 queries (+ - * /) are sent to opensrf.math. When the response is successful, you will see the string of "+" symbols. If the system is not running correctly, you will either get an exception or no result at all. - For other srfsh commands, type 'help' in at the prompt. -
-
- Testing the OPAC - By default, the OPAC will live at the URL http://my.domain.com/opac/. - Navigate to this URL and the front page of the OPAC should load. There is a basic text entry field with some extra search options. If you have any problems loading this page, check the Apache error logs. If the page loads but does not function correctly, then check for possible javascript errors. We hightly reccommend testing with the Firefox browser because of the helpful javascript debugging tools. - Assuming that the OPAC is functioning and there is data in your database, you can now perform other simple functional tests (e.g., searching the catalog). - [[ other simple functional tests ]] -
-
-
- Building the Staff Client - [[ Building the Staff Client ]] +
+ Installing the Staff Client + [[ Installing the Staff Client ]]
Adding Language Localization -- 2.43.2