From 857ab620cc1e91646ca842bfc67dbb4a5f49736a Mon Sep 17 00:00:00 2001 From: Steve Sheppard Date: Tue, 7 Sep 2010 16:47:02 -0400 Subject: [PATCH] tweaks to section "Installing Evergreen V1.6.0.7 On Ubuntu or Debian" --- 1.6/admin/ServersideInstallation.xml | 173 ++++++++++++--------------- 1 file changed, 79 insertions(+), 94 deletions(-) diff --git a/1.6/admin/ServersideInstallation.xml b/1.6/admin/ServersideInstallation.xml index ba6e944d72..a271caa56a 100644 --- a/1.6/admin/ServersideInstallation.xml +++ b/1.6/admin/ServersideInstallation.xml @@ -529,7 +529,7 @@
- Installing Evergreen On Ubuntu or Debian + Installing Evergreen V1.6.0.7 On Ubuntu or Debian This section outlines the installation process for the latest stable version of Evergreen (1.6.0.7). 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. @@ -696,9 +696,10 @@ Commands to restart PostgreSQL service $ su - root - $ /etc/init.d/postgresql-8.3 restart + $ /etc/init.d/postgresql-PGSQL_VERSION restart + Where "PGSQL_VERSION" is your installed PostgreSQL version (e.g. "8.3").
Configure Evergreen @@ -729,7 +730,7 @@ The above commands will create a new subdirectory /openils/var/web/xul/rel_1_6_0_7 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 /server subdirectory of the new Staff Client build: + 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 /server subdirectory of the new Staff Client build:
Commands to create symbolic link @@ -756,7 +757,7 @@
Create and Configure PostgreSQL Database As the postgres user on your PostgreSQL server, create the Evergreen database. - Remember to adjust the path for the contrib repository to match your PostgreSQL server layout. For example, if you built PostgreSQL from source following the cheat sheet, the contrib directory will be located here: /usr/local/share/contrib . If you installed the PostgreSQL 8.3 server packages on Ubuntu 8.04, the directory will be located here: /usr/share/postgresql/8.3/contrib/ . + 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/. @@ -774,33 +775,34 @@ $ createlang plpgsql evergreen # adjust the paths - $ psql -f /usr/share/postgresql/8.3/contrib/tablefunc.sql evergreen - $ psql -f /usr/share/postgresql/8.3/contrib/tsearch2.sql evergreen - $ psql -f /usr/share/postgresql/8.3/contrib/pgxml.sql evergreen + $ 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
+ Where "PGSQL_VERSION" is your installed PostgreSQL version (e.g. "8.3"). Create new Evergreen superuser - As the postgres user on the PostgreSQL system, create the new user evergreen: + As the postgres user on the PostgreSQL system, create the new database user evergreen and assign a password:
Commands to create the "evergreen" user # create superuser 'evergreen' and set the password $ su - postgres $ createuser -P -s evergreen - Enter password for new role: mynewpassword - Enter it again: mynewpassword + Enter password for new role: MYNEWPASSWORD + Enter it again: MYNEWPASSWORD
+ Where "MYNEWPASSWORD" is the password chosen.
Create Database Schema - As the root user, create the database schema and configure your system with the corresponding database authentication details for the database user 'evergreen' that you created in the previous step. - Enter the commands and replace [HOSTNAME], [PORT], [USER], [PASSWORD] and [DATABASENAME] with appropriate values. - On most systems [HOSTNAME] will be localhost, and [PORT] will be 5432. + As the root user, create the database schema and configure your system with the corresponding database authentication details for the database user evergreen that you created in the previous step. + Enter the following commands and replace HOSTNAME, PORT, PASSWORD and DATABASENAME with appropriate values.
Commands to create Evergreen database schema @@ -808,10 +810,11 @@ $ cd /home/opensrf/Evergreen-ILS-1.6.0.7 $ 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 [USER] --password [PASSWORD] --database [DATABASENAME] + --hostname HOSTNAME --port PORT \ + --user evergreen --password PASSWORD --database DATABASENAME
+ Where, on most systems, HOSTNAME will be localhost, PORT will be 5432, and PASSWORD and DATABASENAME will be those assigned when PostgreSQL was installed in the previous step. 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. @@ -832,9 +835,9 @@ $ cd /home/opensrf/Evergreen-ILS-1.6.0.7 # copy files - $ 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/ + $ 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/
@@ -851,7 +854,7 @@ - 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: + This is only a temporary measure to expedite testing. You must get a proper SSL certificate for a public production system. ADD INFO ON HOW TO GET A SIGNED SSL CERTIFICATE @@ -859,7 +862,7 @@
Modify the Apache Configuration File As the root user, edit the Apache configuration file /etc/apache2/sites-available/eg.conf and make the following changes: - + Comment out the line Allow from 10.0.0.0/8, then uncomment the line Allow from all. @@ -872,42 +875,32 @@ - Comment out the line Listen 443 as it conflicts with the same declaration in the configuration file: /etc/apache2/ports.conf . Debian etch users should 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 should not do this. ADD INFO ON WHY DEBIAN ETCH USERS SHOULD NOT DO THIS - The following updates are needed to allow the logs to function properly, but it may break other Apache applications on your server. We hope to make this unnecessary soon. - ADD INFO ON WHETHER THIS IS STILL NECESSARY - + The following updates are needed to allow the logs to function properly, but it may break other Apache applications on your server. We hope to make this unnecessary in a future Evergreen release. + - 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 user: - www-data - to the user: - opensrf + 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 user: www-data to the user: opensrf. - For the Linux distributions Ubuntu Karmic or Ubuntu Lucid or Debian Lenny, as the root user, edit the Apache configuration file /etc/apache2/envvars and change the phrase: - export APACHE_RUN_USER=www-data - to the phrase: - export APACHE_RUN_USER=opensrf + For the Linux distributions Ubuntu Karmic or Ubuntu Lucid or Debian Lenny, as the root user, edit the Apache configuration file /etc/apache2/envvars and change the phrase: export APACHE_RUN_USER=www-data to the phrase: export APACHE_RUN_USER=opensrf. - + As the root user, edit the Apache configuration file /etc/apache2/apache2.conf and add the line KeepAliveTimeout 1, or modify an existing line if it already exists. - +
(OPTIONAL) Performance Modifications for Apache - Some further configuration changes to Apache may be necessary for busy systems. These changes increase the number of Apache server processes that can be started to support additional browser connections, and are made to the prefork configuration section of the Apache configuration file. - - As the root user, edit the Apache configuration file /etc/apache2/apache2.conf and add the line MaxKeepAliveRequests 100, or modify an existing line if it already exists. - - 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. -
- (OPTIONAL) Example of updates to Apache configuration - + Some 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. + As the root user, edit the Apache configuration file /etc/apache2/apache2.conf and add the line MaxKeepAliveRequests 100, or modify an existing line if it already exists. +
(OPTIONAL) Example of updates to Apache configuration <IfModule mpm_prefork_module> StartServers 20 MinSpareServers 5 @@ -915,36 +908,34 @@ MaxClients 150 MaxRequestsPerChild 10000 </IfModule> - + MaxKeepAliveRequests 100 - -
- - +
+
Enable the Evergreen Site - You must run additional Apache configuration commands to enable the Evergreen web site. As the root user, run these commands: + As the root user, execute the following Apache configuration commands to disable the default "It Works" web page and to enable the Evergreen web site:
Commands to enable the Evergreen Web Site $ su - root - - # disables the default site (i.e., the "It Works" page). + + # disable the default site $ a2dissite default - # enables the Evergreen web site + # enable the Evergreen web site $ a2ensite eg.conf
Modify the OpenSRF Configuration File - As the opensrf user, edit the OpenSRF configuration file /openils/conf/opensrf_core.xml to update various usernames and passwords, and to specify the domains from which we will accept and to which we will make connections. + 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 following example uses common XPath syntax on the left-hand side to indicate the aproximage position needing changes within the XML file. + The following example uses common XPath syntax on the left-hand side to indicate the approximate position needing changes within the XML file: ADD A BETTER DIAGRAM HERE @@ -974,15 +965,15 @@
Create Configuration Files for Users Needing 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 the OpenSRF network software. It will be used in a future step to complete and test the Evergreen installation. See the section "Testing the Installation" for further information. - In this section you will set up a special configuration file for each user who will need to run the utility. Copy the short sample configuration file /openils/conf/srfsh.xml.example to the file .srfsh.xml (note the leading dot!) in the home directory of each user who will use srfsh. Finally, edit each file .srfsh.xml and make the following changes: - + In this section you will set up a special configuration file for each user who will need to run the utility. Copy the short sample configuration file /openils/conf/srfsh.xml.example to the file .srfsh.xml (note the leading dot!) in the home directory of each user who will use srfsh. Finally, edit each users' .srfsh.xml file and make the following changes: + Modify domain to be the router hostname (following our domain examples, private.localhost will give srfsh access to all OpenSRF services, while public.localhost will only allow access to those OpenSRF services that are publicly exposed). Modify username and password to match the opensrf Jabber user for the chosen domain Modify logfile to be the full path for a log file to which the user has write access Modify loglevel as needed for testing - +
- Example of the file "/openils/conf/srfsh.xml.example" + Example of user's file ".srfsh.xml" <?xml version="1.0"?> <!-- This file follows the standard bootstrap config file layout --> @@ -1002,7 +993,7 @@
Modify the OpenSRF Environment - As the opensrf user, change the file permissions of the directory /openils/var/cgi-bin to executable, then modify the shell configuration file ~/.bashrc of that user by adding a Perl environmental variable. Finally, execute the shell configuration file to load the new variables into your current environment. + As the opensrf user, change the permissions of .cgi files in the directory /openils/var/cgi-bin to executable, then modify the shell configuration file ~/.bashrc for opensrf by adding a Perl environmental variable. Finally, 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. @@ -1023,11 +1014,6 @@
-
- (OPTIONAL) Configuration for Other Languages - This section describes how translations such as Armenian (hy-AM), Canadian French (fr-CA) and others are loaded into the database to complete the translations (default English) available in the OPAC and Staff Client. - ADD SECTION ON LANGUAGE LOCALIZATION -
Starting Evergreen @@ -1078,22 +1064,16 @@ 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. + You must do this the first time you start Evergreen, and after any changes you make to the library hierarchy in the configuration file config.cgi.
Commands to generate web files $ su - opensrf $ 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 Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml' Updating fieldmapper - Exception: OpenSRF::EX::Session 2010-04-16T06:31:38 \ - OpenSRF::Utils::SettingsClient \ - /usr/local/share/perl/5.10.0/OpenSRF/Utils/SettingsClient.pm:103 \ - Session Error: router@private.localhost/opensrf.settings \ - IS NOT CONNECTED TO THE NETWORK!!! + ... ADD RESULTS OF TESTS FROM "autogen.sh"
@@ -1107,14 +1087,14 @@ $ /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 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:
@@ -1145,8 +1125,8 @@ ------------------------------------
- - +
+
Other Connection Tests with "srfsh" There is another 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: @@ -1161,13 +1141,13 @@ For other srfsh commands, type 'help' in at the prompt. If this does not work, try the troubleshooting steps in the following section. - - - Testing with "settings-test.pl" +
+
+ Testing with "settings-tester.pl" 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: REWORK THIS DIAGRAM TO USE SAME IMAGE STANDARDS AS OTHER CHAPTERS
- Executing the script <emphasis>settings-test.pl</emphasis> + Executing the script <emphasis>settings-tester.pl</emphasis> @@ -1179,20 +1159,20 @@
- 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 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 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). ADD OTHER SIMPLE FUNCTIONAL TESTS - - +
+
Running the Evergreen Staff Client Run the Evergreen Staff Client 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 as follows: + 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 follows:
Commands to run the Staff Client @@ -1200,8 +1180,8 @@ $ xulrunner /home/opensrf/Evergreen-ILS-1.6.0.7/Open-ILS/xul/staff_client/build/application.ini
- - +
+
Testing the Apache Web Server Once you have started Evergreen and confirmed that a basic login attempt works, you can test and start the Apache web server. As the root user, execute the following commands. Note the use of restart to force the new Evergreen modules to be reloaded even if the Apache server is already running. Any problems found with your configuration files should be displayed: @@ -1212,7 +1192,7 @@ $ apache2ctl configtest && /etc/init.d/apache2 restart - +
Stopping Evergreen @@ -1255,7 +1235,7 @@
Set Up Support For Reports Evergreen reports are extremely powerful, but some configuration is required. See the section "Reports" for details. - +
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 reports or scheduled reports and gets them running. As the opensrf user, start the reporter daemon using the following command: @@ -1272,10 +1252,10 @@ --sleep=interval : number of seconds to sleep between checks for new reports to run; defaults to 10 --lockfile=filename : where to place the lockfile for the process; defaults to /tmp/reporter-LOCK --concurrency=integer : number of reporter daemon processes to run; defaults to "1" - --boostrap=filename : OpenSRF bootstrap configuration file; defaults to /openils/conf/opensrf_core.xml + --bootstrap=filename : 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, with a lockfile in the default location. @@ -1293,7 +1273,7 @@ $ rm /tmp/reporter-LOCK - +
@@ -1813,4 +1793,9 @@ Using nginx to serve static content ADD CONTENT FOR USING NGINX TO SERVE STATIC CONTENT
+
+ (OPTIONAL) Configuration for Other Languages + This section describes how translations such as Armenian (hy-AM), Canadian French (fr-CA) and others are loaded into the database to complete the translations (default English) available in the OPAC and Staff Client. + ADD SECTION ON LANGUAGE LOCALIZATION +
-- 2.43.2