From: Steve Sheppard <ssheps@gmail.com> Date: Mon, 20 Dec 2010 17:10:19 +0000 (-0500) Subject: updates to Staff Client Installation; X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=56e6a3aeaeb43a99d3b0579faa82f80173200d4e;p=evergreen%2Fmasslnc.git updates to Staff Client Installation; --- diff --git a/1.6/admin/serversideinstallation.xml b/1.6/admin/serversideinstallation.xml index 4753e265e1..8f0c12cd89 100644 --- a/1.6/admin/serversideinstallation.xml +++ b/1.6/admin/serversideinstallation.xml @@ -1037,10 +1037,8 @@ <userinput>make STAFF_CLIENT_BUILD_ID=rel_1_6_1_2 install</userinput> </screen> <para>The Staff Client will also be automatically built, but you must remember - to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the Staff - Client you will use to connect to the Evergreen server. For further information on manually - building the Staff Client, see - <xref linkend="staffclientinstallation-building-staffclient"/>.</para> + to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the + Staff Client you will use to connect to the Evergreen server.</para> <para>The above commands will create a new subdirectory <filename class="directory">/openils/var/web/xul/rel_1_6_1_2</filename> containing the Staff Client.</para> @@ -1063,7 +1061,7 @@ tested OpenSRF.</para> <para>You must copy several example OpenSRF configuration files into place after first creating backup copies for troubleshooting purposes, then change all the file ownerships - to <systemitem class="username">opensrf</systemitem>. + to <systemitem class="username">opensrf</systemitem>. As the <systemitem class="username">root</systemitem> user, execute the following commands:</para> <screen> @@ -1270,7 +1268,7 @@ <para>Comment out the line <literal>Listen 443</literal>, since it conflicts with the same declaration in the configuration file: - <filename>/etc/apache2/ports.conf</filename>. Note that + <filename>/etc/apache2/ports.conf</filename>. Note that <systemitem class="osname">Debian </systemitem> users should not do this since the conflict does not apply to that operating system.</para> @@ -1463,26 +1461,40 @@ </step> <step xml:id="serversideinstallation-opensrf-env"> <title>Modify the OpenSRF Environment</title> - <para>As the <systemitem class="username">opensrf</systemitem> user, - modify the shell configuration file <filename>~/.bashrc</filename> for - user <systemitem class="username">opensrf</systemitem> by adding a Perl environmental - variable, then execute the shell configuration file to load the new variables into - your current environment.</para> - <note> - <para> - <emphasis>In a multi-server environment, you must add any - modifications to <filename>~/.bashrc</filename> to the top of - the file <emphasis>before</emphasis> the line - <literal>[ -z "$PS1" ] && return </literal>. - This will allow headless (scripted) logins to load the correct - environment.</emphasis> - </para> - </note> - <screen> - <prompt># as the opensrf user:</prompt> - <userinput>echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc</userinput> - <userinput>. ~/.bashrc</userinput> - </screen> + <para>In this step you will make some minor modifications to the OpenSRF environment:</para> + <itemizedlist> + <listitem> + <para>Modify the permissions in the directory + <filename class="directory">/openils/var/cgi-bin</filename> + to make the files executable:</para> + <screen> + <prompt># as the opensrf user:</prompt> + <userinput>chmod 755 /openils/var/cgi-bin/*.cgi</userinput> + </screen> + </listitem> + <listitem> + <para>As the <systemitem class="username">opensrf</systemitem> user, + modify the shell configuration file <filename>~/.bashrc</filename> for + user <systemitem class="username">opensrf</systemitem> by adding a Perl + environmental variable, then execute the shell configuration file to load + the new variables into your current environment.</para> + <note> + <para> + <emphasis>In a multi-server environment, you must add any + modifications to <filename>~/.bashrc</filename> to the top of + the file <emphasis>before</emphasis> the line + <literal>[ -z "$PS1" ] && return </literal>. + This will allow headless (scripted) logins to load the correct + environment.</emphasis> + </para> + </note> + <screen> + <prompt># as the opensrf user:</prompt> + <userinput>echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc</userinput> + <userinput>. ~/.bashrc</userinput> + </screen> + </listitem> + </itemizedlist> </step> <step performance="optional"> <title>(OPTIONAL) Enable and Disable Language Localizations</title> @@ -1495,6 +1507,9 @@ </section> <section xml:id="serversideinstallation-starting"> <title>Starting Evergreen</title> + <para>In this section you will learn how to start the Evergreen services. + For completeness, instructions for stopping Evergreen can be found later in + <xref linkend="serversideinstallation-stopping"/>.</para> <procedure> <step> <para>As the <systemitem class="username">root</systemitem> @@ -1553,11 +1568,12 @@ </step> <step> <para>In this step you will 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). You must do - this the first time you start Evergreen and after making any changes to the - library hierarchy. As the <systemitem class="username">opensrf</systemitem> - user, execute the following command and review the results:</para> + and catalog, and update 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.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, execute the + following command and review the results:</para> <screen> <prompt># as the opensrf user:</prompt> <userinput>cd /openils/bin</userinput> @@ -1677,32 +1693,41 @@ <prompt># as the root user:</prompt> <userinput>xulrunner /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client/build/application.ini</userinput> </screen> - <para>The login screen for the Staff Client should appear.</para> - <para>Log in using the username <literal>admin</literal> and the password - <literal>open-ils</literal> :</para> + <para>The login screen for the Staff Client should appear:</para> <mediaobject> <alt>Logging into the Staff Client</alt> <imageobject> <imagedata fileref="../media/serversideinstallation-staffclient-running-1.png" format="PNG" scalefit="1" width="70%"/> </imageobject> </mediaobject> - <para>If the login is successful, you will see the following screen:</para> + <para>First, add the name of your Evergreen server to the field + <literal>Hostname</literal> in the <literal>Server</literal> section. You will probably + want to use <literal>127.0.0.1</literal>. After adding the server name, click Re-Test + Server. You should now see the messages <literal>200:OK</literal> in the fields + <literal>Status</literal> and <literal>Version</literal>.</para> + <para>Because this is the initial run of the Staff Client, you will see a warning in the + upper-right saying: <emphasis role="bold">Not yet configured for the specified + server</emphasis>. To continue, you must assign a workstation name. Refer to + <xref linkend="staffclientinstallation-workstationnames"/> for further details.</para> + <para>Try to log into the Staff Client with the username <literal>admin</literal> and + the password <literal>open-ils</literal>. If the login is successful, you will see the + following screen:</para> <mediaobject> <alt>Logging into the Staff Client</alt> <imageobject> <imagedata fileref="../media/serversideinstallation-staffclient-running-4.png" format="PNG" scalefit="1" width="70%"/> </imageobject> </mediaobject> - <para>Otherwise, you may need to click <guibutton>Add SSL Exception</guibutton> in the - main window. You will see a popup window labeled "Add Security Exception":</para> + <para>Otherwise, you may need to click <guibutton>'Add SSL Exception'</guibutton> in the + main window. You should see a popup window titled <literal>Add Security Exception</literal>:</para> <mediaobject> - <alt>Logging into the Staff Client</alt> + <alt>Adding an SSL Exception in the Staff Client</alt> <imageobject> <imagedata fileref="../media/serversideinstallation-staffclient-running-2.png" format="PNG" scalefit="1" width="70%"/> </imageobject> </mediaobject> - <para>Click <guibutton>Get Certificate</guibutton>, then click <guibutton>Confirm - Security Exception</guibutton>, then click <guibutton>Re-Test Server</guibutton> in the + <para>Click <guibutton>'Get Certificate'</guibutton>, then click <guibutton>'Confirm + Security Exception'</guibutton>, then click <guibutton>'Re-Test Server'</guibutton> in the main window and try to log in again.</para> </simplesect> <simplesect xml:id="serversideinstallation-starting-apache-server"> @@ -1718,6 +1743,27 @@ <userinput>apache2ctl configtest && /etc/init.d/apache2 restart</userinput> </screen> </simplesect> + <simplesect xml:id="serversideinstallation-stopping"> + <title>Stopping Evergreen</title> + <para>In <xref linkend="serversideinstallation-starting"/> you learned how to start the + Evergreen services. For completeness, following are instructions for stopping the + Evergreen services.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, stop all Evergreen + services by using the following command:</para> + <screen> + # as the opensrf user + # stop the server; use "-l" to force hostname to be "localhost" + osrf_ctl.sh -l -a stop_all + </screen> + <note> + <para>You can also stop Evergreen services + <emphasis role="bold">without</emphasis> the <option>-l</option> flag, but the + <command>osrf_ctl.sh</command> utility must know the fully qualified domain name + for the system on which it will execute. That hostname may have been specified + in the configuration file <filename>opensrf.xml</filename>, which you configured + in a previous step.</para> + </note> + </simplesect> </section> <section xml:id="serversideinstallation-postinstallation"> <title>Post-Installation Chores</title> @@ -1735,7 +1781,7 @@ <warning> <para> <emphasis>This temporary network update was done to expedite - testing. You <emphasis role="bold"> must</emphasis> correct + testing. You <emphasis role="bold">must</emphasis> correct this for a public production system.</emphasis> </para> </warning> @@ -1776,7 +1822,7 @@ </warning> </section> <section> - <title>Set Up Support For Reports</title> + <title>(OPTIONAL) Set Up Support For Reports</title> <para>Evergreen reports are extremely powerful but require some simple configuration. This section describes starting and stopping the Reporter daemon processes.</para> <itemizedlist> @@ -1974,30 +2020,30 @@ <filename class="directory">C:\temp</filename>).</para> </step> <step> - <para>After selecting the file, click <guibutton>Open</guibutton> to import it.</para> + <para>After selecting the file, click <guibutton>'Open'</guibutton> to import it.</para> </step> <step> - <para>Then click <guibutton>OK</guibutton> to save the selection + <para>Then click <guibutton>'OK'</guibutton> to save the selection and return to the VirtualBox Media Manager</para> </step> <step> - <para>Click <guibutton>New</guibutton>, then <guibutton>Next</guibutton> to continue - and create a new virtual machine (VM).</para> + <para>Click <guibutton>'New'</guibutton>, then <guibutton>'Next'</guibutton> + to continue and create a new virtual machine (VM).</para> </step> <step> <para>Create a new name for the VM and set the operating system - type, then click <guibutton>Next</guibutton>.</para> + type, then click <guibutton>'Next'</guibutton>.</para> </step> <step> <para>Set the memory size (at least 512Mb), - then click <guibutton>Next</guibutton>.</para> + then click <guibutton>'Next'</guibutton>.</para> </step> <step> <para>Edit the Virtual Hard Disk configuration settings; click the radio boxes <guilabel>Boot Hard Disk</guilabel> and <guilabel>Use existing hard disk</guilabel> and ensure that the disk name <guilabel>Evergreen1601_DebianLenny.vmdk</guilabel> - is selected. Click <guibutton>Finish</guibutton> to finish the + is selected. Click <guibutton>'Finish'</guibutton> to finish the setup.</para> </step> <step> @@ -2007,13 +2053,13 @@ </step> <step> <para>Return to VirtualBox and see the summary of the VM just - created. Click <guibutton>Start</guibutton> to boot the new VM.</para> + created. Click <guibutton>'Start'</guibutton> to boot the new VM.</para> </step> <step> <para>See the start of the <systemitem class="osname">Linux</systemitem> boot sequence. Choose <guimenuitem>Debian Gnu/Linux, kernel 2.6.26-2-686</guimenuitem> from the startup menu and click - <guibutton>Enter</guibutton> to start + <guibutton>'Enter'</guibutton> to start <systemitem class="osname">Linux</systemitem> and Evergreen. After some delay you should see the command line prompt <prompt>debian-lenny login:</prompt>. Log in with username diff --git a/1.6/admin/staffclientinstallation.xml b/1.6/admin/staffclientinstallation.xml index de727ac132..d183325aad 100644 --- a/1.6/admin/staffclientinstallation.xml +++ b/1.6/admin/staffclientinstallation.xml @@ -1,1019 +1,1318 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter xml:id="staffclientinstallation" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink"> - <info> - <title>Installation of Evergreen Staff Client Software</title> - <abstract> - <para>This section describes installation of the Evergreen Staff Client software.</para> - </abstract> - </info> - <section xml:id="staffclientinstallation-installing-staffclient"> - <title>Installing the Staff Client</title> - <indexterm><primary>staff client</primary><secondary>installing</secondary></indexterm> - <simplesect> - <title>Installing a Pre-Built Staff Client</title> - <para>You can install the pre-built Staff Client available for Windows, MAC or Linux.</para> - <simplesect> - <title>Installing on Windows</title> - <indexterm><primary>staff client</primary><secondary>installing</secondary><tertiary>Windows</tertiary></indexterm> - <para>A standard Microsoft Windows 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> - <mediaobject> - <imageobject> - <imagedata fileref="../media/staffclientinstallation-staffclient-1.png" format="PNG" scalefit="1" width="70%"/> - </imageobject> - <textobject> - <phrase>Running the Staff Client installer</phrase> - </textobject> - </mediaobject> - <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> - <mediaobject> - <imageobject> - <imagedata fileref="../media/staffclientinstallation-staffclient-2.png" format="PNG" scalefit="1" width="70%"/> - </imageobject> - <textobject> - <phrase>Running the Staff Client for the first time</phrase> - </textobject> - </mediaobject> - <para>First, add the name of your Evergreen server to the field <emphasis role="bold">Hostname</emphasis> in the <emphasis role="bold">Server</emphasis> section. - For example, the PINES demo system is <ulink url="http://demo.gapines.org">http://demo.gapines.org</ulink>. After adding the server name, click <guibutton>Re-Test - Server</guibutton>.</para> - <para>Because this is the initial run of the Staff Client, you will see a warning in the upper-right indicating that the <emphasis role="bold">Workstation</emphasis> is - <emphasis role="bold">Not yet configured for the specified server</emphasis>. The first thing you must do to the Staff Client on every workstation is to assign - it a workstation name. This is covered in <xref linkend="staffclientinstallation-workstationnames"/>.</para> - </simplesect> - <simplesect> - <title>Installing on Mac OS</title> - <indexterm><primary>staff client</primary><secondary>installing</secondary><tertiary>Mac OS</tertiary></indexterm> - <para>A Mac package that contains the current version of the Staff Client is available for use with XULRunner.</para> - <simplesect> - <title>Evergreen Indiana Pkg file [Evergreen v1.2.3.0]</title> - <orderedlist> - <listitem>Download and install the latest version of XULRunner for Mac OS. Release notes 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.</listitem> - <listitem>Download and install the Mac 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>.</listitem> - <listitem>To upgrade to a more recent version of the Staff Client, you can copy the <filename class="directory">build</filename> directory from a - working Windows 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 Windows machine: - <filename class="directory">C:\Program Files\Evergreen Staff Client\build</filename>. Copy these files into the - <filename class="directory">Resources</filename> folder within the - <package>Open-ILS</package> package in your <filename class="directory">Applications</filename> directory on the Mac, overwriting files with the - same names.</listitem> <listitem>Drag the application's icon into your toolbar for easier access.</listitem> - </orderedlist> - <para/> - <para>When you run the Staff Client installer, a screen will appear that looks similar to this:</para> - <mediaobject> - <imageobject> - <imagedata fileref="../media/staffclientinstallation-staffclient-3.png" format="PNG" scalefit="1" width="20%"/> - </imageobject> - <textobject> - <phrase>Running the Staff Client installer</phrase> - </textobject> - </mediaobject> - <para>Click <guibutton>continue</guibutton>, accept the license, then finish the installation. The application will be located at the destination you - selected during installation. You will then be able to drag the application into your toolbar for easier access.</para> - <mediaobject> - <imageobject> - <imagedata fileref="../media/staffclientinstallation-staffclient-4.png" format="PNG" scalefit="1" width="20%"/> - </imageobject> - <textobject> - <phrase>Finishing the installation</phrase> - </textobject> - </mediaobject> - </simplesect> - <simplesect> - <title>Running directly using XULRunner</title> - <indexterm><primary>staff client</primary><secondary>XULRunner</secondary></indexterm> - <indexterm><primary>XULRunner</primary></indexterm> - <para>You must install an apropriate version of XULRunner to match the Evergreen version. See the following table for the recommended version of XULRunner:</para> - <table> - <title>Evergreen / XULRunner Dependencies</title> - <tgroup align="left" cols="2" colsep="1" rowsep="1"> - <colspec colnum="1" colwidth="1.0*"/> - <colspec colnum="2" colwidth="3.0*"/> - <tbody> - <row> - <entry>Evergreen 1.6.x.x</entry> - <entry>XULrunner 1.9</entry> - </row> - <row> - <entry>Evergreen 1.4.x.x</entry> - <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry> - </row> - <row> - <entry>Evergreen 1.2.x.x</entry> - <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry> - </row> - </tbody> - </tgroup> - </table> - <note>If you have issues removing previously installed XULRunner versions see <xref linkend="staffclientinstallation-remove-xulrunner"/> for further information. - </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. <filename class="directory">~/Desktop/Evergreen_Staff_Client</filename>). Remember to call XULRunner with the full path to the binary, followed by the - install command and the path to the client data:</para> -<screen> -<userinput>/Library/Frameworks/XUL.framework/xulrunner-bin --install-app ~/Desktop/Evergreen_Staff_Client</userinput> -</screen> - <para>This command should exit quietly. The folder <filename class="directory">/Applications/OpenILS</filename> will be created, containing a launcher - named <application>open_ils_staff_client</application>.</para> - </simplesect> - <simplesect xml:id="staffclientinstallation-remove-xulrunner"> - <title>Removing previously installed XULRunner versions</title> - <indexterm><primary>XULRunner</primary><secondary>removing previous versions</secondary></indexterm> - <para>If you already have a newer version installed, per the release notes, you will need to remove the entire directory - <filename class="directory">/Library/Frameworks/XUL.framework</filename> before downgrading.</para> - <para>In addition, you may also need to remove the previous file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> .</para> - <para>If file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> does not exist (possibly in newer OSX releases), you need to flush the - file <filename>receiptdb</filename>.</para> - <note>If you install a newer version over a previous (older) install, the older one is not removed but the symlinks are changed to the newer one.</note> - <simplesect> - <title>Flush Receiptdb file:</title> - <para>First, get the package identifier, then purge/forget the build that was initially installed:</para> -<screen> -<userinput>sudo pkgutil --pkgs > /tmp/pkgs.txt</userinput> -<userinput>sudo pkgutil --forget org.mozilla.xulrunner</userinput> -</screen> - <note>It may not be necessary to edit the file <filename>/Library/Receipts/InstallHistory.plist</filename> after deleting the folder - <filename class="directory">XUL.framework</filename>. - See <ulink url="http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html"> - http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html</ulink> for more information.</note> - </simplesect> - </simplesect> - <simplesect> - <title>Creating an APP file: Staff Client & XULRunner Bundled</title> - <para>An APP file is basically a folder. Start with a folder stucture like this:</para> - <screen> - * Evergreen.app - * Contents - * Frameworks - * Resources - * MacOS - </screen> - <para>Create an APP folder structure with the following commands:</para> -<screen> -<userinput>mkdir -p Evergreen.app/Contents/Frameworks</userinput> -<userinput>mkdir -p Evergreen.app/Contents/Resources</userinput> -<userinput>mkdir -p Evergreen.app/Contents/MacOS</userinput> -</screen> - <para/> - <orderedlist> - <listitem> - <para>Create a new file in the folder <filename class="directory">Evergreen.app/Contents/Info.plist</filename> containing the following data - (adjust for your version of Evergreen):</para> -<programlisting language="xml"><![CDATA[ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" - "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> -<plist version="1.0"> -<dict> - <key>CFBundleExecutable</key> - <string>xulrunner</string> - <key>CFBundleGetInfoString</key> - <string>OpenILS open_ils_staff_client rel_1_6_0_7</string> - <key>CFBundleInfoDictionaryVersion</key> - <string>6.0</string> - <key>CFBundleName</key> - <string>Evergreen Staff Client</string> - <key>CFBundlePackageType</key> - <string>APPL</string> - <key>CFBundleShortVersionString</key> - <string>rel_1_6_0_7</string> - <key>CFBundleVersion</key> - <string>rel_1_6_0_7.rel_1_6_0_7</string> - <key>NSAppleScriptEnabled</key> - <true/> - <key>CFBundleTypeIconFile</key> - <string>Evergreen.icns</string> -</dict> -</plist> -]]></programlisting> - </listitem> - <listitem>Download and install an appropriate Mac OS package of XULRunner from the Mozilla website (see above for recommendations).</listitem> - <listitem> - <para>Make a copy of the folder <filename class="directory">/Library/Frameworks/XUL.Framework</filename> inside your APP file. It should - look something like this:</para> -<screen> -* Evergreen.app/ -__* Contents/ -____* Frameworks/ -______* XUL.Framework/ -______* Versions/ -________* Current -> 1.9.1.3 (symlink) -________* 1.9.1.3/ -______* XUL -> Versions/Current/XUL -______* libxpcom.dylib -> Versions/Current/libxpcom.dylib -______* xulrunner-bin -> Versions/Current/xulrunner-bin -</screen> - </listitem> - <listitem>Copy <filename>XUL.Framework/Versions/Current/xulrunner</filename> into the folder <filename class="directory">Evergreen.app/MacOS</filename> - (do not symlink; copy the file).</listitem> - <listitem> - <para>Make <filename>Evergreen.app/Resources</filename> the root of your Evergreen application files like this:</para> -<screen> -* Evergreen.app/ -__* Contents/ -____* Resources/ -______* BUILD_ID -______* application.ini -______* chrome/ -______* components/ -______* etc. -</screen> - </listitem> - <listitem>Put a Mac format icon file named <filename>Evergreen.icns</filename> in <filename class="resources">Resources</filename>.</listitem> - </orderedlist> - </simplesect> - </simplesect> - <simplesect> - <title>Installing on Linux</title> - <simplesect> - <title>Quick Upgrade of the Staff Client</title> - <para>A Linux Staff Client is automatically built on the server as part of the normal <emphasis>make install</emphasis> process for Evergreen server-side - software. To upgrade the Staff Client on a remote workstation with a new version, just copy the directory tree containing the Staff Client from the server to - the remote workstation.</para> - <para>The following example assumes you already have an <systemitem class="username">opensrf</systemitem> user account on both the server and the - remote workstation. Remember to replace "user", "client.linux.machine" and "eg-client-x.x.x.x" with the proper user name, client machine name, and version number - in the following example.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then recursively copy the - entire directory tree to the remote workstation:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>scp -r build user@client.linux.machine:~/eg-client-x.x.x.x/</userinput> -</screen> - <para>To test the newly copied Staff Client, as the <systemitem class="username">opensrf</systemitem> user log into the remote workstation and execute it as - shown:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>xulrunner ~/eg-client-x.x.x.x/build/application.ini</userinput> -</screen> - </simplesect> - <simplesect> - <title>Building the Staff Client on the Server</title> - <indexterm><primary>staff client</primary><secondary>building on the server</secondary></indexterm> - <para>A Linux Staff Client is automatically built on the server as part of the normal <emphasis>make install</emphasis> process for Evergreen server-side - software, using a procedure similar to this:</para> -<screen> -<userinput>cd ~/ILS/Open-ILS/xul/staff_client</userinput> -<userinput>make STAFF_CLIENT_BUILD_ID='12345'</userinput> -<userinput>mkdir /openils/var/web/xul/</userinput> -<userinput>mkdir /openils/var/web/xul/12345/</userinput> -<userinput>cd build/</userinput> -<userinput>cp -R server/ /openils/var/web/xul/12345/</userinput> -</screen> - <para>The Staff Client can be run from the build directory using this command:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>xulrunner application.ini</userinput> -</screen> - <para>In order to install a compatible Staff Client on another Linux 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 Windows version on some systems, you may want to choose the BUILD_ID on both server and other versions to match that - of the Windows 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> -<screen> -<userinput>su - root</userinput> -<userinput>cd /openils/var/web/xul</userinput> -<userinput>ln -s SERVER_BUILD_ID/ CLIENT_BUILD_ID</userinput> -</screen> - </simplesect> - <simplesect> - <title>Building the Staff Client on the client Machine</title> - <para>This section is directed toward end-users who wish to use Linux rather than Windows for client machines, but have limited Linux experience. You can build - the Staff Client on a Linux system without installing the Evergreen Server component. This is a relatively simple process compared to server installation, but - does require some command-line work. The following directions are for building Staff Client version 1.2.1.4 on Kubuntu 7.10; you must modify them for - other distributions (the instructions should work as-is for Ubuntu or Ubuntu derivatives).</para> - <procedure> - <step> - <para>Prerequisites</para> - <para>Both <application>subversion</application> and <application>xulrunner</application> are required to build the Staff Client. As - the <systemitem class="username">root</systemitem> user, use <command>apt-get</command> to install packages for - <application>subversion</application> and <application>xulrunner</application>. You can also use <command>synaptic</command>, the graphical - user interface for <command>apt-get</command>. For <application>subversion</application>, select the latest version; for - <application>xulrunner</application>, select version <emphasis>1.8.1.4-2ubuntu5</emphasis>.</para> -<screen> -<userinput>sudo apt-get install subversion</userinput> -<userinput>sudo apt-get install xulrunner</userinput> -</screen> - </step> - <step> - <para>Download the Source Code</para> - <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>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 <guilabel>Visit</guilabel> drop-down box; see the list of <guilabel>Branches</guilabel> and, further down, a list - of <guilabel>Tags</guilabel>. You may have to do some guesswork, but it is fairly straightforward to determine which tag to use. - If the server is version 1.6.1.2, 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_6_1_2'. This is the tag you need; make a note of it for the next step.</para> - </listitem> - <listitem> - <para>Download the Code</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, open a terminal (command-line prompt) and navigate - to the directory in which you wish to download the Staff Client. Use the following commands to download the proper version of - the source code by tag name:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput> -<userinput>svn co rel_1_2_1_4/</userinput> -</screen> - <para>Remember to change "rel_1_6_1_2" to the appropriate tag for your installation.</para> - </listitem> - </itemizedlist> - </step> - <step> - <para>Build the Staff Client</para> - <itemizedlist> - <listitem> - <para>Evergreen 1.2.x</para> - <para>In the following example, navigate to the directory in which the source code was downloaded, then navigate to the - proper subdirectory and run the "make" utility to actually build the Staff Client. Remember to check with your system - administrator about which Staff Client BUILD_ID to use. The server checks the Staff Client BUILD_ID against itself to - determine whether or not a connecting client is supported. For instance, for the PINES installation (version 1.2.1.4) the - supported BUILD_ID is "rel_1_2_1_4". Modify the following commands accordingly.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, run the following commands to build the Staff Client:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput> -<userinput>cd Open-ILS/xul/staff_client</userinput> -<userinput>make STAFF_CLIENT_BUILD_ID='rel_1_6_1_2'</userinput> -</screen> - </listitem> - </itemizedlist> - </step> - <step> - <para>Run the Staff Client (from the command line)</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, navigate to the <filename class="directory">build/</filename> subdirectory - (not <filename class="directory">staff_client/</filename>) and run the following command:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>xulrunner application.ini</userinput> -</screen> - </step> - <step> - <para>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. As - the <systemitem class="username">opensrf</systemitem> user, issue the following commands to create a clean "staging" directory in which to place - the finished Staff Client, and to copy into it the "staff_client" directory:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>mkdir ~/<Destination Directory></userinput> -<userinput>cd ~/<Download Directory>/Open-ILS/xul/</userinput> -<userinput>cp -r staff_client ~/<Destination Directory></userinput> -</screen> - <para>Finally, test the Staff Client to verify that all the necessary files were moved to the destination directory:</para> -<screen> -<userinput>cd ~/<Destination Directory>/staff_client/build</userinput> -<userinput>xulrunner application.ini</userinput> -</screen> - <para>If there were no problems, then finish the cleanup by removing the original download directory and all subdirectories:</para> -<screen> -<userinput>rm -r -f ~/<Download Directory></userinput> -</screen> - <para>You may wish to create <menuchoice><guimenu>Desktop</guimenu><guimenuitem>Start Menu</guimenuitem><guimenuitem>K-Menu</guimenuitem> - </menuchoice> shortcuts for the Staff Client using the command <command>xulrunner ~/<Destination Directory>/staff_client/build/application.ini - </command> as the target.</para> - </step> - </procedure> - </simplesect> - <simplesect> - <title>Using Wine to Install on Linux</title> - <indexterm><primary>staff client</primary><secondary>using wine to install on Linux</secondary></indexterm> - <para>The Linux application <application>Wine</application> is another alternative if you wish to install the packaged Windows versions rather than building - the Staff Client manually. Wine is a Linux application that allows users to directly run Windows executables, and is a simple way for casual Linux users to use - the Staff Client. More information about Wine can be found at - <ulink url="http://www.winehq.org/site/docs/wineusr-guide/getting-wine">http://www.winehq.org/site/docs/wineusr-guide/getting-wine</ulink>.</para> - <para>As the <systemitem class="username">root</systemitem> user, use <command>apt-get</command> to install the package for <application>Wine</application>. - You can also use <command>synaptic</command>, the graphical user interface.</para> - <orderedlist> - <listitem> - <para>Install wine</para> -<screen> -<userinput>sudo apt-get install wine</userinput> -</screen> - </listitem> - <listitem> - <para>Download Windows installer for the Staff Client</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, run the following commands to download the Windows installer for the - proper Staff Client from the <ulink url="http://open-ils.org">open-ils.org</ulink> website and place it in a temporary directory:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput> -<userinput>wget http://open-ils.org/downloads/evergreen-setup-rel_version-number.exe</userinput> -</screen> - </listitem> - <listitem> - <para>Run the downloaded Windows installer</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, navigate to the directory where you downloaded the Windows executable - file, then execute it:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput> -<userinput>wine evergreen-setup-rel_version-number.exe</userinput> -</screen> - <para>If this step fails, you may need to configure Wine first to properly emulate Windows XP. To do so, type "winecfg" from the command line; - in the "Applications" tab of the window that pops up, select "Default Settings" and choose "Windows XP" from the drop-down menu, then - click <guibutton>Apply</guibutton>.</para> - </listitem> - <listitem> - <para>Launch the Staff Client</para> - <para>A new entry for the Staff Client should now appear somewhere in the "All Applications" menu of your Linux desktop. Also, find a new - desktop shortcut for the Staff Client. To launch the Staff Client, visit the "All Applications" menu, find a section similar to "Wine->Program - Files->Evergreen Staff Client->Evergreen Staff Client", or else launch the Staff Client from the desktop shortcut.</para> - </listitem> - </orderedlist> - </simplesect> - <simplesect xml:id="staffclientinstallation-workstationnames"> - <title>Assigning Workstation Names</title> - <indexterm><primary>staff client</primary><secondary>assigning workstation names</secondary></indexterm> - <para>The Staff Client must be assigned to a library and given a unique name before it will connect fully to the Evergreen server. The only restriction is that - the workstation's name must be unique within the assigned library. Make sure to select a workstation name that you will remember later, and reflects the - role, purpose, and/or location of a particular computer. These names will come up later in statistical reporting, and can also be handy when troubleshooting.</para> - <mediaobject> - <imageobject> - <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-1.png" format="PNG" scalefit="1" width="70%"/> - </imageobject> - <textobject> - <phrase>Example of unconfigured Staff Client</phrase> - </textobject> - </mediaobject> - <para>In order to assign a workstation a name, a user with appropriate permissions must login to the Staff Client. In PINES, the local system administrator - (OPSM) has the ability to assign workstation names in their library system. Library managers (LIBM's) have the ability within their branch. To assign a - workstation a name, login to the system. You will be prompted to assign the workstation a library and a name:</para> - <mediaobject> - <imageobject> - <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-2.png" format="PNG" scalefit="1" width="70%"/> - </imageobject> - <textobject> - <phrase>Example of configured Staff Client</phrase> - </textobject> - </mediaobject> - <para>Select the library this workstation physically operates in from the drop down menu. In this example, we have selected "MGRL-MA". Type in a friendly - name for the workstation. In this example, we are installing the Staff Client on the director's personal system, and have named it as such. Then - click <guibutton>Register</guibutton>.</para> - <para>Once you have registered your workstation with the server, your screen will look like this:</para> - <mediaobject> - <imageobject> - <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-3.png" format="PNG" scalefit="1" width="70%"/> - </imageobject> - <textobject> - <phrase>Example of registered Staff Client</phrase> - </textobject> - </mediaobject> - <para>You are now ready to log into the Staff Client for the first time. Type in your password again, and click <guibutton>Login</guibutton>.</para> - </simplesect> - </simplesect> - <simplesect> - <title>Building the Staff Client</title> - <indexterm><primary>staff client</primary><secondary>building</secondary></indexterm> - <para>You can also manually build the Staff Client by using the <command>make</command> utility in the Staff Client source directory (e.g., the directory - <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.0.x/Open-ILS/xul/staff_client</filename> for the current Evergreen version). There are a number of - possible options to manually build special versions of the Staff Client on a Linux system. Following is a list of environment variables that can be passed to - <command>make</command> to influence the manual build process:</para> - <simplesect> - <title>Option STAFF_CLIENT_BUILD_ID</title> - <para>During the normal <emphasis>make install</emphasis> Evergreen server-side software build process, the variable defaults to an automatically generated - date/time string, but you can also override the value of BUILD_ID.</para> - <para>The following commands could be used during the normal build process:</para> -<screen> -<userinput>su - root</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]</userinput> -<userinput>make STAFF_CLIENT_BUILD_ID=[version ID] install</userinput> -</screen> - <para>The following commands will manually build the Staff Client using a different BUILD_ID.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then set the variable and build - the Staff Client:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>make STAFF_CLIENT_BUILD_ID=my_test_id build</userinput> -</screen> - </simplesect> - <simplesect> - <title>Option STAFF_CLIENT_VERSION</title> - <para>During the normal <emphasis>make install</emphasis> Evergreen server-side software build process, the variable is pulled automatically from a README file - in the Evergreen source root. The variable defaults to <emphasis>0trunk.revision</emphasis>, where the value of "revision" is automatically generated. You - can override the value of VERSION similarly to the BUILD_ID.</para> - <para>The following commands could be used during the normal build process:</para> -<screen> -<userinput>su - root</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]</userinput> -<userinput>make STAFF_CLIENT_VERSION=0mytest.200 install</userinput> -</screen> - <para>The following commands will manually build the Staff Client using a different VERSION.</para> - <para>If you plan to make extensions update automatically, the VERSION needs to conform to the format recommended in - <ulink url="https://developer.mozilla.org/en/Toolkit_version_format">Toolkit Version Format</ulink> and newer versions need to be "higher" than older - versions.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then set the variable and build - the Staff Client:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>make STAFF_CLIENT_VERSION=0mytest.200 build</userinput> -</screen> - </simplesect> - <simplesect> - <title>Option STAFF_CLIENT_STAMP_ID variable</title> - <para>During the normal <emphasis>make install</emphasis> Evergreen server-side software build process, this variable is generated from STAFF_CLIENT_VERSION. - You can override the value of STAMP_ID similarly to the BUILD_ID.</para> - <para>The following commands could be used during the normal build process:</para> -<screen> -<userinput>su - root</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]</userinput> -<userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp install</userinput> -</screen> - <para>The following commands will manually build the Staff Client using a different STAMP_ID.</para> - <para>It is possible to have multiple versions of the Staff Client by specifying a different STAMP_ID for each, possibly for different uses or - client-side customizations.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then set the variable and build - the Staff Client:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp build</userinput> -</screen> - </simplesect> - </simplesect> - <simplesect> - <title>Advanced Build Options</title> - <indexterm><primary>staff client</primary><secondary>building</secondary><tertiary>advanced build options</tertiary></indexterm> - <para>In addition to the basic options listed above, there are a number of advanced options for building the Staff Client. Most are target names for the - <command>make</command> utility and require that you build the Staff Client from its source directory. See the following table for a list of possible - <command>make</command> target keywords:</para> - <table> - <title>Keywords Targets for "make" Command</title> - <tgroup align="left" cols="2" colsep="1" rowsep="1"> - <colspec colnum="1" colwidth="1.0*"/> - <colspec colnum="2" colwidth="3.0*"/> - <thead> - <row> - <entry>Keyword</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>clients</entry> - <entry>Runs "make win-client", "make linux-client", and "make generic-client" individually</entry> - </row> - <row> - <entry>client_dir</entry> - <entry>Builds a client directory from the build directory, without doing a rebuild. The same as "copy everything but server/".</entry> - </row> - <row> - <entry>client_app</entry> - <entry>Prerequisite "client_dir"; removes "install.rdf" from client directory so an APP bundle can't be installed as an extension</entry> - </row> - <row> - <entry>client_ext</entry> - <entry>Prerequisite "client_dir"; remove "application.ini", "autoupdate.js", "standalone_xul_app.js" from client directory so an - extension won't break Firefox</entry> - </row> - <row> - <entry>extension</entry> - <entry>Prerequisite "client_ext"; rewritten to use "client_ext"</entry> - </row> - <row> - <entry>generic-client</entry> - <entry>Prerequisite "client_app"; makes an XPI file suitable for use with "xulrunner --install-app""</entry> - </row> - <row> - <entry>win-xulrunner</entry> - <entry>Prerequisite "client_app"; adds Windows xulrunner to client build</entry> - </row> - <row> - <entry>linux-xulrunner</entry> - <entry>Prerequisite "client_app"; adds Linux xulrunner to client build</entry> - </row> - <row> - <entry>win-client</entry> - <entry>Prerequisite "win-xulrunner"; builds "setup exe" (requires that "nsis" package be installed, will add options for automatic update - if configured and developer options if client build was a "make devbuild")</entry> - </row> - <row> - <entry>linux-client</entry> - <entry>Prerequisite "linux_xulrunner"; builds a "tar.bz2" bundle of the Linux client</entry> - </row> - <row> - <entry>[generic-|win-|linux-|extension-]updates[-client]</entry> - <entry>Calls external/make_updates.sh to build full and partial updates generic/win/linux/extension prefix limit to that - distribution; Adding <option>-client</option> builds clients and copies them to a subdirectory of the - <filename class="directory">updates</filename> directory as well; - <option>extension-updates-client</option> doesn't exist.</entry> - </row> - </tbody> - </tgroup> - </table> - <para>Descriptions of other special build options follow:</para> - <itemizedlist> - <listitem> - <para>Developer Build</para> - <para>You can create a so-called <emphasis>developer build</emphasis> of the Staff Client by substituting <option>devbuild</option> for <option>build</option> when running <command>make</command>. - The build will contain an extra configuration file that enables some developer options.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, run <command>make</command> from the Staff Client source directory:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>make devbuild</userinput> -</screen> - </listitem> - <listitem> - <para>Compressed Javascript</para> - <para>You can execute the Google <systemitem class="resource">Closure Compiler</systemitem> utility to automatically review and compress - Javascript code after the build process completes, - by substituting <option>compress-javascript</option> for "build" when running <command>make</command>. For more information see - <ulink url="http://code.google.com/closure/compiler/">Google Closure Compiler</ulink>.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, run the following commands from the Staff Client source directory:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>make compress-javascript</userinput> -</screen> - <para>You can also combine Javascript review and compression, and also perform a <emphasis>developer build</emphasis>.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, run the following commands from the Staff Client source directory:</para> - <note><para>In the following <command>make</command> below, the order of options is important!</para></note> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>make devbuild compress-javascript</userinput> -</screen> - </listitem> - <listitem> - <para>Automatic Update Host</para> - <para>The host used to check for automatic Staff Client updates can be overridden by specifying the <option>AUTOUPDATE_HOST</option> option. The - following commands could have been used during the normal build process:</para> -<screen> -<userinput>su - root</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]</userinput> -<userinput>make AUTOUPDATE_HOST=localhost install</userinput> -</screen> - <para>You can manually set <option>AUTOUPDATE_HOST</option> to set up automatic update checking. The following commands will manually build the Staff - Client using a different <option>AUTOUPDATE_HOST</option>.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then set the variable and - build the Staff Client:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>make AUTOUPDATE_HOST=localhost build</userinput> -</screen> - <para>For more information on Automatic Updates, see <xref linkend="staffclientinstallation-autoupdate"/>.</para> - </listitem> - </itemizedlist> - </simplesect> - <simplesect> - <title>Installing and Activating a Manually Built Staff Client</title> - <para>The Staff Client is automatically built, installed and activated as part of the normal <command>make <option>install</option></command> process for Evergreen - server-side software. However, if you manually build the Staff Client, then you need to take additional steps to properly install and activate it. You also have the - option of installing the Staff Client on the same machine it was built on, or on a different machine.</para> - <para>Assuming you have already built the Staff Client, and that your installation is in the directory <filename class="directory">/openils/var/web/xul</filename>, as - the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the following commands:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>mkdir -p "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput> -<userinput>cp -R build/server "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput> -</screen> - </simplesect> - <simplesect> - <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> - <itemizedlist> - <listitem> - <para>Packaging a Generic Client</para> - <para>This build creates a Staff Client packaged as an XPI file to use with <application>xulrunner</application>. It requires that you already have - the <systemitem>zip</systemitem> utility installed on your system. It will create the output file <filename>evergreen_staff_client.xpi</filename>, - suitable for use with the <application>xulrunner</application> parameter <option>--install-app</option>>.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the - following commands:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>make generic-client</userinput> -</screen> - </listitem> - <listitem> - <para>Packaging a Windows Client</para> - <para>This build creates a Staff Client packaged as a Windows executable. It requires that you already have the "unzip" utility installed on your system. - It also requires that you install <ulink url="http://nsis.sourceforge.net/">NSIS (Nullsoft Scriptable Install System)</ulink>, a professional open - source utility package used to create Windows installers (the "makensis" utility is installed as part of the "nsis" package). We recommend using - Version 2.45 or later. This build will create the output file "evergreen_staff_client_setup.exe".</para> - <para>If you wish for the Staff Client to have a link icon/tray icon by default, you may wish to provide a pre-modified - <application>xulrunner-stub.exe</application>. Place it in the Staff Client source directory and <command>make</command> will automatically use it - instead of the one that comes with the downloaded <application>XULRunner</application> release. The version of - <application>xulrunner-stub.exe</application> need not match exactly.</para> - <para>You can also use a tool such as <ulink url="http://www.angusj.com/resourcehacker/">Resource Hacker</ulink> to embed icons. Resource Hacker - is an open-source utility used to view, modify, rename, add, delete and extract resources in 32bit Windows executables. See the following table for - some useful icon ID strings:</para> - <table> - <title>Useful icon ID strings</title> - <tgroup align="left" cols="2" colsep="1" rowsep="1"> - <colspec colnum="1" colwidth="1.0*"/> - <colspec colnum="2" colwidth="1.0*"/> - <tbody> - <row> - <entry>IDI_APPICON</entry> - <entry>Tray icon</entry> - </row> - <row> - <entry>32512</entry> - <entry>Default window icon</entry> - </row> - </tbody> - </tgroup> - </table> - <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the - following commands:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>make win-client</userinput> -</screen> - </listitem> - <listitem> - <para>Packaging a Linux Client</para> - <para>This build creates a Staff Client package for Linux as a "tar.bz2" file with <application>XULRunner</application> already bundled with it. It - creates the output file "evergreen_staff_client.tar.bz2".</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the - following commands:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>make linux-client</userinput> -</screen> - </listitem> - <listitem> - <para>Packaging a Firefox Extension</para> - <para>This build requires that you already have the <systemitem>zip</systemitem> utility installed on your system. It creates a Staff Client packaged - as a Firefox extension and creates the output file <filename>evergreen.xpi</filename>.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the - following commands:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -<userinput>make extension</userinput> -</screen> - </listitem> - </itemizedlist> - </simplesect> - <simplesect xml:id="staffclientinstallation-autoupdate"> - <title>Staff Client Automatic Updates</title> - <indexterm><primary>staff client</primary><secondary>automatic updates</secondary></indexterm> - <para>It is possible to set up support for automatic Staff Client updates, either during the normal Evergreen server-side build process, or by manually building the - Staff Client with certain special options.</para> - <caution> - <para>Automatic update server certificate requirements are more strict than normal server requirements. Firefox and <application>XULRunner</application> will - both ignore any automatic update server that is not validated by a trusted certificate authority. Servers with exceptions added to force the Staff Client to - accept them <emphasis>WILL NOT WORK</emphasis>.</para> - <para>In addition, automatic updates have special requirements for the file <filename>update.rdf</filename>:</para> - <orderedlist> - <listitem>It must be served from an SSL server, or</listitem> - <listitem>It must be signed with the <ulink url="https://developer.mozilla.org/en/McCoy">McCoy</ulink> tool.</listitem> - </orderedlist> - <para>You can pre-install the signing key into the file <filename>install.rdf</filename> directly, or install it into a copy as - <filename>install.mccoy.rdf</filename>. If the latter exists it will be copied into the build instead of the original file <filename>install.rdf</filename>.</para> - </caution> - <simplesect> - <title>Autoupdate Host</title> - <para>The name of the automatic update host can be provided in either of two ways:</para> - <orderedlist> - <listitem>At configuration time for the normal build of the Evergreen server-side software, or</listitem> - <listitem>During a manual Staff Client build process.</listitem> - </orderedlist> - <para/> - <itemizedlist> - <listitem> - <para>At configuration time for the normal build of Evergreen server-side software</para> - <para>This must be done when the Evergreen server-side software is first configured (see <xref linkend="serversideinstallation-configure"/>). As - the <systemitem class="username">opensrf</systemitem> user, use the utility "configure" as shown:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]</userinput> -<userinput>./configure --prefix=/openils --sysconfdir=/openils/conf --with-updateshost=hostname</userinput> -<userinput>make</userinput> -</screen> - </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 - <systemitem class="domainname">example.com</systemitem>) then the URL will - be a secure URL (such as <systemitem class="domainname">https://example.com</systemitem>. If you wish to use a non-HTTPS URL then prefix - the hostname with <systemitem class="domainname">http://</systemitem> - (such as <systemitem class="domainname">http://example.com</systemitem>).</para> - <para>If neither option is used then, by default, the Staff Client will not include the automatic update preferences.</para> - </listitem> - </itemizedlist> - </simplesect> - <simplesect> - <title>Building Updates</title> - <indexterm><primary>staff client</primary><secondary>automatic updates</secondary><tertiary>building</tertiary></indexterm> - <para>Similar to building clients, the targets <option>generic-updates</option>, <option>win-updates</option>, <option>linux-updates</option>, and - <option>extension-updates</option> can be used individually - with <command>make</command> to build the update files for the Staff Client. To build all the targets at once, simply use the target <option>updates</option>.</para> - <para>A full update will be built for each specified target (or for all if you use the target <option>updates</option>). For all but extensions any previous - full updates (archived by default in the directory <filename class="directory">/openils/var/updates/archives</filename>) will be used to make partial - updates. Partial updates tend to be much smaller and will thus download more quickly, but if something goes wrong with a partial update the full update will be - used as a fallback. Extensions do not currentlysupport partial updates.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the following - commands:</para> - -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -</screen> - - <para>Command to build all updates at once:</para> -<screen> -<userinput>make updates</userinput> -</screen> - <para>commands to build updates individually:</para> -<screen> -<userinput>make generic-updates</userinput> -... -<userinput>make win-updates</userinput> -... -<userinput>make linux-updates</userinput> -... -<userinput>make extension-updates</userinput> -... -</screen> - </simplesect> - <simplesect> - <title>Building updates with clients</title> - <indexterm><primary>staff client</primary><secondary>automatic updates</secondary><tertiary>building with clients</tertiary></indexterm> - <para>To save time and effort you can build updates and manual download clients at the same time by adding <option>-client</option> to each target - name. For instance, you can specify <option>win-updates-client</option>. You can also specify <option>updates-client</option> to build all the targets at once. - This does not work for <option>extension-updates</option>.</para> - <para>The clients will be installed alongside the updates and listed on the <filename>manualupdate.html</filename> page, rather than left in the Staff - Client directory.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the following - commands:</para> -<screen> -<userinput>su - opensrf</userinput> -<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> -</screen> - - <para>Command to build all updates at once:</para> -<screen> -<userinput>make updates-client</userinput> -</screen> - - <para>Command to build updates individually:</para> -<screen> -<userinput>make generic-updates-client</userinput> -... -<userinput>make win-updates-client</userinput> -... -<userinput>make linux-updates-client</userinput> -</screen> - - </simplesect> - <simplesect> - <title>Activating the Update Server</title> - <indexterm><primary>staff client</primary><secondary>automatic updates</secondary><tertiary>activating the update server</tertiary></indexterm> - <para>This section reviews scripts associated with the update server, and requires some final adjustments to file permissions.</para> - <para>The Apache example configuration creates an "updates" directory that, by default, points to the directory - <filename class="directory">/openils/var/updates/pub</filename>. This directory contains one HTML file and several specially-named script files.</para> - <para>The <filename>updatedetails.html</filename> file is the fallback web page for the update details. The <filename>check</filename> script is used - for <application>XULRunner</application> - updates. The <filename>update.rdf</filename> script is used for extension updates. The <filename>manualupdate.html</filename> file checks for clients to - provide download links when automatic updates have failed and uses the download script to force a download of the generic client XPI (compared to Firefox trying - to install it as an extension).</para> - <para>The following scripts should be marked as executable: <filename>check</filename>, <filename>download</filename>, <filename>manualupdate.html</filename>, <filename>update.rdf</filename>. Execute the following commands:</para> -<screen> -<userinput>su - root</userinput> -<userinput>cd /openils/var/updates/pub</userinput> -<userinput>chmod +x check download manualupdate.html update.rdf</userinput> -</screen> - </simplesect> - </simplesect> - <simplesect> - <title>Other tips</title> - <simplesect> - <title>Multiple workstations on one install</title> - <para>Multiple workstation registrations for the same server can be accomplished with a single Staff Client install by using multiple profiles. When running <application>XULRunner</application> you can specify the option "-profilemanager" or "-P" (uppercase "P") to force the Profile Manager to start. Unchecking the "Don't ask at startup" option will make this the default.</para> - <para>Once you have opened the Profile Manager you can create additional profiles, one for each workstation you wish to register. You may need to install SSL exceptions for each profile.</para> - <para>When building targets <option>win-client</option>, <option>win-updates-client</option>, or <option>updates-client</option>, you can - specify <option>NSIS_EXTRAOPTS=-DPROFILES</option> to add an <guimenuitem>Evergreen Staff Client Profile Manager</guimenuitem> option to the start menu.</para> - <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the following - commands:</para> - <screen> - <userinput>su - opensrf</userinput> - <userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput> - <userinput>make NSIS_EXTRAOPTS=-DPROFILES win-client</userinput> - </screen> - </simplesect> - <simplesect> - <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 <application>XULRunner</application> with the option <option>-no-remote</option> (in addition to - <option>-profilemanger</option> or <option>-P</option> - if neeeded). Instead of <application>XULRunner</application> 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> - </simplesect> - </simplesect> - </simplesect> - </section> - <section xml:id="staffclientinstallation-running-staffclient"> - <title>Running the Staff Client</title> - <indexterm><primary>staff client</primary><secondary>running</secondary><tertiary>linux</tertiary></indexterm> - <para>Run the Staff Client on a Linux system by using the application <application>XULRunner</application> (installed automatically and by default with Firefox version 3.0 and later - on Ubuntu and Debian distributions).</para> - <para>For example, if the source files for the Evergreen installation are in the directory <filename class="directory">/home/opensrf/[Evergreen Install Directory]/</filename>, start - the Staff Client as shown in the following example:</para> - <screen> - <userinput>su - opensrf</userinput> - <userinput>xulrunner /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client/build/application.ini</userinput> - </screen> - <simplesect xml:id="staffclientinstallation-proxy"> - <title>Running the Staff Client over an SSH Tunnel</title> - <indexterm><primary>staff client</primary><secondary>running through an SSH tunnel</secondary></indexterm> - <para>The Staff Client can use an SSH tunnel as a SOCKS 5 proxy.</para> - <simplesect> - <title>Configuring 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> - <itemizedlist> - <listitem> - <para>Firewalls may prevent you from reaching the server. This may happen when you are connecting the Staff Client to a test server that should not - be available generally, or it may be the result of network design priorities other than ease of use.</para> - </listitem> - <listitem> - <para>You may wish to improve security where Staff Client traffic may be susceptible to network eavesdropping. This is especially true when wireless - is otherwise the best option for connecting a staff machine to the network.</para> - </listitem> - </itemizedlist> - </simplesect> - <simplesect> - <title>Setting Up an SSH Tunnel</title> - <para>You will need a server that allows you to log in via SSH and has network access to the Evergreen server you want to reach. You will use your username and password - for that <systemitem class="protocal">SSH</systemitem> server to set up a tunnel.</para> - <para>For Windows users, one good solution is the open-source utility <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty/">PuTTY</ulink>, a free - <systemitem class="protocal">telnet/SSH</systemitem> client]]. When setting up a PuTTY session:</para> - <mediaobject> - <imageobject> - <imagedata fileref="../media/staffclientinstallation-proxy-putty.png" format="PNG" scalefit="1" width="70%"/> - </imageobject> - <textobject> - <phrase>Setting up an SSH tunnel in PuTTY</phrase> - </textobject> - </mediaobject> - <orderedlist> - <listitem>Use the menu on the left to go to Connection > SSH > Tunnels.</listitem> - <listitem>Enter ''9999'' in the "Source port".</listitem> - <listitem>Choose "Dynamic". Do not enter anything in the Destination text entry box.</listitem> - <listitem>Click <guibutton>Add</guibutton>; "D9999" will now appear in the "Forwarded ports" list.</listitem> - <listitem>Use the menu on the left to go back to "Session", and enter the host name of the <systemitem class="protocal">SSH</systemitem> server.</listitem> - <listitem>A window will open up so that you can enter your username and password. Once you are logged in, the tunnel is open.</listitem> - </orderedlist> - <para>See <ulink url="http://inside.mines.edu/~gmurray/HowTo/sshNotes.html">How to set up <systemitem class="protocal">SSH</systemitem> (for the beginner)</ulink> - for information on setting up <systemitem class="protocal">SSH</systemitem> for other client operating systems,</para> - </simplesect> - <simplesect> - <title>Configuring the Staff Client to Use the <systemitem class="protocal">SSH</systemitem> Tunnel</title> - <para>In order to tell the Staff Client that all traffic should be sent through the <systemitem class="protocal">SSH</systemitem> tunnel just configured, you must edit - the file <filename>C:\Program Files\Evergreen Staff Client\greprefs\all.js</filename>. Search this file for the word <literal>socks</literal> to find the - appropriate section for the following changes.</para> - <mediaobject> - <imageobject> - <imagedata fileref="../media/staffclientinstallation-proxy-socks-1.png" format="PNG" scalefit="1" width="70%"/> - </imageobject> - <textobject> - <phrase>The SOCKS section of "all.js" before changes</phrase> - </textobject> - </mediaobject> - <para>Make the following changes:</para> - <itemizedlist> - <listitem>Change the value of <literal>network.proxy.socks</literal> from <literal>""</literal> to <literal>localhost</literal>.</listitem> - <listitem>Change the value of <literal>network.proxy.socks_port</literal> from <literal>0</literal> to <literal>9999</literal>.</listitem> - </itemizedlist> - <mediaobject> - <imageobject> - <imagedata fileref="../media/staffclientinstallation-proxy-socks-2.png" format="PNG" scalefit="1" width="70%"/> - </imageobject> - <textobject> - <phrase>The SOCKS section of "all.js" after changes</phrase> - </textobject> - </mediaobject> - <para>If everything is working correctly, you should now be able to run the Staff Client and all its data will be sent encrypted through the - <systemitem class="protocal">SSH</systemitem> tunnel you have just configured.</para> - </simplesect> - </simplesect> - </section> -</chapter> +<?xml version="1.0" encoding="UTF-8"?> +<chapter xml:id="staffclientinstallation" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink"> + <info> + <title>Installation of Evergreen Staff Client Software</title> + <abstract> + <para>This section describes installation of the Evergreen Staff Client software.</para> + </abstract> + </info> + <section xml:id="staffclientinstallation-installing-staffclient"> + <title>Installing the Staff Client</title> + <indexterm> + <primary>staff client</primary> + <secondary>installing</secondary> + </indexterm> + <section xml:id="staffclientinstallation-installing-prebuilt"> + <title>Installing a Pre-Built Staff Client</title> + <para>A pre-built Staff Client is available for Windows, Mac or Linux systems. Installing the + Staff Client in each of these environments is described in the following sections.</para> + <section xml:id="staffclientinstallation-installing-windows"> + <title>Installing on Windows</title> + <indexterm> + <primary>staff client</primary> + <secondary>installing</secondary> + <tertiary>Windows</tertiary> + </indexterm> + <para>In this section we describe the process of installing the Staff Client on the + <systemitem class="osname">Microsoft Windows</systemitem> operating + system.</para> + <para>Visit 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> + and find the standard Microsoft Windows Installer that contains the current version of + the Staff Client. Download the Installer, then run it. A screen that looks similar to + this should appear:</para> + <mediaobject> + <alt> + <phrase>Running the Staff Client installer</phrase> + </alt> + <imageobject> + <imagedata fileref="../media/staffclientinstallation-staffclient-1.png" format="PNG" scalefit="1" width="70%"/> + </imageobject> + </mediaobject> + <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 automatically + 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> + <mediaobject> + <alt> + <phrase>Running the Staff Client for the first time</phrase> + </alt> + <imageobject> + <imagedata fileref="../media/staffclientinstallation-staffclient-2.png" format="PNG" scalefit="1" width="70%"/> + </imageobject> + </mediaobject> + <para>First, add the name of your Evergreen server to the field + <emphasis role="bold">Hostname</emphasis> in the <emphasis role="bold">Server</emphasis> + section. For example, the PINES demo system is + <ulink url="http://demo.gapines.org">http://demo.gapines.org</ulink>. + After adding the server name, click <guibutton>'Re-Test Server'</guibutton>.</para> + <para>Because this is the initial run of the Staff Client, you will see a warning in the + upper-right saying: <emphasis role="bold">Not yet configured for the specified + server</emphasis>. The first thing you must do to the Staff Client on every workstation + is to assign it a workstation name. This is covered in + <xref linkend="staffclientinstallation-workstationnames"/>.</para> + </section> + <section xml:id="staffclientinstallation-installing-macos"> + <title>Installing on Mac OS</title> + <indexterm> + <primary>staff client</primary> + <secondary>installing</secondary> + <tertiary>Mac OS</tertiary> + </indexterm> + <para>In this section, we describe Mac packages and related versions of XULRunner + that can be used to run the Staff Client in a Mac OS environment.</para> + <simplesect> + <title>Evergreen Version 1.2.3.0</title> + <orderedlist> + <listitem> + <para>A Mac package that contains an early version of the Staff Client + (version 1.2.3.0) for use with XULRunner is available. Current releases + of XULRunner can be found here: + <ulink url="http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases"> + http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases</ulink> . + Download and install the latest version. Further information about + XULRunner can be found here: + <ulink url="https://developer.mozilla.org/en/xulrunner"> + https://developer.mozilla.org/en/xulrunner</ulink></para> + <para>Note that later versions of XULRunner (e.g., version 1.9.2.13) have + replaced version 1.8.0.4, which has known security holes and is not + recommended for applications that deal with public web content.</para> + </listitem> + <listitem> + <para>A Mac OS Installation package for Staff Client version 1.2.3.0 + is available from Evergreen Indiana. Download and install it from here: + <ulink url="http://evergreen.lib.in.us/opac/extras/files/evergreen_osx_staff_client_1_2_3.zip"> + evergreen_osx_staff_client_1_2_3.zip</ulink> . + </para> + </listitem> + <listitem> + <para>To upgrade to a more recent version of the Staff Client, you can + copy the <filename class="directory">build</filename> directory from a + working Windows 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 Windows machine: <filename class="directory"> + C:\Program Files\Evergreen Staff Client\build</filename>. + Copy these files to the <filename class="directory">Resources</filename> + folder within the <package>Open-ILS</package> package in your + <filename class="directory">Applications</filename> directory on the Mac, + overwriting files with the same names.</para> + </listitem> + <listitem>Drag the application's icon to your toolbar for easier + access.</listitem> + </orderedlist> + <para>When you run the Staff Client installer, a screen will appear that looks + similar to this:</para> + <mediaobject> + <alt> + <phrase>Running the Staff Client installer for Mac OS</phrase> + </alt> + <imageobject> + <imagedata fileref="../media/staffclientinstallation-staffclient-3.png" format="PNG" scalefit="1" width="20%"/> + </imageobject> + </mediaobject> + <para>Click <guibutton>'Continue'</guibutton>, accept the license, then finish the + installation. The application will be located at the destination you selected + during installation. You will then be able to drag the application into your + toolbar for easier access.</para> + <mediaobject> + <alt> + <phrase>Finishing the installation</phrase> + </alt> + <imageobject> + <imagedata fileref="../media/staffclientinstallation-staffclient-4.png" format="PNG" scalefit="1" width="20%"/> + </imageobject> + </mediaobject> + </simplesect> + <simplesect> + <title>Running directly using XULRunner</title> + <indexterm> + <primary>staff client</primary> + <secondary>XULRunner</secondary> + </indexterm> + <para>You must install an apropriate version of XULRunner to match the Evergreen + version. See the following table for the recommended version of + XULRunner:</para> + <table> + <title>Evergreen / XULRunner Dependencies</title> + <tgroup align="left" cols="2" colsep="1" rowsep="1"> + <colspec colnum="1" colwidth="1.0*"/> + <colspec colnum="2" colwidth="3.0*"/> + <tbody> + <row> + <entry>Evergreen 1.6.x.x</entry> + <entry>XULrunner 1.9</entry> + </row> + <row> + <entry>Evergreen 1.4.x.x</entry> + <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry> + </row> + <row> + <entry>Evergreen 1.2.x.x</entry> + <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry> + </row> + </tbody> + </tgroup> + </table> + <note>If you have issues removing previously installed XULRunner versions see + <xref linkend="staffclientinstallation-remove-xulrunner"/> for further + information. + </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. <filename class="directory">~/Desktop/Evergreen_Staff_Client</filename>). + Remember to call XULRunner with the full path to the binary, followed by the + install command and the path to the client data:</para> + <screen> + <prompt># as the root user</prompt> + <userinput>/Library/Frameworks/XUL.framework/xulrunner-bin --install-app ~/Desktop/Evergreen_Staff_Client</userinput> + </screen> + <para>This command should exit quietly. The folder + <filename class="directory">/Applications/OpenILS</filename> will be created, + containing a launcher named <application>open_ils_staff_client</application>.</para> + </simplesect> + <simplesect xml:id="staffclientinstallation-remove-xulrunner"> + <title>Removing previously installed XULRunner versions</title> + <indexterm> + <primary>XULRunner</primary> + <secondary>removing previous versions</secondary> + </indexterm> + <para>If you already have a newer version installed, per the release notes, you + will need to remove the entire directory + <filename class="directory">/Library/Frameworks/XUL.framework</filename> + before downgrading.</para> + <para>In addition, you may also need to remove the previous + file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> .</para> + <para>If file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> does + not exist (possibly in newer OSX releases), you need to flush the file + <filename>receiptdb</filename>.</para> + <note>If you install a newer version over a previous (older) install, the older + one is not removed but the symlinks are changed to the newer one.</note> + </simplesect> + <simplesect> + <title>Flush Receiptdb file:</title> + <para>First, get the package identifier, then purge/forget the build that was + initially installed:</para> + <screen> + <prompt># as the root user</prompt> + <userinput>sudo pkgutil --pkgs > /tmp/pkgs.txt</userinput> + <userinput>sudo pkgutil --forget org.mozilla.xulrunner</userinput> + </screen> + <note>It may not be necessary to edit the file + <filename>/Library/Receipts/InstallHistory.plist</filename> after deleting the + folder <filename class="directory">XUL.framework</filename>. See + <ulink url="http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html"> + http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html</ulink> + for more information.</note> + </simplesect> + <simplesect> + <title>Creating an APP file: Staff Client & XULRunner Bundled</title> + <para>An APP file is basically a folder. Start with a folder stucture like this:</para> + <screen> + * Evergreen.app + * Contents + * Frameworks + * Resources + * MacOS + </screen> + <para>Create an APP folder structure with the following commands:</para> + <screen> + <prompt># as the root user</prompt> + <userinput>mkdir -p Evergreen.app/Contents/Frameworks</userinput> + <userinput>mkdir -p Evergreen.app/Contents/Resources</userinput> + <userinput>mkdir -p Evergreen.app/Contents/MacOS</userinput> + </screen> + <para/> + <orderedlist> + <listitem> + <para>Create a new file in the folder + <filename class="directory">Evergreen.app/Contents/Info.plist</filename> + containing the following data (adjust for your version of + Evergreen):</para> + <programlisting language="xml"><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> +<plist version="1.0"> +<dict> + <key>CFBundleExecutable</key> + <string>xulrunner</string> + <key>CFBundleGetInfoString</key> + <string>OpenILS open_ils_staff_client rel_1_6_0_7</string> + <key>CFBundleInfoDictionaryVersion</key> + <string>6.0</string> + <key>CFBundleName</key> + <string>Evergreen Staff Client</string> + <key>CFBundlePackageType</key> + <string>APPL</string> + <key>CFBundleShortVersionString</key> + <string>rel_1_6_0_7</string> + <key>CFBundleVersion</key> + <string>rel_1_6_0_7.rel_1_6_0_7</string> + <key>NSAppleScriptEnabled</key> + <true/> + <key>CFBundleTypeIconFile</key> + <string>Evergreen.icns</string> +</dict> +</plist> +]]></programlisting> + </listitem> + <listitem>Download and install an appropriate Mac OS package of + XULRunner from the Mozilla website (see above for + recommendations).</listitem> + <listitem> + <para>Make a copy of the folder + <filename class="directory">/Library/Frameworks/XUL.Framework</filename> + inside your APP file. It should look something like this:</para> + <screen> + <prompt>* Evergreen.app/</prompt> + <prompt>__* Contents/</prompt> + <prompt>____* Frameworks/</prompt> + <prompt>______* XUL.Framework/</prompt> + <prompt>______* Versions/</prompt> + <prompt>________* Current -> 1.9.1.3 (symlink)</prompt> + <prompt>________* 1.9.1.3/</prompt> + <prompt>______* XUL -> Versions/Current/XUL</prompt> + <prompt>______* libxpcom.dylib -> Versions/Current/libxpcom.dylib</prompt> + <prompt>______* xulrunner-bin -> Versions/Current/xulrunner-bin</prompt> + </screen> + </listitem> + <listitem>Copy + <filename>XUL.Framework/Versions/Current/xulrunner</filename> into the + folder <filename class="directory">Evergreen.app/MacOS</filename> + (do not symlink; copy the file).</listitem> + <listitem> + <para>Make <filename>Evergreen.app/Resources</filename> the root + of your Evergreen application files like this:</para> + <screen> + <prompt>* Evergreen.app/</prompt> + <prompt>__* Contents/</prompt> + <prompt>____* Resources/</prompt> + <prompt>______* BUILD_ID</prompt> + <prompt>______* application.ini</prompt> + <prompt>______* chrome/</prompt> + <prompt>______* components/</prompt> + <prompt>______* etc.</prompt> + </screen> + </listitem> + <listitem>Put a Mac format icon file named <filename>Evergreen.icns</filename> in + <filename class="resources">Resources</filename>.</listitem> + </orderedlist> + </simplesect> + </section> + <section xml:id="staffclientinstallation-installing-linux"> + <title>Installing on Linux</title> + <simplesect> + <title>Quick Upgrade of the Staff Client</title> + <para>A Linux Staff Client is automatically built on the server as part of the + normal <emphasis>make install</emphasis> process for Evergreen server-side + software. To upgrade the Staff Client on a remote Linux workstation with a new + version, just copy the directory tree containing the Staff Client from the + server to the remote workstation.</para> + <para>The following example assumes you already have an + <systemitem class="username">opensrf</systemitem> user account on both the + server and the remote workstation. Replace <literal>USER</literal>, + <literal>LINUX_MACHINE</literal>, and <literal>HOME_DIRECTORY</literal> + with appropriate values.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, execute the + following commands:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>scp -r ./build USER@LINUX_MACHINE:~/HOME_DIRECTORY/</userinput> + </screen> + <para>You must now test the newly copied Staff Client. + As the <systemitem class="username">opensrf</systemitem> user, log into the + remote workstation and execute the following command:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>xulrunner ~/HOME_DIRECTORY/build/application.ini</userinput> + </screen> + </simplesect> + <simplesect> + <title>Building the Staff Client on the Server</title> + <indexterm> + <primary>staff client</primary> + <secondary>building on the server</secondary> + </indexterm> + <para>A Linux Staff Client is automatically built on the server as part of the + normal <emphasis>make install</emphasis> process for Evergreen server-side + software. See <xref linkend="serversideinstallation-compile"/> for details of + the build process.</para> + <para>In order to install a compatible Staff Client on another Linux system, you + can copy the appropriate files from the Staff Client build directory on the + server to the new Linux system, or just manually build it on the new + system. Ensure that the BUILD_ID you choose on the new system matches the + BUILD_ID for each Staff Client you use on other systems.</para> + <para>If you wish to use a pre-packaged Windows version on some systems, you + may want to choose the BUILD_ID on both server and other versions to match that + of the Windows Staff Client. To determine which BUILD_ID used in an existing + Staff Client installation, execute the Staff Client and click + <guibutton>'About this Client'</guibutton>.</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> + <screen> + <prompt># as the root user</prompt> + <userinput>cd /openils/var/web/xul</userinput> + <userinput>ln -s SERVER_BUILD_ID/ CLIENT_BUILD_ID</userinput> + </screen> + </simplesect> + <simplesect> + <title>Building the Staff Client on a client Machine</title> + <para>This section is directed toward end-users who wish to use Linux rather + than Windows for client machines, but have limited Linux experience. You can + build the Staff Client on a Linux system without installing the Evergreen Server + component. This is a relatively simple process compared to server installation, + but does require some command-line work. The following directions are for + building Staff Client version 1.2.1.4 on Kubuntu 7.10; you must modify them for + other distributions (the instructions should work as-is for Ubuntu or Ubuntu + derivatives).</para> + <procedure> + <step> + <title>Prerequisites</title> + <para>Both <application>subversion</application> and + <application>xulrunner</application> are required to build the Staff + Client. As the <systemitem class="username">root</systemitem> user, + use <command>apt-get</command> to install packages for + <application>subversion</application> and + <application>xulrunner</application>. You can also use + <command>synaptic</command>, the graphical user interface for + <command>apt-get</command>. For <application>subversion</application>, + select the latest version; for <application>xulrunner</application>, + select version <emphasis>1.8.1.4-2ubuntu5</emphasis>.</para> + <screen> + <prompt># as the root user</prompt> + <userinput>sudo apt-get install subversion</userinput> + <userinput>sudo apt-get install xulrunner</userinput> + </screen> + </step> + <step> + <title>Download the Source Code</title> + <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>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 <guilabel>Visit</guilabel> drop-down box; see + the list of <guilabel>Branches</guilabel> and, further + down, a list of <guilabel>Tags</guilabel>. You may have + to do some guesswork, but it is fairly straightforward to + determine which tag to use. If the server is version + 1.6.1.2, 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_6_1_2'. This is the tag + you need; make a note of it for the next step.</para> + </listitem> + <listitem> + <para>Download the Code</para> + <para>As the + <systemitem class="username">opensrf</systemitem> + user, open a terminal (command-line prompt) and navigate + to the directory in which you wish to download the Staff + Client. Use the following commands to download the proper + version of the source code by tag name:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /DOWNLOAD/DIRECTORY</userinput> + <userinput>svn co rel_1_6_1_2/</userinput> + </screen> + <para>Remember to change "rel_1_6_1_2" to the appropriate + tag for your installation.</para> + </listitem> + </itemizedlist> + </step> + <step> + <title>Build the Staff Client</title> + <para>In the following + example, navigate to the directory in which the source code was + downloaded, then navigate to the proper subdirectory and run the + "make" utility to actually build the Staff Client. Remember to + check with your system administrator about which Staff Client + BUILD_ID to use. The server checks the Staff Client BUILD_ID + against itself to determine whether or not a connecting client + is supported. For instance, for the PINES installation (version + 1.2.1.4) the supported BUILD_ID is "rel_1_2_1_4". Modify the + following commands accordingly.</para> + <para>As the <systemitem class="username">opensrf</systemitem> + user, run the following commands to build the Staff Client:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput> + <userinput>cd Open-ILS/xul/staff_client</userinput> + <userinput>make STAFF_CLIENT_BUILD_ID='rel_1_6_1_2'</userinput> + </screen> + </step> + <step> + <title>Run the Staff Client (from the command line)</title> + <para>As the <systemitem class="username">opensrf</systemitem> + user, navigate to the <filename class="directory">build/</filename> + subdirectory (not <filename class="directory">staff_client/</filename>) + and run the following command:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>xulrunner application.ini</userinput> + </screen> + </step> + <step> + <title>(OPTIONAL) Cleaning Up / Creating Shortcuts</title> + <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 then + be copied to other machines.</para> + <para>To create a clean "staging" directory in which to place + the finished Staff Client, execute the following commands + (remember to replace <literal>DESTINATION_DIRECTORY</literal> + with the appropriate path):</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>mkdir ~/DESTINATION_DIRECTORY</userinput> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/</userinput> + <userinput>cp -r staff_client ~/DESTINATION_DIRECTORY</userinput> + </screen> + <para>Finally, test the Staff Client to verify that all necessary + files were moved to the destination directory:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd ~/DESTINATION_DIRECTORY/staff_client/build</userinput> + <userinput>xulrunner application.ini</userinput> + </screen> + <para>If there were no problems, then finish the cleanup by removing the + original download directory and all subdirectories as shown:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>rm -r -f ~/DOWNLOAD_DIRECTORY</userinput> + </screen> + <para>You may wish to create a shortcut for the Staff Client:</para> + <menuchoice> + <guimenu>Desktop</guimenu> + <guimenuitem>StartMenu</guimenuitem> + <guimenuitem>K-Menu</guimenuitem> + </menuchoice> + <para>Use the command: <command>xulrunner + ~/DESTINATION_DIRECTORY/staff_client/build/application.ini</command> + as the target for the shortcut.</para> + </step> + </procedure> + </simplesect> + <simplesect> + <title>Using Wine to Install on Linux</title> + <indexterm> + <primary>staff client</primary> + <secondary>using wine to install on Linux</secondary> + </indexterm> + <para>The Linux application <application>Wine</application> is another alternative if you + wish to install the packaged Windows versions rather than building the Staff Client + manually. Wine is a Linux application that allows users to directly run Windows + executables, and is a simple way for casual Linux users to use the Staff Client. More + information about Wine can be found at + <ulink url="http://www.winehq.org/site/docs/wineusr-guide/getting-wine"> + http://www.winehq.org/site/docs/wineusr-guide/getting-wine</ulink>.</para> + <para>As the <systemitem class="username">root</systemitem> user, use + <command>apt-get</command> to install the package for <application>Wine</application>. + You can also use <command>synaptic</command>, the graphical user interface.</para> + <orderedlist> + <listitem> + <para>Install wine:</para> + <screen> + <prompt># as the root user</prompt> + <userinput>sudo apt-get install wine</userinput> + </screen> + </listitem> + <listitem> + <para>Download Windows installer for the Staff Client</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, run + the following commands to download the Windows installer for the proper + Staff Client from the <ulink url="http://open-ils.org">open-ils.org</ulink> + website and place it in a temporary directory:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput> + <userinput>wget http://open-ils.org/downloads/evergreen-setup-rel_version-number.exe</userinput> + </screen> + </listitem> + <listitem> + <para>Run the downloaded Windows installer</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, + navigate to the directory where you downloaded the Windows executable + file, then execute it:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput> + <userinput>wine evergreen-setup-rel_version-number.exe</userinput> + </screen> + <para>If this step fails, you may need to configure Wine first to properly + emulate Windows XP. To do so, type "winecfg" from the command line; in the + "Applications" tab of the window that pops up, select "Default Settings" + and choose "Windows XP" from the drop-down menu, then click + <guibutton>'Apply'</guibutton>.</para> + </listitem> + <listitem> + <para>Launch the Staff Client</para> + <para>A new entry for the Staff Client should now appear somewhere in the + "All Applications" menu of your Linux desktop. Also, find a new desktop + shortcut for the Staff Client. To launch the Staff Client, visit the "All + Applications" menu, find a section similar to "Wine->Program + Files->Evergreen Staff Client->Evergreen Staff Client", or else launch the + Staff Client from the desktop shortcut.</para> + </listitem> + </orderedlist> + </simplesect> + <simplesect xml:id="staffclientinstallation-workstationnames"> + <title>Assigning Workstation Names</title> + <indexterm> + <primary>staff client</primary> + <secondary>assigning workstation names</secondary> + </indexterm> + <para>The Staff Client must be assigned to a library and given a unique name before it + will connect fully to the Evergreen server. The only restriction is that the workstation's + name must be unique within the assigned library. Make sure to select a workstation name + that you will remember later, and reflects the role, purpose, and/or location of a + particular computer. These names will come up later in statistical reporting, and can also + be handy when troubleshooting.</para> + <mediaobject> + <alt> + <phrase>Example of unconfigured Staff Client</phrase> + </alt> + <imageobject> + <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-1.png" format="PNG" scalefit="1" width="70%"/> + </imageobject> + </mediaobject> + <para>In order to assign a workstation a name, a user with appropriate permissions must + login to the Staff Client. In PINES, the local system administrator (OPSM) has the ability + to assign workstation names in their library system. Library managers (LIBM's) have the + ability within their branch. To assign a workstation a name, login to the system. You will + be prompted to assign the workstation a library and a name:</para> + <mediaobject> + <alt> + <phrase>Example of configured Staff Client</phrase> + </alt> + <imageobject> + <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-2.png" format="PNG" scalefit="1" width="70%"/> + </imageobject> + </mediaobject> + <para>Select the library this workstation physically operates in from the drop down + menu. In this example, we have selected "MGRL-MA". Type in a friendly name for the + workstation. In this example, we are installing the Staff Client on the director's + personal system, and have named it as such. Then click + <guibutton>'Register'</guibutton>.</para> + <para>Once you have registered your workstation + with the server, your screen will look like this:</para> + <mediaobject> + <alt> + <phrase>Example of registered Staff Client</phrase> + </alt> + <imageobject> + <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-3.png" format="PNG" scalefit="1" width="70%"/> + </imageobject> + </mediaobject> + <para>You are now ready to log into the Staff Client for the first time. Type in your + password again, and click <guibutton>'Login'</guibutton>.</para> + </simplesect> + </section> + <section> + <title>Building the Staff Client</title> + <indexterm> + <primary>staff client</primary> + <secondary>building</secondary> + </indexterm> + <para>You can also manually build the Staff Client by using the <command>make</command> + utility in the Staff Client source directory (e.g., the directory + <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.0.x/Open-ILS/xul/staff_client</filename> + for the current Evergreen version). There are a number of possible options to manually + build special versions of the Staff Client on a Linux system. Following is a list of + environment variables that can be passed to <command>make</command> to influence the + manual build process:</para> + <simplesect> + <title>Option STAFF_CLIENT_BUILD_ID</title> + <para>During the normal <emphasis>make install</emphasis> Evergreen server-side + software build process, the variable defaults to an automatically generated + date/time string, but you can also override the value of BUILD_ID.</para> + <para>The following commands could be used during the normal build process:</para> + <screen> + <prompt># as the root user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput> + <userinput>make STAFF_CLIENT_BUILD_ID=1.6.1.2 install</userinput> + </screen> + <para>The following commands will manually build the Staff Client using a different BUILD_ID.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff + Client source directory, then set the variable and build the Staff Client:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>make STAFF_CLIENT_BUILD_ID=my_test_id build</userinput> + </screen> + </simplesect> + <simplesect> + <title>Option STAFF_CLIENT_VERSION</title> + <para>During the normal <emphasis>make install</emphasis> Evergreen server-side + software build process, the variable is pulled automatically from a README file + in the Evergreen source root. The variable defaults to + <emphasis>0trunk.revision</emphasis>, where the value of "revision" is + automatically generated. You can override the value of VERSION similarly to the + BUILD_ID.</para> + <para>The following commands could be used during the normal build process:</para> + <screen> + <prompt># as the root user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput> + <userinput>make STAFF_CLIENT_VERSION=0mytest.200 install</userinput> + </screen> + <para>The following commands will manually build the Staff Client using a different VERSION.</para> + <para>If you plan to make extensions update automatically, the VERSION needs to + conform to the format recommended in + <ulink url="https://developer.mozilla.org/en/Toolkit_version_format"> + Toolkit Version Format</ulink> and newer versions need to be "higher" than older + versions.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, change + directory to the Staff Client source directory, then set the variable and build + the Staff Client:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>make STAFF_CLIENT_VERSION=0mytest.200 build</userinput> + </screen> + </simplesect> + <simplesect> + <title>Option STAFF_CLIENT_STAMP_ID variable</title> + <para>During the normal <emphasis>make install</emphasis> Evergreen server-side software + build process, this variable is generated from STAFF_CLIENT_VERSION. You can override the + value of STAMP_ID similarly to the BUILD_ID.</para> + <para>The following commands could be used during the normal build process:</para> + <screen> + <prompt># as the root user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput> + <userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp install</userinput> + </screen> + <para>The following commands will manually build the Staff Client using a + different STAMP_ID.</para> + <para>It is possible to have multiple versions of the + Staff Client by specifying a different STAMP_ID for each, possibly for different + uses or client-side customizations.</para> + <para>As the <systemitem class="username">opensrf</systemitem> + user, change directory to the Staff Client source directory, then set the variable and + build the Staff Client:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp build</userinput> + </screen> + </simplesect> + </section> + <section> + <title>Advanced Build Options</title> + <indexterm> + <primary>staff client</primary> + <secondary>building</secondary> + <tertiary>advanced build options</tertiary> + </indexterm> + <para>In addition to the basic options listed above, there are a number of advanced options for + building the Staff Client. Most are target names for the <command>make</command> utility and + require that you build the Staff Client from its source directory. See the following table for a + list of possible <command>make</command> target keywords:</para> + <table> + <title>Keywords Targets for "make" Command</title> + <tgroup align="left" cols="2" colsep="1" rowsep="1"> + <colspec colnum="1" colwidth="1.0*"/> + <colspec colnum="2" colwidth="3.0*"/> + <thead> + <row> + <entry>Keyword</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>clients</entry> + <entry>Runs "make win-client", "make linux-client", and "make + generic-client" individually</entry> + </row> + <row> + <entry>client_dir</entry> + <entry>Builds a client directory from the build directory, without + doing a rebuild. The same as "copy everything but + server/".</entry> + </row> + <row> + <entry>client_app</entry> + <entry>Prerequisite "client_dir"; removes "install.rdf" from + client directory so an APP bundle can't be installed as an + extension</entry> + </row> + <row> + <entry>client_ext</entry> + <entry>Prerequisite "client_dir"; remove "application.ini", + "autoupdate.js", "standalone_xul_app.js" from client directory so + an extension won't break Firefox</entry> + </row> + <row> + <entry>extension</entry> + <entry>Prerequisite "client_ext"; rewritten to use "client_ext"</entry> + </row> + <row> + <entry>generic-client</entry> + <entry>Prerequisite "client_app"; makes an XPI file suitable for + use with "xulrunner --install-app""</entry> + </row> + <row> + <entry>win-xulrunner</entry> + <entry>Prerequisite "client_app"; adds Windows xulrunner to client build</entry> + </row> + <row> + <entry>linux-xulrunner</entry> + <entry>Prerequisite "client_app"; adds Linux xulrunner to client build</entry> + </row> + <row> + <entry>win-client</entry> + <entry>Prerequisite "win-xulrunner"; builds "setup exe" (requires + that "nsis" package be installed, will add options for automatic + update if configured and developer options if client build was a + "make devbuild")</entry> + </row> + <row> + <entry>linux-client</entry> + <entry>Prerequisite "linux_xulrunner"; builds a "tar.bz2" bundle + of the Linux client</entry> + </row> + <row> + <entry>[generic-|win-|linux-|extension-]updates[-client]</entry> + <entry>Calls external/make_updates.sh to build full and partial + updates generic/win/linux/extension prefix limit to that + distribution; Adding <option>-client</option> builds clients and + copies them to a subdirectory of the + <filename class="directory">updates</filename> directory as well; + <option>extension-updates-client</option> doesn't exist.</entry> + </row> + </tbody> + </tgroup> + </table> + <para>Descriptions of other special build options follow:</para> + <itemizedlist> + <listitem> + <para>Developer Build</para> + <para>You can create a so-called <emphasis>developer build</emphasis> of the Staff + Client by substituting <option>devbuild</option> for <option>build</option> when + running <command>make</command>. The build will contain an extra configuration + file that enables some developer options.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, run + <command>make</command> from the Staff Client source directory:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>make devbuild</userinput> + </screen> + </listitem> + <listitem> + <para>Compressed Javascript</para> + <para>You can execute the Google <systemitem class="resource">Closure + Compiler</systemitem> utility to automatically review and compress Javascript code + after the build process completes, by substituting + <option>compress-javascript</option> for "build" when running + <command>make</command>. For more information see + <ulink url="http://code.google.com/closure/compiler/">Google Closure Compiler</ulink>.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, run the + following commands from the Staff Client source directory:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>make compress-javascript</userinput> + </screen> + <para>You can also combine Javascript review and compression, and also perform a + <emphasis>developer build</emphasis>.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, run the + following commands from the Staff Client source directory:</para> + <note>In the following <command>make</command> below, the order of options is + important!</note> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>make devbuild compress-javascript</userinput> + </screen> + </listitem> + <listitem> + <para>Automatic Update Host</para> + <para>The host used to check for automatic Staff Client updates can be overridden + by specifying the <option>AUTOUPDATE_HOST</option> option. The following commands + could have been used during the normal build process:</para> + <screen> + <prompt># as the root user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput> + <userinput>make AUTOUPDATE_HOST=localhost install</userinput> + </screen> + <para>You can manually set <option>AUTOUPDATE_HOST</option> to set up automatic + update checking. The following commands will manually build the Staff Client using + a different <option>AUTOUPDATE_HOST</option>.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, change + directory to the Staff Client source directory, then set the variable and build + the Staff Client:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>make AUTOUPDATE_HOST=localhost build</userinput> + </screen> + <para>For more information on Automatic Updates, see + <xref linkend="staffclientinstallation-autoupdate"/>.</para> + </listitem> + </itemizedlist> + </section> + <section> + <title>Installing and Activating a Manually Built Staff Client</title> + <para>The Staff Client is automatically built, installed and activated as part of the normal + <command>make <option>install</option></command> process for Evergreen server-side + software. However, if you manually build the Staff Client, then you need to take additional steps + to properly install and activate it. You also have the option of installing the Staff Client on + the same machine it was built on, or on a different machine.</para> + <para>Assuming you have already built the Staff Client, and that your installation is in the + directory <filename class="directory">/openils/var/web/xul</filename>, as the + <systemitem class="username">opensrf</systemitem> user, change directory to the + Staff Client source directory, then execute the following commands:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>mkdir -p "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput> + <userinput>cp -R build/server "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput> + </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> + <itemizedlist> + <listitem> + <para>Packaging a Generic Client</para> + <para>This build creates a Staff Client packaged as an XPI file to use with + <application>xulrunner</application>. It requires that you already have the + <systemitem>zip</systemitem> utility installed on your system. It will create the + output file <filename>evergreen_staff_client.xpi</filename>, suitable for use with + the <application>xulrunner</application> parameter + <option>--install-app</option>>.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, change + directory to the Staff Client source directory, then execute the following + commands:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>make generic-client</userinput> + </screen> + </listitem> + <listitem> + <para>Packaging a Windows Client</para> + <para>This build creates a Staff Client packaged as a Windows executable. It + requires that you already have the "unzip" utility installed on your system. It + also requires that you install <ulink url="http://nsis.sourceforge.net/">NSIS + (Nullsoft Scriptable Install System)</ulink>, a professional open source utility + package used to create Windows installers (the "makensis" utility is installed as + part of the "nsis" package). We recommend using Version 2.45 or later. This build + will create the output file "evergreen_staff_client_setup.exe".</para> + <para>If you wish for the Staff Client to have a link icon/tray icon by default, + you may wish to provide a pre-modified <application>xulrunner-stub.exe</application>. + Place it in the Staff Client source directory and <command>make</command> will + automatically use it instead of the one that comes with the downloaded + <application>XULRunner</application> release. The version of + <application>xulrunner-stub.exe</application> need not match exactly.</para> + <para>You can also use a tool such as + <ulink url="http://www.angusj.com/resourcehacker/">Resource Hacker</ulink> to + embed icons. Resource Hacker is an open-source utility used to view, modify, + rename, add, delete and extract resources in 32bit Windows executables. + See the following table for some useful icon ID strings:</para> + <table> + <title>Useful icon ID strings</title> + <tgroup align="left" cols="2" colsep="1" rowsep="1"> + <colspec colnum="1" colwidth="1.0*"/> + <colspec colnum="2" colwidth="1.0*"/> + <tbody> + <row> + <entry>IDI_APPICON</entry> + <entry>Tray icon</entry> + </row> + <row> + <entry>32512</entry> + <entry>Default window icon</entry> + </row> + </tbody> + </tgroup> + </table> + <para>As the <systemitem class="username">opensrf</systemitem> user, change + directory to the Staff Client source directory, then execute the following + commands:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>make win-client</userinput> + </screen> + </listitem> + <listitem> + <para>Packaging a Linux Client</para> + <para>This build creates a Staff Client package for Linux as a "tar.bz2" file with + <application>XULRunner</application> already bundled with it. It creates the + output file "evergreen_staff_client.tar.bz2".</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, change + directory to the Staff Client source directory, then execute the following + commands:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>make linux-client</userinput> + </screen> + </listitem> + <listitem> + <para>Packaging a Firefox Extension</para> + <para>This build requires that you already have the <systemitem>zip</systemitem> + utility installed on your system. It creates a Staff Client packaged as a Firefox + extension and creates the output file <filename>evergreen.xpi</filename>.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, change + directory to the Staff Client source directory, then execute the following + commands:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>make extension</userinput> + </screen> + </listitem> + </itemizedlist> + </section> + <section xml:id="staffclientinstallation-autoupdate"> + <title>Staff Client Automatic Updates</title> + <indexterm> + <primary>staff client</primary> + <secondary>automatic updates</secondary> + </indexterm> + <para>It is possible to set up support for automatic Staff Client updates, either during the + normal Evergreen server-side build process, or by manually building the Staff Client with certain + special options.</para> + <caution> + <para>Automatic update server certificate requirements are more strict than normal + server requirements. Firefox and <application>XULRunner</application> will both ignore + any automatic update server that is not validated by a trusted certificate authority. + Servers with exceptions added to force the Staff Client to accept them + <emphasis>WILL NOT WORK</emphasis>.</para> + <para>In addition, automatic updates have special requirements for the file + <filename>update.rdf</filename>:</para> + <orderedlist> + <listitem>It must be served from an SSL server, or</listitem> + <listitem>It must be signed with the + <ulink url="https://developer.mozilla.org/en/McCoy">McCoy</ulink> tool.</listitem> + </orderedlist> + <para>You can pre-install the signing key into the file <filename>install.rdf</filename> + directly, or install it into a copy as <filename>install.mccoy.rdf</filename>. If the + latter exists it will be copied into the build instead of the original file + <filename>install.rdf</filename>.</para> + </caution> + <simplesect> + <title>Autoupdate Host</title> + <para>The name of the automatic update host can be provided in either of two ways:</para> + <orderedlist> + <listitem>At configuration time for the normal build of the Evergreen server-side + software, or</listitem> + <listitem>During a manual Staff Client build process.</listitem> + </orderedlist> + <para/> + <itemizedlist> + <listitem> + <para>At configuration time for the normal build of Evergreen server-side + software</para> + <para>This must be done when the Evergreen server-side software is first + configured (see <xref linkend="serversideinstallation-configure"/>). As + the <systemitem class="username">opensrf</systemitem> user, use the + utility "configure" as shown:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput> + <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf --with-updateshost=hostname</userinput> + <userinput>make</userinput> + </screen> + </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 + <systemitem class="domainname">example.com</systemitem>) then + the URL will be a secure URL (such as + <systemitem class="domainname">https://example.com</systemitem>. + If you wish to use a non-HTTPS URL then prefix the hostname with + <systemitem class="domainname">http://</systemitem> (such as + <systemitem class="domainname">http://example.com</systemitem>).</para> + <para>If neither option is used then, by default, the Staff Client will + not include the automatic update preferences.</para> + </listitem> + </itemizedlist> + </simplesect> + <simplesect> + <title>Building Updates</title> + <indexterm> + <primary>staff client</primary> + <secondary>automatic updates</secondary> + <tertiary>building</tertiary> + </indexterm> + <para>Similar to building clients, the targets <option>generic-updates</option>, + <option>win-updates</option>, <option>linux-updates</option>, and + <option>extension-updates</option> can be used individually with <command>make</command> + to build the update files for the Staff Client. To build all the targets at once, simply + use the target <option>updates</option>.</para> + <para>A full update will be built for each specified target (or for all if you use the + target <option>updates</option>). For all but extensions any previous full updates + (archived by default in the directory + <filename class="directory">/openils/var/updates/archives</filename>) will be used to make partial + updates. Partial updates tend to be much smaller and will thus download more quickly, but + if something goes wrong with a partial update the full update will be used as a + fallback. Extensions do not currentlysupport partial updates.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to + the Staff Client source directory, then execute the following commands:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + </screen> + <para>Command to build all updates at once:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>make updates</userinput> + </screen> + <para>commands to build updates individually:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>make generic-updates</userinput> + <userinput>make win-updates</userinput> + <userinput>make linux-updates</userinput> + <userinput>make extension-updates</userinput> + </screen> + </simplesect> + <simplesect> + <title>Building updates with clients</title> + <indexterm> + <primary>staff client</primary> + <secondary>automatic updates</secondary> + <tertiary>building with clients</tertiary> + </indexterm> + <para>To save time and effort you can build updates and manual download clients at the + same time by adding <option>-client</option> to each target name. For instance, you can + specify <option>win-updates-client</option>. You can also specify + <option>updates-client</option> to build all the targets at once. This does not work for + <option>extension-updates</option>.</para> + <para>The clients will be installed alongside the updates and listed on the + <filename>manualupdate.html</filename> page, rather than left in the Staff Client + directory.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to + the Staff Client source directory, then execute the following commands:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + </screen> + <para>Command to build all updates at once:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>make updates-client</userinput> + </screen> + <para>Command to build updates individually:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>make generic-updates-client</userinput> + <userinput>make win-updates-client</userinput> + <userinput>make linux-updates-client</userinput> + </screen> + </simplesect> + <simplesect> + <title>Activating the Update Server</title> + <indexterm> + <primary>staff client</primary> + <secondary>automatic updates</secondary> + <tertiary>activating the update server</tertiary> + </indexterm> + <para>This section reviews scripts associated with the update server, and requires some + final adjustments to file permissions.</para> + <para>The Apache example configuration creates an "updates" directory that, by default, + points to the directory <filename class="directory">/openils/var/updates/pub</filename>. + This directory contains one HTML file and several specially-named script files.</para> + <para>The <filename>updatedetails.html</filename> file is the fallback web page for the + update details. The <filename>check</filename> script is used for + <application>XULRunner</application> updates. The <filename>update.rdf</filename> script + is used for extension updates. The <filename>manualupdate.html</filename> file checks for + clients to provide download links when automatic updates have failed and uses the download + script to force a download of the generic client XPI (compared to Firefox trying to + install it as an extension).</para> + <para>The following scripts should be marked as executable: <filename>check</filename>, + <filename>download</filename>, <filename>manualupdate.html</filename>, + <filename>update.rdf</filename>. Execute the following commands:</para> + <screen> + <prompt># as the root user</prompt> + <userinput>cd /openils/var/updates/pub</userinput> + <userinput>chmod +x check download manualupdate.html update.rdf</userinput> + </screen> + </simplesect> + </section> + <section> + <title>Other tips</title> + <simplesect> + <title>Multiple workstations on one install</title> + <para>Multiple workstation registrations for the same server can be accomplished with a + single Staff Client install by using multiple profiles. When running + <application>XULRunner</application> you can specify the option "-profilemanager" or "-P" + (uppercase "P") to force the Profile Manager to start. Unchecking the "Don't ask at + startup" option will make this the default.</para> + <para>Once you have opened the Profile Manager you can create additional profiles, one for + each workstation you wish to register. You may need to install SSL exceptions for each + profile.</para> + <para>When building targets <option>win-client</option>, + <option>win-updates-client</option>, or <option>updates-client</option>, you can specify + <option>NSIS_EXTRAOPTS=-DPROFILES</option> to add an <guimenuitem>Evergreen Staff Client + Profile Manager</guimenuitem> option to the start menu.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to + the Staff Client source directory, then execute the following commands:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput> + <userinput>make NSIS_EXTRAOPTS=-DPROFILES win-client</userinput> + </screen> + </simplesect> + <simplesect> + <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 <application>XULRunner</application> with + the option <option>-no-remote</option> (in addition to <option>-profilemanger</option> or + <option>-P</option> if neeeded). Instead of <application>XULRunner</application> 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> + </simplesect> + </section> + </section> + </section> + <section xml:id="staffclientinstallation-running-staffclient"> + <title>Running the Staff Client</title> + <indexterm> + <primary>staff client</primary> + <secondary>running</secondary> + <tertiary>linux</tertiary> + </indexterm> + <para>Run the Staff Client on a Linux system by using the application + <application>XULRunner</application> (installed automatically and by default with Firefox version 3.0 + and later on Ubuntu and Debian distributions).</para> + <para>For example, if the source files for the Evergreen installation are in the directory + <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2/</filename>, start the Staff + Client as shown in the following example:</para> + <screen> + <prompt># as the opensrf user</prompt> + <userinput>xulrunner /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client/build/application.ini</userinput> + </screen> + <simplesect xml:id="staffclientinstallation-proxy"> + <title>Running the Staff Client over an SSH Tunnel</title> + <indexterm> + <primary>staff client</primary> + <secondary>running through an SSH tunnel</secondary> + </indexterm> + <para>The Staff Client can use an SSH tunnel as a SOCKS 5 proxy.</para> + <simplesect> + <title>Configuring 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> + <itemizedlist> + <listitem> + <para>Firewalls may prevent you from reaching the server. This may happen when you + are connecting the Staff Client to a test server that should not be available + generally, or it may be the result of network design priorities other than ease of + use.</para> + </listitem> + <listitem> + <para>You may wish to improve security where Staff Client traffic may be + susceptible to network eavesdropping. This is especially true when wireless is + otherwise the best option for connecting a staff machine to the network.</para> + </listitem> + </itemizedlist> + </simplesect> + <simplesect> + <title>Setting Up an SSH Tunnel</title> + <para>You will need a server that allows you to log in via SSH and has network access to + the Evergreen server you want to reach. You will use your username and password for that + <systemitem class="protocal">SSH</systemitem> server to set up a tunnel.</para> + <para>For Windows users, one good solution is the open-source utility + <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty/">PuTTY</ulink>, a free + <systemitem class="protocal">telnet/SSH</systemitem> client. When setting up a PuTTY + session:</para> + <mediaobject> + <alt> + <phrase>Setting up an SSH tunnel in PuTTY</phrase> + </alt> + <imageobject> + <imagedata fileref="../media/staffclientinstallation-proxy-putty.png" format="PNG" scalefit="1" width="70%"/> + </imageobject> + </mediaobject> + <orderedlist> + <listitem>Use the menu on the left to go to Connection > SSH > Tunnels.</listitem> + <listitem>Enter ''9999'' in the "Source port".</listitem> + <listitem>Choose "Dynamic". Do not enter anything in the Destination text entry box.</listitem> + <listitem>Click <guibutton>'Add'</guibutton>; "D9999" will now appear in the "Forwarded + ports" list.</listitem> + <listitem>Use the menu on the left to go back to "Session", and enter the host name of the + <systemitem class="protocal">SSH</systemitem> server.</listitem> + <listitem>A window will open up so that you can enter your username and password. Once you + are logged in, the tunnel is open.</listitem> + </orderedlist> + <para>See <ulink url="http://inside.mines.edu/~gmurray/HowTo/sshNotes.html">How to set up + <systemitem class="protocal">SSH</systemitem> (for the beginner)</ulink> for information on + setting up <systemitem class="protocal">SSH</systemitem> for other client operating + systems,</para> + </simplesect> + <simplesect> + <title>Configuring the Staff Client to Use the <systemitem class="protocal">SSH</systemitem> Tunnel</title> + <para>In order to tell the Staff Client that all traffic should be sent through the + <systemitem class="protocal">SSH</systemitem> tunnel just configured, you must edit the + file <filename>C:\Program Files\Evergreen Staff + Client\greprefs\all.js</filename>. Search this file for the word + <literal>socks</literal> to find the appropriate section for the following + changes.</para> + <mediaobject> + <alt> + <phrase>The SOCKS section of "all.js" before changes</phrase> + </alt> + <imageobject> + <imagedata fileref="../media/staffclientinstallation-proxy-socks-1.png" format="PNG" scalefit="1" width="70%"/> + </imageobject> + </mediaobject> + <para>Make the following changes:</para> + <itemizedlist> + <listitem>Change the value of <literal>network.proxy.socks</literal> from + <literal>""</literal> to <literal>localhost</literal>.</listitem> + <listitem>Change the value of <literal>network.proxy.socks_port</literal> from + <literal>0</literal> to <literal>9999</literal>.</listitem> + </itemizedlist> + <mediaobject> + <alt> + <phrase>The SOCKS section of "all.js" after changes</phrase> + </alt> + <imageobject> + <imagedata fileref="../media/staffclientinstallation-proxy-socks-2.png" format="PNG" scalefit="1" width="70%"/> + </imageobject> + </mediaobject> + <para>If everything is working correctly, you should now be able to run the Staff Client and all + its data will be sent encrypted through the <systemitem class="protocal">SSH</systemitem> tunnel + you have just configured.</para> + </simplesect> + </simplesect> + </section> +</chapter> diff --git a/1.6/media/serversideinstallation-staffclient-running-2.png b/1.6/media/serversideinstallation-staffclient-running-2.png index a532686454..33abe1371a 100644 Binary files a/1.6/media/serversideinstallation-staffclient-running-2.png and b/1.6/media/serversideinstallation-staffclient-running-2.png differ diff --git a/1.6/media/staffclientinstallation-staffclient-1.png b/1.6/media/staffclientinstallation-staffclient-1.png index 8e821c9f3c..b47a033370 100644 Binary files a/1.6/media/staffclientinstallation-staffclient-1.png and b/1.6/media/staffclientinstallation-staffclient-1.png differ diff --git a/1.6/media/staffclientinstallation-staffclient-2.png b/1.6/media/staffclientinstallation-staffclient-2.png index 8c4adca68d..dd224ab0d2 100644 Binary files a/1.6/media/staffclientinstallation-staffclient-2.png and b/1.6/media/staffclientinstallation-staffclient-2.png differ