</section>
<section>
<title>Define Public and Private OpenSRF Domains</title>
- <para>Define your public and private OpenSRF domains. For security purposes, OpenSRF uses Jabber domains to separate services into public and private realms. Throughout these instructions, we will use the example domains <systemitem class="domainname">public.localhost</systemitem> for the public domain and <systemitem class="domainname">private.localhost</systemitem> for the private domain. On a single-server system, the easiest way to define public and private domains is to define separate hostnames by adding entries to the file <filename>/etc/hosts</filename>.</para>
+ <para>Define your public and private OpenSRF domains. For security purposes, OpenSRF uses Jabber domains to separate services into public and private realms. Throughout these instructions, we will use the example domains <systemitem class="domainname">public.localhost</systemitem> for the public domain and <systemitem class="domainname">private.localhost</systemitem> for the private domain. On a single-server system, the easiest way to define public and private domains is to define separate host names by adding entries to the file <filename>/etc/hosts</filename>.</para>
<para>As the <systemitem class="username">root</systemitem> user, edit the file <filename>/etc/hosts</filename> and add the following entries for our example domains:</para>
<figure>
<title>Example public and private domains in /etc/hosts</title>
<para>Edit the file <filename>/openils/conf/opensrf_core.xml</filename> to change the <systemitem class="service">ejabberd</systemitem> usernames and passwords as follows.</para>
<note>
<para>
- <emphasis>The following example uses common XPath syntax on the left-hand side to indicate the approximage position needing changes within the XML file.</emphasis>
+ <emphasis>The following example uses common XPath syntax on the left-hand side to indicate the approximate position needing changes within the XML file.</emphasis>
</para>
</note>
<figure>
</figure>
<note>
<para>
- <emphasis>PostgreSQL 8.1 is deprecated and will become unsupported in a future release, though existing installations upgrading from Evergreen 1.4 or before will work fine. However, consider upgrading your Postgres soon!</emphasis>
+ <emphasis>PostgreSQL 8.1 is deprecated and will become unsupported in a future release, though existing installations upgrading from Evergreen 1.4 or before will work fine. However, consider upgrading your PostgreSQL installation soon!</emphasis>
</para>
</note>
<indexterm>
</itemizedlist>
</step>
<step>
- <para>As the <systemitem class="username">opensrf</systemitem> 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 <emphasis>Holds</emphasis> to work properly).</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, generate the Web files needed by the Staff Client and catalog, and calculate the proximity of locations in the Organizational Unit tree (which allows <emphasis>Holds</emphasis> to work properly).</para>
<para>You must do this the first time you start Evergreen, and after making any changes to the library hierarchy in the configuration file <filename>config.cgi</filename>.</para>
<figure>
<title>Commands to generate web files</title>
<section xml:id="serversideinstallation-testing-opac">
<title>Testing the Catalog</title>
<para>By default, the OPAC will live at the URL <uri>http://my.domain.com/opac/</uri>.</para>
- <para>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 hight
ly reccommend testing with the <application>Firefox</application> browser because of the helpful javascript debugging tools.</para>
+ <para>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 hight
y recommend testing with the <application>Firefox</application> browser because of the helpful javascript debugging tools.</para>
<para>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).</para>
<indexterm>
<primary>ZZZ-REVIEW</primary>
</section>
<section>
<title>Define Public and Private OpenSRF Domains</title>
- <para>Define your public and private OpenSRF domains. For security purposes, OpenSRF uses Jabber domains to separate services into public and private realms. Throughout these instructions, we will use the example domains <systemitem class="domainname">public.localhost</systemitem> for the public domain and <systemitem class="domainname">private.localhost</systemitem> for the private domain. On a single-server system, the easiest way to define public and private domains is to define separate hostnames by adding entries to the file <filename>/etc/hosts</filename>.</para>
+ <para>Define your public and private OpenSRF domains. For security purposes, OpenSRF uses Jabber domains to separate services into public and private realms. Throughout these instructions, we will use the example domains <systemitem class="domainname">public.localhost</systemitem> for the public domain and <systemitem class="domainname">private.localhost</systemitem> for the private domain. On a single-server system, the easiest way to define public and private domains is to define separate host names by adding entries to the file <filename>/etc/hosts</filename>.</para>
<para>As the <systemitem class="username">root</systemitem> user, edit the file <filename>/etc/hosts</filename> and add the following entries for our example domains:</para>
<figure>
<title>Example public and private domains in /etc/hosts</title>
<para>This section reviews the process of installing pre-built versions of the Staff Client in various environments.</para>
<section>
<title>Installing on <systemitem class="osname">Windows</systemitem></title>
- <para>A standard <systemitem class="osname">Windows</systemitem> installer that contains the current version of the Staff Client is available from the downloads section of the Evergreen website at <ulink url="http://www.evergreen-ils.org/downloads.php">http://www.evergreen-ils.org/downloads.php</ulink>. Download the staff client installer, then run it. A screen that looks similar to this should appear:</para>
+ <para>A standard <systemitem class="osname">Windows</systemitem> installer that contains the current version of the Staff Client is available from the downloads section of the Evergreen website at <ulink url="http://www.evergreen-ils.org/downloads.php">http://www.evergreen-ils.org/downloads.php</ulink>. Download the Staff Client installer, then run it. A screen that looks similar to this should appear:</para>
<figure>
<title>Running the Staff Client installer</title>
<mediaobject>
</mediaobject>
</figure>
<para>Click <guibutton>Next</guibutton> to continue through the guided install process. The install wizard will ask you to agree to the end-user license, ask you where to install the software, ask about where to place icons, and then will install the software on your workstation.</para>
- <para>When you run the staff client for the first time, a screen similar to this should appear:</para>
+ <para>When you run the Staff Client for the first time, a screen similar to this should appear:</para>
<figure>
<title>Running the Staff Client for the first time</title>
<mediaobject>
</mediaobject>
</figure>
<para>First, configure the server you would like to connect to in the <emphasis role="bold">Server</emphasis> section. For example, the PINES demo system is <systemitem class="domain">demo.gapines.org</systemitem>. After selecting a server, click <guibutton>Re-Test Server</guibutton>.</para>
- <para>Because this is the initial run of the staff client, the <emphasis role="bold">Workstation</emphasis> section in the upper-right states: <emphasis role="bold">Not yet configured for the specified server</emphasis>. The first thing that must be done to the Staff Client on every workstation is to assign it a workstation name. This is covered in <xref linkend="serversideinstallation-workstationnames"/>.</para>
+ <para>Because this is the initial run of the Staff Client, the <emphasis role="bold">Workstation</emphasis> section in the upper-right states: <emphasis role="bold">Not yet configured for the specified server</emphasis>. The first thing that must be done to the Staff Client on every workstation is to assign it a workstation name. This is covered in <xref linkend="serversideinstallation-workstationnames"/>.</para>
</section>
<section>
<title>Installing on <systemitem class="osname">Mac OS X</systemitem></title>
<procedure>
<step>Download and install the latest version of <application>xulrunner</application> for <systemitem class="osname">Mac OS X</systemitem>. Release notes for the latest version can be found here: <ulink url="http://developer.mozilla.org/en/docs/XULRunner_1.8.0.4_Release_Notes">http://developer.mozilla.org/en/docs/XULRunner_1.8.0.4_Release_Notes</ulink>. Note, later versions may not work correctly.</step>
<step>Download and install the <systemitem class="osname">Mac OS X</systemitem> Installation package for the 1_2_3_0 Version Staff Client from <ulink url="http://evergreen.lib.in.us/opac/extras/files/evergreen_osx_staff_client_1_2_3.zip">http://evergreen.lib.in.us/opac/extras/files/evergreen_osx_staff_client_1_2_3.zip</ulink>.</step>
- <step>To upgrade to a more recent version of the staff client, you can copy the directory <emphasis>build</emphasis> from a working <systemitem class="osname">Windows</systemitem> installation of the desired version of the staff client to your Mac. The required files may be located in a directory like this on the <systemitem class="osname">Windows</systemitem> machine: <filename class="directory">C:\Program Files\Evergreen Staff Client\build</filename>. Copy these files into the folder <filename class="directory">Resources</filename> within the Open-ILS package in your Applications directory on the Mac, overwriting files with the same names.</step>
+ <step>To upgrade to a more recent version of the Staff Client, you can copy the directory <emphasis>build</emphasis> from a working <systemitem class="osname">Windows</systemitem> installation of the desired version of the Staff Client to your Mac. The required files may be located in a directory like this on the <systemitem class="osname">Windows</systemitem> machine: <filename class="directory">C:\Program Files\Evergreen Staff Client\build</filename>. Copy these files into the folder <filename class="directory">Resources</filename> within the Open-ILS package in your Applications directory on the Mac, overwriting files with the same names.</step>
<step>Drag the application's icon into your toolbar for easier access.</step>
</procedure>
<para/>
- <para>When you run the staff client installer, a screen will appear that looks similar to this:</para>
+ <para>When you run the Staff Client installer, a screen will appear that looks similar to this:</para>
<figure>
<title>Running the Staff Client installer</title>
<mediaobject>
</section>
<section>
<title>Running directly using <application>xulrunner</application></title>
- <para>You must install an apropriate version of <application>xulrunner</application> to match the Evergreen version. See the following table for the recommended version of <application>xulrunner</application>:</para>
+ <para>You must install an ap
propriate version of <application>xulrunner</application> to match the Evergreen version. See the following table for the recommended version of <application>xulrunner</application>:</para>
<table>
<title>Evergreen / XULRunner Dependencies</title>
<tgroup align="left" cols="2" colsep="1" rowsep="1">
</tgroup>
</table>
<note>If you have issues removing previously installed <application>xulrunner</application> versions see <xref linkend="serversideinstallation-staffclient-remove-xulrunner"/> for information on removing previous <application>XULRunner</application> versions.</note>
- <para>The
staff client data from the directory <filename class="directory">./staff_client/build</filename> must be placed somewhere on the machine (e.g. <emphasis>~/Desktop/Evergreen_Staff_Client</emphasis>). Remember to call <application>XULRunner</application> with the full path to the binary, followed by the install command and the path to the client data. See the following command:</para>
+ <para>The
Staff Client data from the directory <filename class="directory">./staff_client/build</filename> must be placed somewhere on the machine (e.g. <emphasis>~/Desktop/Evergreen_Staff_Client</emphasis>). Remember to call <application>XULRunner</application> with the full path to the binary, followed by the install command and the path to the client data. See the following command:</para>
<figure>
<title>Executing <application>xulrunner</application></title>
<screen>
</section>
<section>
<title>Creating an APP file: Staff Client & <application>xulrunner</application> Bundled</title>
- <para>An APP file is basically a folder. Start with a folder stucture like this:</para>
+ <para>An APP file is basically a folder. Start with a folder structure like this:</para>
<figure>
<title>Sample APP file folder structure</title>
<screen>
<section>
<title>Building the Staff Client on the Server</title>
<para>A <systemitem class="osname">Linux</systemitem> Staff Client is automatically built on the server as part of the normal <emphasis>make install</emphasis> process for Evergreen server-side software.</para>
- <para>In order to install a compatible Staff Client on another <systemitem class="osname">Linux</systemitem> system, just copy the applicable files from the server to that system, or even manually build it on that system. Ensure that the BUILD_ID you choose on the server matches the BUILD_ID for each staff client you use on other systems.</para>
+ <para>In order to install a compatible Staff Client on another <systemitem class="osname">Linux</systemitem> system, just copy the applicable files from the server to that system, or even manually build it on that system. Ensure that the BUILD_ID you choose on the server matches the BUILD_ID for each Staff Client you use on other systems.</para>
<para>If you will be using a pre-packaged <systemitem class="osname">Windows</systemitem> version on some systems, you may want to choose the BUILD_ID on both server and other versions to match that of the <systemitem class="osname">Windows</systemitem> Staff Client. To determine which BUILD_ID is used in an existing Staff Client installation, just click <guibutton>About this Client</guibutton> on the running Staff Client.</para>
<para>If you are allowed to make changes on the Evergreen server, another option is to create a symbolic link. In order for a copy of the Staff Client and server to work together, the BUILD_ID must match the name of the directory containing the server components of the Staff Client, or the name of a symbolic link to that directory.</para>
<figure>
<itemizedlist>
<listitem>
<para>Determine which version is needed</para>
- <para>For most end-users, a specific version is required to communicate properly with the Evergreen server. Check with your system admininstrator, IT person, or HelpDesk to determine which Staff Client versions are supported.</para>
+ <para>For most end-users, a specific version is required to communicate properly with the Evergreen server. Check with your system administrator, IT person, or HelpDesk to determine which Staff Client versions are supported.</para>
<para>Next, you need to determine which <emphasis>tag</emphasis> to use when downloading the source code. Tags are markers in the source code to create a snapshot of the code as it existed at a certain time; tags usually point to tested and stable code, or at least a community-recognized release version.</para>
<para>To determine which tag to use, browse to <ulink url="http://svn.open-ils.org/trac/ILS/browser">http://svn.open-ils.org/trac/ILS/browser</ulink>. Look in the <guibutton>Visit</guibutton> drop-down box; see the list of Branches and, further down, a list of Tags. You may have to do some guesswork, but it is fairly straightforward to determine which tag to use. If the server is version 1.2.1.4, you will want to use the tag that looks most appropriate. For example, as you look through the tag list, notice the tag named 'rel_1_2_1_4'. This is the tag you need; make a note of it for the next step.</para>
</listitem>
</step>
<step>
<para>(OPTIONAL) Cleaning Up / Creating Shortcuts</para>
- <para>The source code download included many files that are needed to build the Staff Client, but are not necessary to run it. You may wish to remove them to save space, or to create a clean directory containing the built staff client that can be copied to other machines. To create a clean "staging" directory in which to place the finished staff client, issue the following commands:</para>
+ <para>The source code download included many files that are needed to build the Staff Client, but are not necessary to run it. You may wish to remove them to save space, or to create a clean directory containing the built Staff Client that can be copied to other machines. To create a clean "staging" directory in which to place the finished Staff Client, issue the following commands:</para>
<figure>
<title>Creating a "staging" directory</title>
<screen>
</section>
<section>
<title>Packaging the Staff Client</title>
- <para>Once the Staff Client has been built, you can create several forms of client packages by using some targetted <command>make</command> commands in the Staff Client source directory.</para>
+ <para>Once the Staff Client has been built, you can create several forms of client packages by using some targeted <command>make</command> commands in the Staff Client source directory.</para>
<itemizedlist>
<listitem>
<para>Packaging a Generic Client</para>
</listitem>
<listitem>
<para>During a manual Staff Client build process</para>
- <para>You will used the variable AUTOUPDATE_HOST=hostname (see above). If you specify just a hostname (such as <uri>example.com</uri>) then the URL will be a secure URL (such as <uri>https://example.com</uri>. If you wish to use a non-HTTPS URL then prefix the hostname with "http://" (such as <uri>http://example.com</uri>).</para>
+ <para>You will used the variable AUTOUPDATE_HOST=hostname (see above). If you specify just a hostname (such as <uri>example.com</uri>) then the URL will be a secure URL (such as <uri>https://example.com</uri>. If you wish to use a non-HTTPS URL then prefix the host name with "http://" (such as <uri>http://example.com</uri>).</para>
<para>If neither option is used then, by default, the Staff Client will not include the automatic update preferences.</para>
</listitem>
</itemizedlist>
<section>
<title> Multiple Staff Clients</title>
<para>This may be confusing if you are not careful, but you can log in to multiple Evergreen servers at the same time, or a single Evergreen server multiple times. In either case you will need to create an additional profile for each additional server or workstation you want to log in as (see previous tip).</para>
- <para>Once you have created the profiles, run <emphasis>XULRunner</emphasis> with the option <option>-no-remote</option> (in addition to <option>-profilemanger</option> or <option>-P</option> if neeeded). Instead of <emphasis>XULRunner</emphasis> opening a new login window on your existing session it will start a new session instead, which can then be logged in to a different server or workstation ID.</para>
+ <para>Once you have created the profiles, run <emphasis>XULRunner</emphasis> with the option <option>-no-remote</option> (in addition to <option>-profilemanger</option> or <option>-P</option> if needed). Instead of <emphasis>XULRunner</emphasis> opening a new login window on your existing session it will start a new session instead, which can then be logged in to a different server or workstation ID.</para>
</section>
</section>
</section>
</section>
<section xml:id="serversideinstallation-proxy">
<title>Configuring a Proxy for the Staff Client</title>
- <para>By using an SSH proxy and an SSH tunnel, it is possible to provide secure (encrypted) network communications between the Staff Client and one or more Evergreen servers. In addition to providing excellent data security, this method also buffers and caches data travelling to and from the Staff Client and can speed up access to resources on remote Evergreen servers. This is important if your system architecture includes many Staff Clients and Evergreen servers in a busy environment, through network firewalls, or must operate over unsecure networks.</para>
+ <para>By using an SSH proxy and an SSH tunnel, it is possible to provide secure (encrypted) network communications between the Staff Client and one or more Evergreen servers. In addition to providing excellent data security, this method also buffers and caches data traveling to and from the Staff Client and can speed up access to resources on remote Evergreen servers. This is important if your system architecture includes many Staff Clients and Evergreen servers in a busy environment, through network firewalls, or must operate over insecure networks.</para>
<section>
<title>Why Use a Proxy for the Staff Client?</title>
<para>There are several reasons for sending network traffic for the Staff Client through an SSH proxy:</para>
projects / contrib / Conifer.git / commitdiff