From b142f354b2ef2c929e5860ed4eaff9e95d98c1f3 Mon Sep 17 00:00:00 2001 From: Steve Sheppard Date: Sat, 16 Apr 2011 18:02:32 -0400 Subject: [PATCH] updates to section 'Installing OpenSRF 1.6.3'; --- 2.0/admin/serversideinstallation_2.0.xml | 486 ++++++++++++++++++------------- 1 file changed, 287 insertions(+), 199 deletions(-) diff --git a/2.0/admin/serversideinstallation_2.0.xml b/2.0/admin/serversideinstallation_2.0.xml index 601a212..7b1b1bd 100644 --- a/2.0/admin/serversideinstallation_2.0.xml +++ b/2.0/admin/serversideinstallation_2.0.xml @@ -9,7 +9,9 @@ Installing, configuring and testing the Evergreen server-side software is straightforward with the current - stable software release. + 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). @@ -22,7 +24,9 @@ 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"). + "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: @@ -49,6 +53,26 @@ 1.6.3 8.4 + + 1.6.1.x + 1.4.0 + 8.2 / 8.3 + + + 1.6.0.x + 1.2 + 8.2 / 8.3 + + + 1.4.x + 1.0 + 8.1 / 8.2 + + + 1.2.x + 0.9 + 8.1 / 8.2 + @@ -88,10 +112,11 @@ 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.6.3 has been tested on Debian Lenny (5.0), Debian Squeeze (6.0) - and Ubuntu Lucid Lynx (10.04), Debian Lenny (5.0), - CentOS 5, Red Hat Enterprise Linux 5. + The following steps have been tested on the x86 (32-bit) architecture of + Debian Squeeze (6.0), + Ubuntu Lucid Lynx (10.04), and on + Fedora 13 and + Fedora 14. In the following instructions, you are asked to perform certain steps as either the root user, the opensrf user, or the @@ -126,12 +151,12 @@ In the following example, the default shell for the opensrf user is automatically set to /bin/bash to inherit a reasonable environment: - - + + # as the root user: useradd -m -s /bin/bash opensrf passwd opensrf - + Download and Unpack Latest OpenSRF Version @@ -145,13 +170,13 @@ the directory /home/opensrf then download and extract OpenSRF. The new subdirectory /home/opensrf/OpenSRF-1.6.3 will be created: - - + + # as the opensrf user: cd /home/opensrf wget http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz tar zxf OpenSRF-1.6.3.tar.gz - + Install Prerequisites to Build OpenSRF @@ -162,35 +187,82 @@ 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 listed distributions. + Linux distributions listed in the + distribution keywords table . For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would enter this command: make -f src/extras/Makefile.install ubuntu-lucid . - - + + # as the root user: cd /home/opensrf/OpenSRF-1.6.3 make -f src/extras/Makefile.install [DISTRIBUTION] - - - - for Debian Squeeze (6.0) - LinuxDebian - - - for Fedora 13 - LinuxFedora - - - for Ubuntu Lucid Lynx - (10.04) - - - for CentOS 5 - - - for Red Hat Enterprise Linux 5 - - + + + + Keyword Targets for OpenSRF <application>"make"</application> Command + + + + + + Keyword + Linux Version + + + + + debian-squeeze + Debian "Squeeze" (6.0) + + + debian-etch + Debian "Etch" (4.0) + + + debian-lenny + Debian "Lenny" (5.0) + + + ubuntu-hardy + Ubuntu "Hardy Heron" (8.04) + + + ubuntu-karmic + Ubuntu "Karmic Koala" (9.10) + + + ubuntu-lucid + Ubuntu "Lucid Lynx" (10.04) + + + fedora13 + Fedora "Goddard" (13) + + + fedora13 + Fedora "Laughlin" (14) + + + centos + CentOS 5 + + + rhel + Red Hat Enterprise Linux 5 + + + gentoo + Gentoo + + + +
+ LinuxDebian + LinuxFedora + LinuxUbuntu + LinuxCentOS + LinuxRed Hat + LinuxGentoo This will install a number of packages on the system that are required by OpenSRF, including some Perl modules from CPAN. You can say No to the initial CPAN configuration prompt to allow it to automatically configure itself to download and @@ -215,13 +287,13 @@ include support for Python and Java, add the configuration options and , respectively: - - + + # as the opensrf user: cd /home/opensrf/OpenSRF-1.6.3 ./configure --prefix=/openils --sysconfdir=/openils/conf make - + This step will take several minutes to complete. @@ -230,12 +302,12 @@ user, return to the new OpenSRF build directory and use the make utility to compile, link and install OpenSRF: - - + + # as the root user: cd /home/opensrf/OpenSRF-1.6.3 make install - + This step will take several minutes to complete. @@ -244,16 +316,17 @@ 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 + /etc/ld.so.conf.d/osrf.conf containing two + new library paths, then execute the command ldconfig to automatically read the file and modify the system dynamic library path: - - + + # as the root user: - echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf + echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf + echo "/usr/local/lib >> /etc/ld.so.conf.d/osrf.conf ldconfig - + Define Public and Private OpenSRF Domains @@ -272,12 +345,12 @@ Jabber - - + + # as the root user: 127.0.1.2 public.localhost public 127.0.1.3 private.localhost private - + Change File Ownerships @@ -285,11 +358,11 @@ user, change the ownership of all files installed in the directory /openils to the user opensrf: - - + + # as the root user: chown -R opensrf:opensrf /openils - + @@ -301,25 +374,25 @@ Before continuing with configuration of ejabberd you must stop that service. As the root user, execute the following command to stop the service: - - + + # as the root user: /etc/init.d/ejabberd stop - + If ejabberd reports that it is already stopped, there may have been a problem when it started back in the installation step. If there are any remaining daemon processes such as beam or epmd you may need to perform the following commands to kill them: - - + + # as the root user: epmd -kill killall beam; killall beam.smp rm /var/lib/ejabberd/* echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd - + Edit the <systemitem class="service">ejabberd</systemitem> configuration @@ -337,14 +410,14 @@ - Change the line: + Change the line for older versions of ejabberd: {max_user_sessions, 10} to instead read: {max_user_sessions, 10000} - If the line looks something like this: + Change the line for newer versions of ejabberd: {access, max_user_sessions, [{10, all}]} - then change it to instead read: + to instead read: {access, max_user_sessions, [{10000, all}]} @@ -373,11 +446,11 @@ As the root user, restart the ejabberd service to test the configuration changes and to register your users: - - + + # as the root user: /etc/init.d/ejabberd start - + Register <systemitem class="username">router</systemitem> and @@ -410,8 +483,8 @@ for the users <systemitem class="username">router</systemitem> and <systemitem class="username">opensrf</systemitem> on each domain (remember to replace <emphasis>NEWPASSWORD</emphasis> with the appropriate password):</para> - <screen> - <userinput> +<screen> + <userinput> # as the root user: # Note: the syntax for registering a user with ejabberdctl is: # ejabberdctl register USER DOMAIN PASSWORD @@ -419,11 +492,22 @@ ejabberdctl register router public.localhost NEWPASSWORD ejabberdctl register opensrf private.localhost NEWPASSWORD ejabberdctl register opensrf public.localhost NEWPASSWORD</userinput> - </screen> - <para>Note that the users <systemitem class="username">router</systemitem> and +</screen> + <para>The users <systemitem class="username">router</systemitem> and <systemitem class="username">opensrf</systemitem> and their respective passwords will be used again in <xref linkend="serversideinstallation-passwords"/> when we modify the OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename> .</para> + <note> + <para> + There appears to be a problem with <command>ejabberdctl</command> in + that it does not escape input correctly, so a password like + <literal>'0P3N$SRF'</literal> will be created as <literal>'0P3N'</literal>. + A bug against ejabberd has been filed. To register a password using + <command>ejabberdctl</command> with special shell characters until such + time as that bug is resolved, the workaround is to specify a + double-escaped character at the command line, for example, + <literal>'0P3N\\\\$RF'</literal> .</para> + </note> </step> <step xml:id="serversideinstallation-opensrf-createconfig"> <title>Create OpenSRF configuration files @@ -431,13 +515,13 @@ execute the following commands to create the new configuration files /openils/conf/opensrf_core.xml and /openils/conf/opensrf.xml from the example templates: - - + + # as the opensrf user: cd /openils/conf cp opensrf.xml.example opensrf.xml cp opensrf_core.xml.example opensrf_core.xml - + Update usernames and passwords in the OpenSRF configuration file @@ -530,11 +614,11 @@ to match values for your own systems. - Set location of the persistent database + Set the 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. Change the default line: + file /openils/conf/opensrf.xml, then find and verify that + the element dbfile (near the end of the file) is set to the + location of the persistent database. If necessary, change the default line: /openils/var/persist.db to instead read: /tmp/persist.db @@ -557,8 +641,8 @@ srfsh The software installation will automatically create the utility - srfsh (surf shell), a command line diagnostic tool for - testing and interacting with OpenSRF. It will be used + srfsh, a command line diagnostic tool for testing and + interacting with OpenSRF. It will be used in a future step to complete and test the Evergreen installation. See for further information. As the root user, copy the @@ -566,11 +650,11 @@ to the home directory of each user who will use srfsh. For instance, do the following for the opensrf user: - - + + # as the root user: cp /openils/conf/srfsh.xml.example /home/opensrf/.srfsh.xml - + Edit each user's file ~/.srfsh.xml and make the following changes: @@ -624,33 +708,33 @@ environmental variable PATH by adding a new file path to the opensrf user's shell configuration file ~/.bashrc: - - + + # as the opensrf user: echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc - + Start OpenSRF As the root user, start the ejabberd and memcached services: - - + + # as the root user: /etc/init.d/ejabberd start /etc/init.d/memcached start - - As the opensrf user, + + Then as the opensrf user, start OpenSRF as follows: - - + + # as the opensrf user: osrf_ctl.sh -l -a start_all - + The flag forces Evergreen to use localhost (your current system) - as the hostname. The flag starts the other + as the hostname. The flag starts the OpenSRF router , Perl , and C services. @@ -678,23 +762,23 @@ 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 + root user test your connection to + OpenSRF with the srfsh + utility and try to call the add method on the OpenSRF math service: - - + + # as the root user: /openils/bin/srfsh - + srfsh# request opensrf.math add 2 2 - + Received Data: 4 ------------------------------------ Request Completed Successfully Request Time in seconds: 0.007519 ------------------------------------ - + For other srfsh commands, type in help at the prompt. @@ -704,11 +788,11 @@ osrf_ctl.sh again. As the opensrf user, stop OpenSRF as follows: - - + + # as the opensrf user: osrf_ctl.sh -l -a stop_all - + @@ -781,13 +865,13 @@ the directory /home/opensrf then download and extract Evergreen. The new subdirectory /home/opensrf/Evergreen-ILS-2.0.4 will be created: - - + + # as the opensrf user: cd /home/opensrf wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz tar zxf Evergreen-ILS-2.0.4.tar.gz - + Install Prerequisites to Build Evergreen @@ -804,12 +888,12 @@ For example, to install the prerequisites for Ubuntu version 10.05 (Lucid Lynx) you would enter this command: make -f Open-ILS/src/extras/Makefile.install ubuntu-lucid. - - + + # as the root user: cd /home/opensrf/Evergreen-ILS-2.0.4 make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION] - + @@ -859,17 +943,17 @@ modules: as the root user, ensure the gcc compiler is installed: -aptitude install gcc libxml-libxml-perl libxml-libxslt-perl + aptitude install gcc libxml-libxml-perl libxml-libxslt-perl then install the Perl modules: -perl -MCPAN -e shell -cpan> Business::ISBN -cpan> install JSON::XS -cpan> Library::CallNumber::LC -cpan> install MARC::Record -cpan> install MARC::File::XML -cpan> cpan UUID::Tiny + perl -MCPAN -e shell + cpan> Business::ISBN + cpan> install JSON::XS + cpan> Library::CallNumber::LC + cpan> install MARC::Record + cpan> install MARC::File::XML + cpan> cpan UUID::Tiny For more information on installing Perl Modules vist the official CPAN site. @@ -885,13 +969,13 @@ do this by creating the new file /etc/ld.so.conf.d/osrf.conf containing a new library path, then run the command ldconfig to automatically read the file and modify the system dynamic library path: - - + + # as the root user: echo "/usr/local/lib" >> /etc/ld.so.conf.d/osrf.conf echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf ldconfig - + Restart the PostgreSQL Server @@ -903,11 +987,11 @@ execute the following command (remember to replace PGSQL_VERSION with your installed PostgreSQL version, for example 8.4): - - + + # as the opensrf user: /etc/init.d/postgresql-PGSQL_VERSION restart - + Configure Evergreen @@ -916,13 +1000,13 @@ and linked later in . As the opensrf user, return to the Evergreen build directory and execute these commands: - - + + # as the opensrf user: cd /home/opensrf/Evergreen-ILS-2.0.4 ./configure --prefix=/openils --sysconfdir=/openils/conf make - + Compile, Link and Install Evergreen @@ -930,12 +1014,12 @@ default Evergreen Staff Client. As the root user, return to the Evergreen build directory and use the make utility as shown below: - - + + # as the root user: cd /home/opensrf/Evergreen-ILS-2.0.4 make STAFF_CLIENT_BUILD_ID=rel_2_0_4 install - + The Staff Client will also be automatically built, but you must remember to set the variable STAFF_CLIENT_BUILD_ID to match the version of the Staff Client you will use to connect to the Evergreen server. @@ -948,12 +1032,12 @@ directory /openils/var/web/xul that points to the subdirectory /server of the new Staff Client build: - - + + # as the root user: cd /openils/var/web/xul ln -sf rel_2_0_4/server server - + Copy the OpenSRF Configuration Files @@ -965,8 +1049,8 @@ to opensrf. As the root user, execute the following commands: - - + + # as the root user: cd /openils/conf cp opensrf.xml opensrf.xml.BAK @@ -975,7 +1059,7 @@ 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 @@ -999,25 +1083,25 @@ As the postgres user on the PostgreSQL system create the PostgreSQL database, then set some internal paths: - - + + # as the postgres user: createdb evergreen -E UTF8 -T template0 createlang plperl evergreen createlang plperlu evergreen createlang plpgsql evergreen - + Continue as the postgres user and execute the SQL scripts as shown below (remember to adjust the paths as needed, where PGSQL_VERSION is your installed PostgreSQL version, for example 8.4). - - + + # as the postgres user: psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen - + Create <systemitem class="username">evergreen</systemitem> PostgreSQL user @@ -1026,14 +1110,14 @@ named evergreen and assign a password (remember to replace NEWPASSWORD with an appropriate new password): - - + + # as the postgres user: createuser -P -s evergreen - + Enter password for new role: NEWPASSWORD Enter it again: NEWPASSWORD - + Create database schema @@ -1094,13 +1178,13 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ Apache modules - - + + # as the root user: a2enmod ssl # enable mod_ssl a2enmod rewrite # enable mod_rewrite a2enmod expires # enable mod_expires - + As the commands execute, you may see warnings similar to: Module SOMEMODULE already enabled but you can safely ignore them. @@ -1111,14 +1195,14 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ Evergreen installation directory to the Apache directory. As the root user, perform the following commands: - - + + # as the root user: cd /home/opensrf/Evergreen-ILS-2.0.4 cp Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/ cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/ cp Open-ILS/examples/apache/startup.pl /etc/apache2/ - + Create a Security Certificate @@ -1129,13 +1213,13 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ accept the warnings in the Staff Client and browser during testing and development. As the root user, perform the following commands: - - + + # as the root user: mkdir /etc/apache2/ssl cd /etc/apache2/ssl openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key - + You will be prompted for several items of information; enter the appropriate information for each item. The new files server.crt and server.key will @@ -1191,11 +1275,11 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ export APACHE_RUN_GROUP=www-data to instead read: - - + + export APACHE_RUN_USER=opensrf export APACHE_RUN_GROUP=opensrf - + As the @@ -1205,11 +1289,11 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ modify the value for KeepAliveTimeout and MaxKeepAliveRequests to match the following: - - + + KeepAliveTimeout 1 MaxKeepAliveRequests 100 - + Further configuration changes to Apache may be @@ -1242,15 +1326,15 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ following Apache configuration commands to disable the default It Works web page and enable the Evergreen web site, and then restart the Apache server: - - + + # as the root user: # disable/enable web sites a2dissite default a2ensite eg.conf # restart the server /etc/init.d/apache2 reload - + @@ -1367,12 +1451,12 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ before the line [ -z "$PS1" ] && return . This will allow headless (scripted) logins to load the correct environment. - - + + # as the opensrf user: echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc . ~/.bashrc - + @@ -1385,6 +1469,10 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ +
+ Installing Evergreen 2.x On <systemitem class="osname">Fedora 13</systemitem> or + <systemitem class="osname">Fedora 14</systemitem> +
Starting Evergreen In this section you will learn how to start the Evergreen services. @@ -1395,24 +1483,24 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ As the root user, start the ejabberd and memcached services as follows: - - + + # as the root user: /etc/init.d/ejabberd start /etc/init.d/memcached start - + As the opensrf user, - start Evergreen as follows: - - + start the OpenSRF router service as follows: + + # as the opensrf user: osrf_ctl.sh -l -a start_all - - The flag forces Evergreen to use + + The flag forces Evergreen to use localhost (your current system) - as the hostname. The flag starts the other + as the hostname. The flag starts the OpenSRF router , Perl , and C services. @@ -1456,12 +1544,12 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ changes to the library hierarchy. As the opensrf user, execute the following command and review the results: - - + + # as the opensrf user: cd /openils/bin ./autogen.sh -c /openils/conf/opensrf_core.xml -u - + Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml' Updating fieldmapper Updating web_fieldmapper @@ -1478,16 +1566,16 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ Refreshing proximity of org units Successfully updated the organization proximity Done - + As the root user, restart the Apache Web server: - - + + # as the root user: /etc/init.d/apache2 restart - + If the Apache Web server was running when you started the OpenSRF services, you might not be able to successfully log into the OPAC or Staff Client until the Apache Web server has been restarted. @@ -1508,11 +1596,11 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ srfsh commands, type help at the prompt. As the opensrf user, execute the following commands to test your Evergreen connection: - - + + # as the opensrf user: /openils/bin/srfsh - + srfsh% login admin open-ils Received Data: "250bf1518c7527a03249858687714376" ------------------------------------ @@ -1534,19 +1622,19 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ Request Completed Successfully Request Time in seconds: 1.336568 ------------------------------------ - + If this does not work, try the following: As the opensrf user, run the settings-tester.pl utility to review your Evergreen installation for any system configuration problems: - - + + # as the opensrf user: cd /home/opensrf ./Evergreen-ILS-2.0.4/Open-ILS/src/support-scripts/settings-tester.pl - + If the output of settings-tester.pl does not help you find the problem, please do not make any significant changes to your configuration. @@ -1574,11 +1662,11 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ version 3.0 and later on Ubuntu and Debian distributions). As the root user, start the Staff Client as shown: - - + + # as the root user: xulrunner /home/opensrf/Evergreen-ILS-v/Open-ILS/xul/staff_client/build/application.ini - + A login screen for the Staff Client similar to this should appear: Logging into the Staff Client @@ -1622,11 +1710,11 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ commands. Note the use of restart to force the new Evergreen modules to be reloaded even if the Apache server is already running. Any problems found with your configuration files should be displayed: - - + + # as the root user: apache2ctl configtest && /etc/init.d/apache2 restart - + Stopping Evergreen @@ -1635,12 +1723,12 @@ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \ Evergreen services. As the opensrf user, stop all Evergreen services by using the following command: - - + + # as the opensrf user # stop the server; use "-l" to force hostname to be "localhost" osrf_ctl.sh -l -a stop_all - + You can also stop Evergreen services without the flag, but the osrf_ctl.sh utility must know the fully qualified domain name for the system on which it will execute. That hostname may -- 2.11.0