-<?xml version="1.0" encoding="UTF-8"?>\r
-<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">\r
- <info>\r
- <title>Installation of Evergreen Staff Client Software</title>\r
- <abstract>\r
- <para>This section describes installation of the Evergreen Staff Client software.</para>\r
- </abstract>\r
- </info>\r
- <section xml:id="staffclientinstallation-installing-staffclient">\r
- <title>Installing the Staff Client</title>\r
- <indexterm><primary>staff client</primary><secondary>installing</secondary></indexterm>\r
- <simplesect>\r
- <title>Installing a Pre-Built Staff Client</title>\r
- <para>You can install the pre-built Staff Client available for Windows, MAC or Linux.</para>\r
- <simplesect>\r
- <title>Installing on Windows</title>\r
- <indexterm><primary>staff client</primary><secondary>installing</secondary><tertiary>Windows</tertiary></indexterm>\r
- <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 \r
- 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. \r
- A screen that looks similar to this should appear:</para>\r
- <mediaobject>\r
- <imageobject>\r
- <imagedata fileref="../media/staffclientinstallation-staffclient-1.png" format="PNG" scalefit="1" width="70%"/>\r
- </imageobject>\r
- <textobject>\r
- <phrase>Running the Staff Client installer</phrase>\r
- </textobject>\r
- </mediaobject>\r
- <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 \r
- where to install the software, ask about where to place icons, and then will install the software on your workstation.</para>\r
- <para>When you run the Staff Client for the first time, a screen similar to this should appear:</para>\r
- <mediaobject>\r
- <imageobject>\r
- <imagedata fileref="../media/staffclientinstallation-staffclient-2.png" format="PNG" scalefit="1" width="70%"/>\r
- </imageobject>\r
- <textobject>\r
- <phrase>Running the Staff Client for the first time</phrase>\r
- </textobject>\r
- </mediaobject>\r
- <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. \r
- 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 \r
- Server</guibutton>.</para>\r
- <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 \r
- <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 \r
- it a workstation name. This is covered in <xref linkend="staffclientinstallation-workstationnames"/>.</para>\r
- </simplesect>\r
- <simplesect>\r
- <title>Installing on Mac OS</title>\r
- <indexterm><primary>staff client</primary><secondary>installing</secondary><tertiary>Mac OS</tertiary></indexterm>\r
- <para>A Mac package that contains the current version of the Staff Client is available for use with XULRunner.</para>\r
- <simplesect>\r
- <title>Evergreen Indiana Pkg file [Evergreen v1.2.3.0]</title>\r
- <orderedlist>\r
- <listitem>Download and install the latest version of XULRunner for Mac OS. Release notes can be found here: \r
- <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\r
- </ulink>. Note, later versions may not work correctly.</listitem>\r
- <listitem>Download and install the Mac Installation package for the 1_2_3_0 Version Staff Client from \r
- <ulink url="http://evergreen.lib.in.us/opac/extras/files/evergreen_osx_staff_client_1_2_3.zip">\r
- http://evergreen.lib.in.us/opac/extras/files/evergreen_osx_staff_client_1_2_3.zip</ulink>.</listitem>\r
- <listitem>To upgrade to a more recent version of the Staff Client, you can copy the <filename class="directory">build</filename> directory from a \r
- working Windows installation of the desired version of the Staff Client to your Mac. The required files may be located in a directory like \r
- this on the Windows machine: \r
- <filename class="directory">C:\Program Files\Evergreen Staff Client\build</filename>. Copy these files into the \r
- <filename class="directory">Resources</filename> folder within the \r
- <package>Open-ILS</package> package in your <filename class="directory">Applications</filename> directory on the Mac, overwriting files with the \r
- same names.</listitem> <listitem>Drag the application's icon into your toolbar for easier access.</listitem>\r
- </orderedlist>\r
- <para/>\r
- <para>When you run the Staff Client installer, a screen will appear that looks similar to this:</para>\r
- <mediaobject>\r
- <imageobject>\r
- <imagedata fileref="../media/staffclientinstallation-staffclient-3.png" format="PNG" scalefit="1" width="20%"/>\r
- </imageobject>\r
- <textobject>\r
- <phrase>Running the Staff Client installer</phrase>\r
- </textobject>\r
- </mediaobject>\r
- <para>Click <guibutton>continue</guibutton>, accept the license, then finish the installation. The application will be located at the destination you \r
- selected during installation. You will then be able to drag the application into your toolbar for easier access.</para>\r
- <mediaobject>\r
- <imageobject>\r
- <imagedata fileref="../media/staffclientinstallation-staffclient-4.png" format="PNG" scalefit="1" width="20%"/>\r
- </imageobject>\r
- <textobject>\r
- <phrase>Finishing the installation</phrase>\r
- </textobject>\r
- </mediaobject>\r
- </simplesect>\r
- <simplesect>\r
- <title>Running directly using XULRunner</title>\r
- <indexterm><primary>staff client</primary><secondary>XULRunner</secondary></indexterm>\r
- <indexterm><primary>XULRunner</primary></indexterm>\r
- <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>\r
- <table>\r
- <title>Evergreen / XULRunner Dependencies</title>\r
- <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
- <colspec colnum="1" colwidth="1.0*"/>\r
- <colspec colnum="2" colwidth="3.0*"/>\r
- <tbody>\r
- <row>\r
- <entry>Evergreen 1.6.x.x</entry>\r
- <entry>XULrunner 1.9</entry>\r
- </row>\r
- <row>\r
- <entry>Evergreen 1.4.x.x</entry>\r
- <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry>\r
- </row>\r
- <row>\r
- <entry>Evergreen 1.2.x.x</entry>\r
- <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- <note>If you have issues removing previously installed XULRunner versions see <xref linkend="staffclientinstallation-remove-xulrunner"/> for further information.\r
- </note>\r
- <para>The Staff Client data from the directory <filename class="directory">./staff_client/build</filename> must be placed somewhere on the machine \r
- (e.g. <filename class="directory">~/Desktop/Evergreen_Staff_Client</filename>). Remember to call XULRunner with the full path to the binary, followed by the \r
- install command and the path to the client data:</para>\r
-<screen>\r
-<userinput>/Library/Frameworks/XUL.framework/xulrunner-bin --install-app ~/Desktop/Evergreen_Staff_Client</userinput>\r
-</screen>\r
- <para>This command should exit quietly. The folder <filename class="directory">/Applications/OpenILS</filename> will be created, containing a launcher \r
- named <application>open_ils_staff_client</application>.</para>\r
- </simplesect>\r
- <simplesect xml:id="staffclientinstallation-remove-xulrunner">\r
- <title>Removing previously installed XULRunner versions</title>\r
- <indexterm><primary>XULRunner</primary><secondary>removing previous versions</secondary></indexterm>\r
- <para>If you already have a newer version installed, per the release notes, you will need to remove the entire directory \r
- <filename class="directory">/Library/Frameworks/XUL.framework</filename> before downgrading.</para>\r
- <para>In addition, you may also need to remove the previous file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> .</para>\r
- <para>If file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> does not exist (possibly in newer OSX releases), you need to flush the \r
- file <filename>receiptdb</filename>.</para>\r
- <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>\r
- <simplesect>\r
- <title>Flush Receiptdb file:</title>\r
- <para>First, get the package identifier, then purge/forget the build that was initially installed:</para>\r
-<screen>\r
-<userinput>sudo pkgutil --pkgs > /tmp/pkgs.txt</userinput>\r
-<userinput>sudo pkgutil --forget org.mozilla.xulrunner</userinput>\r
-</screen>\r
- <note>It may not be necessary to edit the file <filename>/Library/Receipts/InstallHistory.plist</filename> after deleting the folder \r
- <filename class="directory">XUL.framework</filename>. \r
- See <ulink url="http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html">\r
- http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html</ulink> for more information.</note>\r
- </simplesect>\r
- </simplesect>\r
- <simplesect>\r
- <title>Creating an APP file: Staff Client & XULRunner Bundled</title>\r
- <para>An APP file is basically a folder. Start with a folder stucture like this:</para>\r
- <screen>\r
- * Evergreen.app\r
- * Contents\r
- * Frameworks\r
- * Resources\r
- * MacOS\r
- </screen>\r
- <para>Create an APP folder structure with the following commands:</para>\r
-<screen>\r
-<userinput>mkdir -p Evergreen.app/Contents/Frameworks</userinput>\r
-<userinput>mkdir -p Evergreen.app/Contents/Resources</userinput>\r
-<userinput>mkdir -p Evergreen.app/Contents/MacOS</userinput>\r
-</screen>\r
- <para/>\r
- <orderedlist>\r
- <listitem>\r
- <para>Create a new file in the folder <filename class="directory">Evergreen.app/Contents/Info.plist</filename> containing the following data \r
- (adjust for your version of Evergreen):</para>\r
-<programlisting language="xml"><![CDATA[\r
-<?xml version="1.0" encoding="UTF-8"?>\r
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" \r
- "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\r
-<plist version="1.0">\r
-<dict>\r
- <key>CFBundleExecutable</key>\r
- <string>xulrunner</string>\r
- <key>CFBundleGetInfoString</key>\r
- <string>OpenILS open_ils_staff_client rel_1_6_0_7</string>\r
- <key>CFBundleInfoDictionaryVersion</key>\r
- <string>6.0</string>\r
- <key>CFBundleName</key>\r
- <string>Evergreen Staff Client</string>\r
- <key>CFBundlePackageType</key>\r
- <string>APPL</string>\r
- <key>CFBundleShortVersionString</key>\r
- <string>rel_1_6_0_7</string>\r
- <key>CFBundleVersion</key>\r
- <string>rel_1_6_0_7.rel_1_6_0_7</string>\r
- <key>NSAppleScriptEnabled</key>\r
- <true/>\r
- <key>CFBundleTypeIconFile</key>\r
- <string>Evergreen.icns</string>\r
-</dict>\r
-</plist>\r
-]]></programlisting> \r
- </listitem>\r
- <listitem>Download and install an appropriate Mac OS package of XULRunner from the Mozilla website (see above for recommendations).</listitem>\r
- <listitem>\r
- <para>Make a copy of the folder <filename class="directory">/Library/Frameworks/XUL.Framework</filename> inside your APP file. It should \r
- look something like this:</para>\r
-<screen>\r
-* Evergreen.app/\r
-__* Contents/\r
-____* Frameworks/\r
-______* XUL.Framework/\r
-______* Versions/\r
-________* Current -> 1.9.1.3 (symlink)\r
-________* 1.9.1.3/\r
-______* XUL -> Versions/Current/XUL\r
-______* libxpcom.dylib -> Versions/Current/libxpcom.dylib\r
-______* xulrunner-bin -> Versions/Current/xulrunner-bin\r
-</screen>\r
- </listitem>\r
- <listitem>Copy <filename>XUL.Framework/Versions/Current/xulrunner</filename> into the folder <filename class="directory">Evergreen.app/MacOS</filename> \r
- (do not symlink; copy the file).</listitem>\r
- <listitem>\r
- <para>Make <filename>Evergreen.app/Resources</filename> the root of your Evergreen application files like this:</para>\r
-<screen>\r
-* Evergreen.app/\r
-__* Contents/\r
-____* Resources/\r
-______* BUILD_ID\r
-______* application.ini\r
-______* chrome/\r
-______* components/\r
-______* etc.\r
-</screen>\r
- </listitem>\r
- <listitem>Put a Mac format icon file named <filename>Evergreen.icns</filename> in <filename class="resources">Resources</filename>.</listitem>\r
- </orderedlist>\r
- </simplesect>\r
- </simplesect>\r
- <simplesect>\r
- <title>Installing on Linux</title>\r
- <simplesect>\r
- <title>Quick Upgrade of the Staff Client</title>\r
- <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 \r
- 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 \r
- the remote workstation.</para>\r
- <para>The following example assumes you already have an <systemitem class="username">opensrf</systemitem> user account on both the server and the \r
- 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 \r
- in the following example.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then recursively copy the \r
- entire directory tree to the remote workstation:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>scp -r build user@client.linux.machine:~/eg-client-x.x.x.x/</userinput>\r
-</screen>\r
- <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 \r
- shown:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>xulrunner ~/eg-client-x.x.x.x/build/application.ini</userinput>\r
-</screen>\r
- </simplesect>\r
- <simplesect>\r
- <title>Building the Staff Client on the Server</title>\r
- <indexterm><primary>staff client</primary><secondary>building on the server</secondary></indexterm>\r
- <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 \r
- software, using a procedure similar to this:</para>\r
-<screen>\r
-<userinput>cd ~/ILS/Open-ILS/xul/staff_client</userinput>\r
-<userinput>make STAFF_CLIENT_BUILD_ID='12345'</userinput>\r
-<userinput>mkdir /openils/var/web/xul/</userinput>\r
-<userinput>mkdir /openils/var/web/xul/12345/</userinput>\r
-<userinput>cd build/</userinput>\r
-<userinput>cp -R server/ /openils/var/web/xul/12345/</userinput>\r
-</screen>\r
- <para>The Staff Client can be run from the build directory using this command:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>xulrunner application.ini</userinput>\r
-</screen>\r
- <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 \r
- 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>\r
- <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 \r
- 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> \r
- on the running Staff Client.</para>\r
- <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 \r
- 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 \r
- that directory.</para>\r
-<screen>\r
-<userinput>su - root</userinput>\r
-<userinput>cd /openils/var/web/xul</userinput>\r
-<userinput>ln -s SERVER_BUILD_ID/ CLIENT_BUILD_ID</userinput>\r
-</screen>\r
- </simplesect>\r
- <simplesect>\r
- <title>Building the Staff Client on the client Machine</title>\r
- <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 \r
- the Staff Client on a Linux system without installing the Evergreen Server component. This is a relatively simple process compared to server installation, but \r
- 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 \r
- other distributions (the instructions should work as-is for Ubuntu or Ubuntu derivatives).</para>\r
- <procedure>\r
- <step>\r
- <para>Prerequisites</para>\r
- <para>Both <application>subversion</application> and <application>xulrunner</application> are required to build the Staff Client. As \r
- the <systemitem class="username">root</systemitem> user, use <command>apt-get</command> to install packages for \r
- <application>subversion</application> and <application>xulrunner</application>. You can also use <command>synaptic</command>, the graphical \r
- user interface for <command>apt-get</command>. For <application>subversion</application>, select the latest version; for \r
- <application>xulrunner</application>, select version <emphasis>1.8.1.4-2ubuntu5</emphasis>.</para>\r
-<screen>\r
-<userinput>sudo apt-get install subversion</userinput>\r
-<userinput>sudo apt-get install xulrunner</userinput>\r
-</screen>\r
- </step>\r
- <step>\r
- <para>Download the Source Code</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para>Determine which version is needed</para>\r
- <para>For most end-users, a specific version is required to communicate properly with the Evergreen server. Check with your \r
- system admininstrator, IT person, or HelpDesk to determine which Staff Client versions are supported.</para>\r
- <para>Next, you need to determine which <emphasis>tag</emphasis> to use when downloading the source code. Tags are markers in \r
- 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, \r
- or at least a community-recognized release version.</para>\r
- <para>To determine which tag to use, browse to \r
- <ulink url="http://svn.open-ils.org/trac/ILS/browser">http://svn.open-ils.org/trac/ILS/browser</ulink>. \r
- Look in the <guilabel>Visit</guilabel> drop-down box; see the list of <guilabel>Branches</guilabel> and, further down, a list \r
- of <guilabel>Tags</guilabel>. You may have to do some guesswork, but it is fairly straightforward to determine which tag to use. \r
- 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 \r
- 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>\r
- </listitem>\r
- <listitem>\r
- <para>Download the Code</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, open a terminal (command-line prompt) and navigate \r
- to the directory in which you wish to download the Staff Client. Use the following commands to download the proper version of\r
- the source code by tag name:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput>\r
-<userinput>svn co rel_1_2_1_4/</userinput>\r
-</screen>\r
- <para>Remember to change "rel_1_6_1_2" to the appropriate tag for your installation.</para>\r
- </listitem>\r
- </itemizedlist>\r
- </step>\r
- <step>\r
- <para>Build the Staff Client</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para>Evergreen 1.2.x</para>\r
- <para>In the following example, navigate to the directory in which the source code was downloaded, then navigate to the \r
- proper subdirectory and run the "make" utility to actually build the Staff Client. Remember to check with your system \r
- administrator about which Staff Client BUILD_ID to use. The server checks the Staff Client BUILD_ID against itself to \r
- determine whether or not a connecting client is supported. For instance, for the PINES installation (version 1.2.1.4) the \r
- supported BUILD_ID is "rel_1_2_1_4". Modify the following commands accordingly.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, run the following commands to build the Staff Client:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput>\r
-<userinput>cd Open-ILS/xul/staff_client</userinput>\r
-<userinput>make STAFF_CLIENT_BUILD_ID='rel_1_6_1_2'</userinput>\r
-</screen>\r
- </listitem>\r
- </itemizedlist>\r
- </step>\r
- <step>\r
- <para>Run the Staff Client (from the command line)</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, navigate to the <filename class="directory">build/</filename> subdirectory \r
- (not <filename class="directory">staff_client/</filename>) and run the following command:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>xulrunner application.ini</userinput>\r
-</screen>\r
- </step>\r
- <step>\r
- <para>Cleaning Up / Creating Shortcuts</para>\r
- <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 \r
- 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 \r
- the <systemitem class="username">opensrf</systemitem> user, issue the following commands to create a clean "staging" directory in which to place \r
- the finished Staff Client, and to copy into it the "staff_client" directory:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>mkdir ~/<Destination Directory></userinput>\r
-<userinput>cd ~/<Download Directory>/Open-ILS/xul/</userinput>\r
-<userinput>cp -r staff_client ~/<Destination Directory></userinput>\r
-</screen>\r
- <para>Finally, test the Staff Client to verify that all the necessary files were moved to the destination directory:</para>\r
-<screen>\r
-<userinput>cd ~/<Destination Directory>/staff_client/build</userinput>\r
-<userinput>xulrunner application.ini</userinput>\r
-</screen>\r
- <para>If there were no problems, then finish the cleanup by removing the original download directory and all subdirectories:</para>\r
-<screen>\r
-<userinput>rm -r -f ~/<Download Directory></userinput>\r
-</screen>\r
- <para>You may wish to create <menuchoice><guimenu>Desktop</guimenu><guimenuitem>Start Menu</guimenuitem><guimenuitem>K-Menu</guimenuitem>\r
- </menuchoice> shortcuts for the Staff Client using the command <command>xulrunner ~/<Destination Directory>/staff_client/build/application.ini\r
- </command> as the target.</para>\r
- </step>\r
- </procedure>\r
- </simplesect>\r
- <simplesect>\r
- <title>Using Wine to Install on Linux</title>\r
- <indexterm><primary>staff client</primary><secondary>using wine to install on Linux</secondary></indexterm>\r
- <para>The Linux application <application>Wine</application> is another alternative if you wish to install the packaged Windows versions rather than building \r
- 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 \r
- the Staff Client. More information about Wine can be found at \r
- <ulink url="http://www.winehq.org/site/docs/wineusr-guide/getting-wine">http://www.winehq.org/site/docs/wineusr-guide/getting-wine</ulink>.</para>\r
- <para>As the <systemitem class="username">root</systemitem> user, use <command>apt-get</command> to install the package for <application>Wine</application>. \r
- You can also use <command>synaptic</command>, the graphical user interface.</para>\r
- <orderedlist>\r
- <listitem>\r
- <para>Install wine</para>\r
-<screen>\r
-<userinput>sudo apt-get install wine</userinput>\r
-</screen>\r
- </listitem>\r
- <listitem>\r
- <para>Download Windows installer for the Staff Client</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, run the following commands to download the Windows installer for the \r
- proper Staff Client from the <ulink url="http://open-ils.org">open-ils.org</ulink> website and place it in a temporary directory:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput>\r
-<userinput>wget http://open-ils.org/downloads/evergreen-setup-rel_version-number.exe</userinput>\r
-</screen>\r
- </listitem>\r
- <listitem>\r
- <para>Run the downloaded Windows installer</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, navigate to the directory where you downloaded the Windows executable \r
- file, then execute it:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput>\r
-<userinput>wine evergreen-setup-rel_version-number.exe</userinput>\r
-</screen>\r
- <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; \r
- in the "Applications" tab of the window that pops up, select "Default Settings" and choose "Windows XP" from the drop-down menu, then \r
- click <guibutton>Apply</guibutton>.</para>\r
- </listitem>\r
- <listitem>\r
- <para>Launch the Staff Client</para>\r
- <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 \r
- desktop shortcut for the Staff Client. To launch the Staff Client, visit the "All Applications" menu, find a section similar to "Wine->Program \r
- Files->Evergreen Staff Client->Evergreen Staff Client", or else launch the Staff Client from the desktop shortcut.</para>\r
- </listitem>\r
- </orderedlist>\r
- </simplesect>\r
- <simplesect xml:id="staffclientinstallation-workstationnames">\r
- <title>Assigning Workstation Names</title>\r
- <indexterm><primary>staff client</primary><secondary>assigning workstation names</secondary></indexterm>\r
- <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 \r
- 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 \r
- 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>\r
- <mediaobject>\r
- <imageobject>\r
- <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-1.png" format="PNG" scalefit="1" width="70%"/>\r
- </imageobject>\r
- <textobject>\r
- <phrase>Example of unconfigured Staff Client</phrase>\r
- </textobject>\r
- </mediaobject>\r
- <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 \r
- (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 \r
- workstation a name, login to the system. You will be prompted to assign the workstation a library and a name:</para>\r
- <mediaobject>\r
- <imageobject>\r
- <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-2.png" format="PNG" scalefit="1" width="70%"/>\r
- </imageobject>\r
- <textobject>\r
- <phrase>Example of configured Staff Client</phrase>\r
- </textobject>\r
- </mediaobject>\r
- <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 \r
- 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 \r
- click <guibutton>Register</guibutton>.</para>\r
- <para>Once you have registered your workstation with the server, your screen will look like this:</para>\r
- <mediaobject>\r
- <imageobject>\r
- <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-3.png" format="PNG" scalefit="1" width="70%"/>\r
- </imageobject>\r
- <textobject>\r
- <phrase>Example of registered Staff Client</phrase>\r
- </textobject>\r
- </mediaobject>\r
- <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>\r
- </simplesect>\r
- </simplesect>\r
- <simplesect>\r
- <title>Building the Staff Client</title>\r
- <indexterm><primary>staff client</primary><secondary>building</secondary></indexterm>\r
- <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 \r
- <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 \r
- 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 \r
- <command>make</command> to influence the manual build process:</para>\r
- <simplesect>\r
- <title>Option STAFF_CLIENT_BUILD_ID</title>\r
- <para>During the normal <emphasis>make install</emphasis> Evergreen server-side software build process, the variable defaults to an automatically generated \r
- date/time string, but you can also override the value of BUILD_ID.</para>\r
- <para>The following commands could be used during the normal build process:</para>\r
-<screen>\r
-<userinput>su - root</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]</userinput>\r
-<userinput>make STAFF_CLIENT_BUILD_ID=[version ID] install</userinput>\r
-</screen>\r
- <para>The following commands will manually build the Staff Client using a different BUILD_ID.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then set the variable and build \r
- the Staff Client:</para> \r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>make STAFF_CLIENT_BUILD_ID=my_test_id build</userinput>\r
-</screen>\r
- </simplesect>\r
- <simplesect>\r
- <title>Option STAFF_CLIENT_VERSION</title>\r
- <para>During the normal <emphasis>make install</emphasis> Evergreen server-side software build process, the variable is pulled automatically from a README file \r
- in the Evergreen source root. The variable defaults to <emphasis>0trunk.revision</emphasis>, where the value of "revision" is automatically generated. You \r
- can override the value of VERSION similarly to the BUILD_ID.</para>\r
- <para>The following commands could be used during the normal build process:</para>\r
-<screen>\r
-<userinput>su - root</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]</userinput>\r
-<userinput>make STAFF_CLIENT_VERSION=0mytest.200 install</userinput>\r
-</screen>\r
- <para>The following commands will manually build the Staff Client using a different VERSION.</para>\r
- <para>If you plan to make extensions update automatically, the VERSION needs to conform to the format recommended in \r
- <ulink url="https://developer.mozilla.org/en/Toolkit_version_format">Toolkit Version Format</ulink> and newer versions need to be "higher" than older \r
- versions.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then set the variable and build \r
- the Staff Client:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>make STAFF_CLIENT_VERSION=0mytest.200 build</userinput>\r
-</screen>\r
- </simplesect>\r
- <simplesect>\r
- <title>Option STAFF_CLIENT_STAMP_ID variable</title>\r
- <para>During the normal <emphasis>make install</emphasis> Evergreen server-side software build process, this variable is generated from STAFF_CLIENT_VERSION. \r
- You can override the value of STAMP_ID similarly to the BUILD_ID.</para>\r
- <para>The following commands could be used during the normal build process:</para>\r
-<screen>\r
-<userinput>su - root</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]</userinput>\r
-<userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp install</userinput>\r
-</screen>\r
- <para>The following commands will manually build the Staff Client using a different STAMP_ID.</para>\r
- <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 \r
- client-side customizations.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then set the variable and build \r
- the Staff Client:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp build</userinput>\r
-</screen>\r
- </simplesect>\r
- </simplesect>\r
- <simplesect>\r
- <title>Advanced Build Options</title>\r
- <indexterm><primary>staff client</primary><secondary>building</secondary><tertiary>advanced build options</tertiary></indexterm>\r
- <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 \r
- <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 \r
- <command>make</command> target keywords:</para>\r
- <table>\r
- <title>Keywords Targets for "make" Command</title>\r
- <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
- <colspec colnum="1" colwidth="1.0*"/>\r
- <colspec colnum="2" colwidth="3.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Keyword</entry>\r
- <entry>Description</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>clients</entry>\r
- <entry>Runs "make win-client", "make linux-client", and "make generic-client" individually</entry>\r
- </row>\r
- <row>\r
- <entry>client_dir</entry>\r
- <entry>Builds a client directory from the build directory, without doing a rebuild. The same as "copy everything but server/".</entry>\r
- </row>\r
- <row>\r
- <entry>client_app</entry>\r
- <entry>Prerequisite "client_dir"; removes "install.rdf" from client directory so an APP bundle can't be installed as an extension</entry>\r
- </row>\r
- <row>\r
- <entry>client_ext</entry>\r
- <entry>Prerequisite "client_dir"; remove "application.ini", "autoupdate.js", "standalone_xul_app.js" from client directory so an \r
- extension won't break Firefox</entry>\r
- </row>\r
- <row>\r
- <entry>extension</entry>\r
- <entry>Prerequisite "client_ext"; rewritten to use "client_ext"</entry>\r
- </row>\r
- <row>\r
- <entry>generic-client</entry>\r
- <entry>Prerequisite "client_app"; makes an XPI file suitable for use with "xulrunner --install-app""</entry>\r
- </row>\r
- <row>\r
- <entry>win-xulrunner</entry>\r
- <entry>Prerequisite "client_app"; adds Windows xulrunner to client build</entry>\r
- </row>\r
- <row>\r
- <entry>linux-xulrunner</entry>\r
- <entry>Prerequisite "client_app"; adds Linux xulrunner to client build</entry>\r
- </row>\r
- <row>\r
- <entry>win-client</entry>\r
- <entry>Prerequisite "win-xulrunner"; builds "setup exe" (requires that "nsis" package be installed, will add options for automatic update \r
- if configured and developer options if client build was a "make devbuild")</entry>\r
- </row>\r
- <row>\r
- <entry>linux-client</entry>\r
- <entry>Prerequisite "linux_xulrunner"; builds a "tar.bz2" bundle of the Linux client</entry>\r
- </row>\r
- <row>\r
- <entry>[generic-|win-|linux-|extension-]updates[-client]</entry>\r
- <entry>Calls external/make_updates.sh to build full and partial updates generic/win/linux/extension prefix limit to that \r
- distribution; Adding <option>-client</option> builds clients and copies them to a subdirectory of the \r
- <filename class="directory">updates</filename> directory as well; \r
- <option>extension-updates-client</option> doesn't exist.</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- <para>Descriptions of other special build options follow:</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para>Developer Build</para>\r
- <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>. \r
- The build will contain an extra configuration file that enables some developer options.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, run <command>make</command> from the Staff Client source directory:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>make devbuild</userinput>\r
-</screen>\r
- </listitem>\r
- <listitem>\r
- <para>Compressed Javascript</para>\r
- <para>You can execute the Google <systemitem class="resource">Closure Compiler</systemitem> utility to automatically review and compress \r
- Javascript code after the build process completes, \r
- by substituting <option>compress-javascript</option> for "build" when running <command>make</command>. For more information see \r
- <ulink url="http://code.google.com/closure/compiler/">Google Closure Compiler</ulink>.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, run the following commands from the Staff Client source directory:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>make compress-javascript</userinput>\r
-</screen>\r
- <para>You can also combine Javascript review and compression, and also perform a <emphasis>developer build</emphasis>.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, run the following commands from the Staff Client source directory:</para>\r
- <note><para>In the following <command>make</command> below, the order of options is important!</para></note>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>make devbuild compress-javascript</userinput>\r
-</screen>\r
- </listitem>\r
- <listitem>\r
- <para>Automatic Update Host</para>\r
- <para>The host used to check for automatic Staff Client updates can be overridden by specifying the <option>AUTOUPDATE_HOST</option> option. The \r
- following commands could have been used during the normal build process:</para>\r
-<screen>\r
-<userinput>su - root</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]</userinput>\r
-<userinput>make AUTOUPDATE_HOST=localhost install</userinput>\r
-</screen>\r
- <para>You can manually set <option>AUTOUPDATE_HOST</option> to set up automatic update checking. The following commands will manually build the Staff \r
- Client using a different <option>AUTOUPDATE_HOST</option>.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then set the variable and \r
- build the Staff Client:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>make AUTOUPDATE_HOST=localhost build</userinput>\r
-</screen>\r
- <para>For more information on Automatic Updates, see <xref linkend="staffclientinstallation-autoupdate"/>.</para>\r
- </listitem>\r
- </itemizedlist>\r
- </simplesect>\r
- <simplesect>\r
- <title>Installing and Activating a Manually Built Staff Client</title>\r
- <para>The Staff Client is automatically built, installed and activated as part of the normal <command>make <option>install</option></command> process for Evergreen \r
- 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 \r
- option of installing the Staff Client on the same machine it was built on, or on a different machine.</para>\r
- <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 \r
- the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the following commands:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>mkdir -p "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput>\r
-<userinput>cp -R build/server "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput>\r
-</screen>\r
- </simplesect>\r
- <simplesect>\r
- <title>Packaging the Staff Client</title>\r
- <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 \r
- Client source directory.</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para>Packaging a Generic Client</para>\r
- <para>This build creates a Staff Client packaged as an XPI file to use with <application>xulrunner</application>. It requires that you already have \r
- the <systemitem>zip</systemitem> utility installed on your system. It will create the output file <filename>evergreen_staff_client.xpi</filename>, \r
- suitable for use with the <application>xulrunner</application> parameter <option>--install-app</option>>.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the \r
- following commands:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>make generic-client</userinput>\r
-</screen>\r
- </listitem>\r
- <listitem>\r
- <para>Packaging a Windows Client</para>\r
- <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. \r
- It also requires that you install <ulink url="http://nsis.sourceforge.net/">NSIS (Nullsoft Scriptable Install System)</ulink>, a professional open \r
- source utility package used to create Windows installers (the "makensis" utility is installed as part of the "nsis" package). We recommend using \r
- Version 2.45 or later. This build will create the output file "evergreen_staff_client_setup.exe".</para>\r
- <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 \r
- <application>xulrunner-stub.exe</application>. Place it in the Staff Client source directory and <command>make</command> will automatically use it \r
- instead of the one that comes with the downloaded <application>XULRunner</application> release. The version of \r
- <application>xulrunner-stub.exe</application> need not match exactly.</para>\r
- <para>You can also use a tool such as <ulink url="http://www.angusj.com/resourcehacker/">Resource Hacker</ulink> to embed icons. Resource Hacker \r
- is an open-source utility used to view, modify, rename, add, delete and extract resources in 32bit Windows executables. See the following table for \r
- some useful icon ID strings:</para>\r
- <table>\r
- <title>Useful icon ID strings</title>\r
- <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
- <colspec colnum="1" colwidth="1.0*"/>\r
- <colspec colnum="2" colwidth="1.0*"/>\r
- <tbody>\r
- <row>\r
- <entry>IDI_APPICON</entry>\r
- <entry>Tray icon</entry>\r
- </row>\r
- <row>\r
- <entry>32512</entry>\r
- <entry>Default window icon</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the \r
- following commands:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>make win-client</userinput>\r
-</screen>\r
- </listitem>\r
- <listitem>\r
- <para>Packaging a Linux Client</para>\r
- <para>This build creates a Staff Client package for Linux as a "tar.bz2" file with <application>XULRunner</application> already bundled with it. It \r
- creates the output file "evergreen_staff_client.tar.bz2".</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the \r
- following commands:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>make linux-client</userinput>\r
-</screen>\r
- </listitem>\r
- <listitem>\r
- <para>Packaging a Firefox Extension</para>\r
- <para>This build requires that you already have the <systemitem>zip</systemitem> utility installed on your system. It creates a Staff Client packaged \r
- as a Firefox extension and creates the output file <filename>evergreen.xpi</filename>.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the \r
- following commands:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-<userinput>make extension</userinput>\r
-</screen>\r
- </listitem>\r
- </itemizedlist>\r
- </simplesect>\r
- <simplesect xml:id="staffclientinstallation-autoupdate">\r
- <title>Staff Client Automatic Updates</title>\r
- <indexterm><primary>staff client</primary><secondary>automatic updates</secondary></indexterm>\r
- <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 \r
- Staff Client with certain special options.</para>\r
- <caution>\r
- <para>Automatic update server certificate requirements are more strict than normal server requirements. Firefox and <application>XULRunner</application> will \r
- 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 \r
- accept them <emphasis>WILL NOT WORK</emphasis>.</para>\r
- <para>In addition, automatic updates have special requirements for the file <filename>update.rdf</filename>:</para>\r
- <orderedlist>\r
- <listitem>It must be served from an SSL server, or</listitem>\r
- <listitem>It must be signed with the <ulink url="https://developer.mozilla.org/en/McCoy">McCoy</ulink> tool.</listitem>\r
- </orderedlist>\r
- <para>You can pre-install the signing key into the file <filename>install.rdf</filename> directly, or install it into a copy as \r
- <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>\r
- </caution>\r
- <simplesect>\r
- <title>Autoupdate Host</title>\r
- <para>The name of the automatic update host can be provided in either of two ways:</para>\r
- <orderedlist>\r
- <listitem>At configuration time for the normal build of the Evergreen server-side software, or</listitem>\r
- <listitem>During a manual Staff Client build process.</listitem>\r
- </orderedlist>\r
- <para/>\r
- <itemizedlist>\r
- <listitem>\r
- <para>At configuration time for the normal build of Evergreen server-side software</para>\r
- <para>This must be done when the Evergreen server-side software is first configured (see <xref linkend="serversideinstallation-configure"/>). As \r
- the <systemitem class="username">opensrf</systemitem> user, use the utility "configure" as shown:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]</userinput>\r
-<userinput>./configure --prefix=/openils --sysconfdir=/openils/conf --with-updateshost=hostname</userinput>\r
-<userinput>make</userinput>\r
-</screen>\r
- </listitem>\r
- <listitem>\r
- <para>During a manual Staff Client build process</para>\r
- <para>You will used the variable AUTOUPDATE_HOST=hostname (see above). If you specify just a hostname (such as \r
- <systemitem class="domainname">example.com</systemitem>) then the URL will\r
- be a secure URL (such as <systemitem class="domainname">https://example.com</systemitem>. If you wish to use a non-HTTPS URL then prefix \r
- the hostname with <systemitem class="domainname">http://</systemitem> \r
- (such as <systemitem class="domainname">http://example.com</systemitem>).</para>\r
- <para>If neither option is used then, by default, the Staff Client will not include the automatic update preferences.</para>\r
- </listitem>\r
- </itemizedlist>\r
- </simplesect>\r
- <simplesect>\r
- <title>Building Updates</title>\r
- <indexterm><primary>staff client</primary><secondary>automatic updates</secondary><tertiary>building</tertiary></indexterm>\r
- <para>Similar to building clients, the targets <option>generic-updates</option>, <option>win-updates</option>, <option>linux-updates</option>, and \r
- <option>extension-updates</option> can be used individually \r
- 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>\r
- <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 \r
- full updates (archived by default in the directory <filename class="directory">/openils/var/updates/archives</filename>) will be used to make partial \r
- 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 \r
- used as a fallback. Extensions do not currentlysupport partial updates.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the following \r
- commands:</para>\r
- \r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-</screen>\r
-\r
- <para>Command to build all updates at once:</para>\r
-<screen>\r
-<userinput>make updates</userinput>\r
-</screen>\r
- <para>commands to build updates individually:</para>\r
-<screen>\r
-<userinput>make generic-updates</userinput>\r
-...\r
-<userinput>make win-updates</userinput>\r
-...\r
-<userinput>make linux-updates</userinput>\r
-...\r
-<userinput>make extension-updates</userinput>\r
-...\r
-</screen>\r
- </simplesect>\r
- <simplesect>\r
- <title>Building updates with clients</title>\r
- <indexterm><primary>staff client</primary><secondary>automatic updates</secondary><tertiary>building with clients</tertiary></indexterm>\r
- <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 \r
- 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. \r
- This does not work for <option>extension-updates</option>.</para>\r
- <para>The clients will be installed alongside the updates and listed on the <filename>manualupdate.html</filename> page, rather than left in the Staff \r
- Client directory.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the following \r
- commands:</para>\r
-<screen>\r
-<userinput>su - opensrf</userinput>\r
-<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
-</screen>\r
-\r
- <para>Command to build all updates at once:</para>\r
-<screen>\r
-<userinput>make updates-client</userinput>\r
-</screen>\r
-\r
- <para>Command to build updates individually:</para>\r
-<screen>\r
-<userinput>make generic-updates-client</userinput>\r
-...\r
-<userinput>make win-updates-client</userinput>\r
-...\r
-<userinput>make linux-updates-client</userinput>\r
-</screen>\r
-\r
- </simplesect>\r
- <simplesect>\r
- <title>Activating the Update Server</title>\r
- <indexterm><primary>staff client</primary><secondary>automatic updates</secondary><tertiary>activating the update server</tertiary></indexterm>\r
- <para>This section reviews scripts associated with the update server, and requires some final adjustments to file permissions.</para>\r
- <para>The Apache example configuration creates an "updates" directory that, by default, points to the directory \r
- <filename class="directory">/openils/var/updates/pub</filename>. This directory contains one HTML file and several specially-named script files.</para>\r
- <para>The <filename>updatedetails.html</filename> file is the fallback web page for the update details. The <filename>check</filename> script is used \r
- for <application>XULRunner</application> \r
- updates. The <filename>update.rdf</filename> script is used for extension updates. The <filename>manualupdate.html</filename> file checks for clients to \r
- 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 \r
- to install it as an extension).</para>\r
- <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>\r
-<screen>\r
-<userinput>su - root</userinput>\r
-<userinput>cd /openils/var/updates/pub</userinput>\r
-<userinput>chmod +x check download manualupdate.html update.rdf</userinput>\r
-</screen>\r
- </simplesect>\r
- </simplesect>\r
- <simplesect>\r
- <title>Other tips</title>\r
- <simplesect>\r
- <title>Multiple workstations on one install</title>\r
- <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>\r
- <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>\r
- <para>When building targets <option>win-client</option>, <option>win-updates-client</option>, or <option>updates-client</option>, you can \r
- specify <option>NSIS_EXTRAOPTS=-DPROFILES</option> to add an <guimenuitem>Evergreen Staff Client Profile Manager</guimenuitem> option to the start menu.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff Client source directory, then execute the following \r
- commands:</para>\r
- <screen>\r
- <userinput>su - opensrf</userinput>\r
- <userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
- <userinput>make NSIS_EXTRAOPTS=-DPROFILES win-client</userinput>\r
- </screen>\r
- </simplesect>\r
- <simplesect>\r
- <title> Multiple Staff Clients</title>\r
- <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 \r
- 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>\r
- <para>Once you have created the profiles, run <application>XULRunner</application> with the option <option>-no-remote</option> (in addition to \r
- <option>-profilemanger</option> or <option>-P</option> \r
- 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 \r
- then be logged in to a different server or workstation ID.</para>\r
- </simplesect>\r
- </simplesect>\r
- </simplesect>\r
- </section>\r
- <section xml:id="staffclientinstallation-running-staffclient">\r
- <title>Running the Staff Client</title>\r
- <indexterm><primary>staff client</primary><secondary>running</secondary><tertiary>linux</tertiary></indexterm>\r
- <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 \r
- on Ubuntu and Debian distributions).</para>\r
- <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 \r
- the Staff Client as shown in the following example:</para>\r
- <screen>\r
- <userinput>su - opensrf</userinput>\r
- <userinput>xulrunner /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client/build/application.ini</userinput>\r
- </screen>\r
- <simplesect xml:id="staffclientinstallation-proxy">\r
- <title>Running the Staff Client over an SSH Tunnel</title>\r
- <indexterm><primary>staff client</primary><secondary>running through an SSH tunnel</secondary></indexterm>\r
- <para>The Staff Client can use an SSH tunnel as a SOCKS 5 proxy.</para>\r
- <simplesect>\r
- <title>Configuring a Proxy for the Staff Client</title>\r
- <para>There are several reasons for sending network traffic for the Staff Client through an SSH proxy:</para>\r
- <itemizedlist>\r
- <listitem>\r
- <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 \r
- be available generally, or it may be the result of network design priorities other than ease of use.</para>\r
- </listitem>\r
- <listitem>\r
- <para>You may wish to improve security where Staff Client traffic may be susceptible to network eavesdropping. This is especially true when wireless \r
- is otherwise the best option for connecting a staff machine to the network.</para>\r
- </listitem>\r
- </itemizedlist>\r
- </simplesect>\r
- <simplesect>\r
- <title>Setting Up an SSH Tunnel</title>\r
- <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 \r
- for that <systemitem class="protocal">SSH</systemitem> server to set up a tunnel.</para>\r
- <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 \r
- <systemitem class="protocal">telnet/SSH</systemitem> client]]. When setting up a PuTTY session:</para>\r
- <mediaobject>\r
- <imageobject>\r
- <imagedata fileref="../media/staffclientinstallation-proxy-putty.png" format="PNG" scalefit="1" width="70%"/>\r
- </imageobject>\r
- <textobject>\r
- <phrase>Setting up an SSH tunnel in PuTTY</phrase>\r
- </textobject>\r
- </mediaobject>\r
- <orderedlist>\r
- <listitem>Use the menu on the left to go to Connection > SSH > Tunnels.</listitem>\r
- <listitem>Enter ''9999'' in the "Source port".</listitem>\r
- <listitem>Choose "Dynamic". Do not enter anything in the Destination text entry box.</listitem>\r
- <listitem>Click <guibutton>Add</guibutton>; "D9999" will now appear in the "Forwarded ports" list.</listitem>\r
- <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>\r
- <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>\r
- </orderedlist>\r
- <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> \r
- for information on setting up <systemitem class="protocal">SSH</systemitem> for other client operating systems,</para>\r
- </simplesect>\r
- <simplesect>\r
- <title>Configuring the Staff Client to Use the <systemitem class="protocal">SSH</systemitem> Tunnel</title>\r
- <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 \r
- 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 \r
- appropriate section for the following changes.</para>\r
- <mediaobject>\r
- <imageobject>\r
- <imagedata fileref="../media/staffclientinstallation-proxy-socks-1.png" format="PNG" scalefit="1" width="70%"/>\r
- </imageobject>\r
- <textobject>\r
- <phrase>The SOCKS section of "all.js" before changes</phrase>\r
- </textobject>\r
- </mediaobject>\r
- <para>Make the following changes:</para>\r
- <itemizedlist>\r
- <listitem>Change the value of <literal>network.proxy.socks</literal> from <literal>""</literal> to <literal>localhost</literal>.</listitem>\r
- <listitem>Change the value of <literal>network.proxy.socks_port</literal> from <literal>0</literal> to <literal>9999</literal>.</listitem>\r
- </itemizedlist>\r
- <mediaobject>\r
- <imageobject>\r
- <imagedata fileref="../media/staffclientinstallation-proxy-socks-2.png" format="PNG" scalefit="1" width="70%"/>\r
- </imageobject>\r
- <textobject>\r
- <phrase>The SOCKS section of "all.js" after changes</phrase>\r
- </textobject>\r
- </mediaobject>\r
- <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 \r
- <systemitem class="protocal">SSH</systemitem> tunnel you have just configured.</para>\r
- </simplesect>\r
- </simplesect>\r
- </section>\r
-</chapter>\r
+<?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>
projects / working / Evergreen.git / commitdiff
