From: Steve Sheppard Date: Sun, 29 Aug 2010 01:52:42 +0000 (-0400) Subject: expand sections 6.3 .. 6.10; X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=1561a5edf0d2a78caf59b7743c79a9e3c61d9e1a;p=Evergreen-DocBook.git expand sections 6.3 .. 6.10; add new supporting images; --- diff --git a/1.6/admin/ServersideInstallation.xml b/1.6/admin/ServersideInstallation.xml index ba37172..f7b8d32 100644 --- a/1.6/admin/ServersideInstallation.xml +++ b/1.6/admin/ServersideInstallation.xml @@ -49,9 +49,9 @@ now. The developers themselves used Gentoo originally, and that's what I'm using at the moment & have documented in the wiki; the install process on Ubuntu is very thoroughly documented and - Ubuntu is reasonably close to Debian. See - http://open-ils.org/dokuwiki/doku.php?id=server_installation for - the list of install instructions for various distributions. + Ubuntu is reasonably close to Debian. + See http://open-ils.org/dokuwiki/doku.php?id=server_installation + for the list of install instructions for various distributions. As for advantages / disadvantages of particular distributions, that's a religious war that I don't want to step into... We'll try @@ -145,7 +145,7 @@ Installing Evergreen 1.6.0.x 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: sudo 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. + 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. @@ -162,7 +162,7 @@
Commands to download/extract Evergreen - $ sudo su - opensrf + $ su - opensrf $ wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.0.7.tar.gz $ tar zxf Evergreen-ILS-1.6.0.7.tar.gz @@ -183,7 +183,7 @@
Commands to install prerequisites for Evergreen - $ sudo su - root + $ su - root $ cd /home/opensrf/Evergreen-ILS-1.6.0.7 $ make -f Open-ILS/src/extras/Makefile.install [distribution] @@ -197,7 +197,7 @@
Commands to install the PostgreSQL server - $ sudo su - root + $ su - root # Debian Lenny and Ubuntu Hardy (8.04) $ make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_83 @@ -218,7 +218,7 @@ Commands to install Perl modules # ensure the gcc compiler is installed - $ sudo su - root + $ su - root $ aptitude install gcc # install the Perl modules @@ -237,7 +237,7 @@
Commands to modify system dynamic library path - $ sudo su - root + $ su - root $ cat > /etc/ld.so.conf.d/eg.conf << ENDOFFILE /usr/local/lib /usr/local/lib/dbd @@ -253,7 +253,7 @@
Commands to restart PostgreSQL service - $ sudo su - root + $ su - root $ /etc/init.d/postgresql-8.3 restart
@@ -264,7 +264,7 @@
Commands to configure and compile Evergreen - $ sudo su - opensrf + $ su - opensrf $ cd /home/opensrf/Evergreen-ILS-1.6.0.7 $ ./configure --prefix=/openils --sysconfdir=/openils/conf $ make @@ -277,7 +277,7 @@
Commands to link and install Evergreen - $ sudo su - root + $ su - root $ cd /home/opensrf/Evergreen-ILS-1.6.0.7 $ make STAFF_CLIENT_BUILD_ID=rel_1_6_0_6 install $ cd /openils/var/web/xul @@ -291,7 +291,7 @@
Commands to copy OpenSRF configuration files - $ sudo su - root + $ su - root $ cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml $ cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml $ cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml @@ -313,7 +313,7 @@ Commands to create database and adjust the path # create the database - $ sudo su - postgres + $ su - postgres $ createdb -E UNICODE evergreen $ createlang plperl evergreen $ createlang plperlu evergreen @@ -333,7 +333,7 @@ Commands to create the 'evergreen' user # create superuser 'evergreen' and set the password - $ sudo su - postgres + $ su - postgres $ createuser -P -s evergreen Enter password for new role: mynewpassword Enter it again: mynewpassword @@ -350,7 +350,7 @@
Commands to create Evergreen database schema - $ sudo su - root + $ su - root $ 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 \ @@ -369,7 +369,7 @@ Commands to configure the Apache server # configure the Apache server - $ sudo su - root + $ su - root $ a2enmod ssl # enable mod_ssl $ a2enmod rewrite # enable mod_rewrite $ a2enmod expires # enable mod_expires @@ -457,7 +457,7 @@
Commands to enabl e the Evergreen site - $ sudo su - root + $ su - root $ a2dissite default # OPTIONAL: disable the default site (i.e., the "It Works" page). $ a2ensite eg.conf @@ -521,7 +521,7 @@ Modify the OpenSRF environment # change permissions - $ sudo su - opensrf + $ su - opensrf $ chmod 755 /openils/var/cgi-bin/*.cgi # add environmental variable @@ -535,7 +535,7 @@ 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.
-
+
Starting Evergreen @@ -543,7 +543,7 @@
Start some services - $ sudo su - root + $ su - root $ /etc/init.d/ejabberd start $ /etc/init.d/memcached start @@ -555,7 +555,7 @@
Start Evergreen - $ sudo su - opensrf + $ su - opensrf # ensure you have the needed path $ export PATH=$PATH:/openils/bin @@ -565,10 +565,8 @@ $ osrf_ctl.sh -l -a start_all
- - - Note: You can also start Evergreen without the -l flag, but it must know the fully qualified domain name for the system on which it will execute. That hostname would have been specified in the configuration file opensrf.xml, which you configured in a previous step. - [[ explanation needed for configuring opensrf.xml ]] + Note: You can also start Evergreen without the -l flag, but the utility osrf_ctl.sh must know the fully qualified domain name for the system on which it will execute. That hostname would have been specified in the configuration file opensrf.xml, which you configured in a previous step. + [[ explanation for configuring opensrf.xml ]] Execute the following command to determine the fully qualified domain name of your system:
(OPTIONAL) Determine the fully qualified domain name @@ -576,21 +574,18 @@ $ perl -e 'use Net::Domain qw(hostfqdn); print hostfqdn()."\n"'
- When you attempt to start Evergreen, 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 /home/opensrf/.bashrc and add the following line: export PATH=$PATH:/openils/bin - When you attempt to start Evergreen, 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 /home/opensrf/.bashrc and add the following line: export PERL5LIB=$PERL5LIB:/openils/lib/perl5 - 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'': + You need to do this the first time you start Evergreen, and after that each time you change the library hierarchy in ''config.cgi'':
Generate web files - $ sudo su - opensrf + $ 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' @@ -598,36 +593,155 @@ 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!!! - - [[ TEST THIS! ]] + [[ TEST THIS! ]]
As the root user, restart the Apache Web server: -
Generate web files - $ sudo su - root + $ su - root $ /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. -
-
- Testing Connections to the Server +
+ 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 + + $ 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 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. +
-
- Starting the Web Server +
+ 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: +
+ Running the Linux staff client + + $ su - opensrf + $ xulrunner /home/opensrf/Evergreen-ILS-1.6.0.7/Open-ILS/xul/staff_client/build/application.ini + +
-
- Stopping the Server +
+ Starting 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: +
+ Start the Apache Web Server + + $ su - root + $ apache2ctl configtest && /etc/init.d/apache2 restart + +
-
+
+ Stopping the Evergreen Services + As the opensrf user, stop all Evergreen services by using the following command: +
+ Stop all Evergreen services + + $ su - opensrf + + # stop the server: + # use "-l" to force hostname to be "localhost" + $ osrf_ctl.sh -l -a stop_all + +
+ Note: You can also stop Evergreen services without the -l flag, but the utility osrf_ctl.sh must know the fully qualified domain name for the system on which it will execute. That hostname would have been specified in the configuration file opensrf.xml, which you configured in a previous step. + [[ explanation for configuring opensrf.xml ]] +
+
Setting 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: +
+ Starting the Reporter Daemon + + $ su - opensrf + $ cd /home/opensrf/Evergreen-ILS-1.6.0.7/Open-ILS/src/reporter + $ ./clark-kent.pl --daemon + +
+ You can also specify other options with this utility: + + --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 + +
+
+ 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. Note: it is possible that several processes are running; see the optional commands in the previous section. As the opensrf user, perform the following commands to stop the Reporter daemon: +
+ Stopping the Reporter Daemon + + $ su - opensrf + # 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 + +
diff --git a/1.6/media/serversideinstallation-testing-1.png b/1.6/media/serversideinstallation-testing-1.png new file mode 100644 index 0000000..96b60ef Binary files /dev/null and b/1.6/media/serversideinstallation-testing-1.png differ diff --git a/1.6/media/serversideinstallation-testing-2.png b/1.6/media/serversideinstallation-testing-2.png new file mode 100644 index 0000000..dbe991d Binary files /dev/null and b/1.6/media/serversideinstallation-testing-2.png differ