From: Kyujung Lim <kyujung.lim@gmail.com> Date: Mon, 22 Aug 2011 20:58:28 +0000 (-0400) Subject: Added staffclientinstallation.xml with old 1.6 content for now X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=edc2f2fb36498b275e49114145a1030c8cf2a658;p=evergreen%2Fmasslnc.git Added staffclientinstallation.xml with old 1.6 content for now --- diff --git a/2.0/admin/staffclientinstallation.xml b/2.0/admin/staffclientinstallation.xml new file mode 100644 index 0000000000..fc3ad5b12f --- /dev/null +++ b/2.0/admin/staffclientinstallation.xml @@ -0,0 +1,1537 @@ +<?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 <systemitem class="osname">Windows</systemitem>, + <systemitem class="osname">Mac</systemitem> 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 <systemitem class="osname">Windows</systemitem></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 <systemitem class="osname">Microsoft Windows</systemitem> 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="60%"/> + </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="60%"/> + </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> + <note><para>Users must have the <literal>REGISTER_WORKSTATION</literal> permission and be assigned the appropriate working location(s) in order to + register a workstation.</para></note> + <para>To add working locations to a userâs account:</para> + <orderedlist> + <listitem> + <para>Retrieve the user through a patron search and select <menuchoice><guimenu>Other</guimenu><guimenuitem>User Permission + Editor</guimenuitem></menuchoice> and select the boxes for the locations necessary.</para> + <para>Save the user record.</para> + <note> + <para>Making modifications to <guilabel>Working Locations</guilabel> while changing permission settings does not work â when this + workflow is performed, permission changes will not be applied to the database.</para> + </note> + </listitem> + <listitem> + <para>Alternately, from the <guimenu>Admin</guimenu> menu, select <guimenuitem>User Permission Editor</guimenuitem> and retrieve the user by + barcode.</para> + <para>Make changes to working locations as described above.</para> + </listitem> + </orderedlist> + </section> + <section xml:id="staffclientinstallation-installing-macos"> + <title>Installing on <systemitem class="osname">Mac OS</systemitem></title> + <indexterm> + <primary>staff client</primary> + <secondary>installing</secondary> + <tertiary>Mac OS</tertiary> + </indexterm> + <para>This section describes <systemitem class="osname">Mac OS</systemitem> + packages and related versions of <application>XULrunner</application> that can + be used to run the Staff Client in a <systemitem class="osname">Mac OS</systemitem> + environment.</para> + <simplesect> + <title>Evergreen Version 1.2.3.0</title> + <orderedlist> + <listitem> + <para>A <systemitem class="osname">Mac OS</systemitem> package that + contains an early version of the Staff Client (version 1.2.3.0) for use + with <application>XULrunner</application> is available. You can find + current releases of <application>XULrunner</application> 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. You can find further information + about <application>XULrunner</application> here: + <ulink url="https://developer.mozilla.org/en/xulrunner"> + https://developer.mozilla.org/en/xulrunner</ulink>.</para> + <para>Note that later versions of <application>XULrunner</application> + (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 <systemitem class="osname">Mac OS</systemitem> + 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 <systemitem class="osname">Windows</systemitem> installation of + the desired version of the Staff Client to your + <systemitem class="osname">Mac</systemitem>. + The required files may be located in a directory like this on the + <systemitem class="osname">Windows</systemitem> machine: + <filename class="directory">C:\Program Files\Evergreen Staff Client\build</filename>. + Copy these files 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 + <systemitem class="osname">Mac OS</systemitem></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 <application>XULrunner</application></title> + <indexterm> + <primary>staff client</primary> + <secondary>XULRunner</secondary> + </indexterm> + <para>You must install an appropriate version of <application>XULrunner</application> + to match the Evergreen version. See the following table for the recommended version of + <application>XULrunner</application>:</para> + <table xml:id="staffclientinstallation-table-1"> + <?dbfo keep-together="always" ?> + <title>Evergreen / <application>XULrunner</application> Dependencies</title> + <tgroup align="left" cols="2" colsep="1" rowsep="1"> + <colspec colname="evergreen_version" colnum="1" colwidth="1.0*"/> + <colspec colname="xulrunner_version" colnum="2" colwidth="1.0*"/> + <thead> + <row> + <entry>Evergreen Version</entry> + <entry>XULRunner Version</entry> + </row> + </thead> + <tbody> + <row> + <entry>Evergreen 1.6.x.x</entry> + <entry>XULrunner 1.9.x.x</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 + <application>XULrunner</application> 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>).</para> + <para>Remember to call <application>XULrunner</application> with the full path to the + binary, followed by the install command and the path to the client data:</para> +<screen> + <userinput> + /Library/Frameworks/XUL.framework/xulrunner-bin --install-app ~/Desktop/Evergreen_Staff_Client</userinput> +</screen> + <para>The command should exit quietly and will create the folder + <filename class="directory">/Applications/OpenILS</filename>, + containing a launcher named <application>open_ils_staff_client</application>.</para> + </simplesect> + <simplesect xml:id="staffclientinstallation-remove-xulrunner"> + <title>(OPTIONAL) Removing previously installed XULRunner versions</title> + <indexterm> + <primary>XULRunner</primary> + <secondary>removing previous versions</secondary> + </indexterm> + <para>If you already have a newer version of + <application>XULrunner</application> 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 <systemitem class="osname">Mac OS</systemitem> + releases), you need to flush the file <filename>receiptdb</filename>.</para> + <note>If you install a newer version of <application>XULrunner</application> + over a previous (older) install, the older install is not removed but the + symlinks are changed to the newer one.</note> + </simplesect> + <simplesect> + <title>(OPTIONAL) Flush Receiptdb file:</title> + <para>First, get the package identifier, then purge/forget the build that was + initially installed:</para> +<screen> + <userinput> + sudo pkgutil --pkgs > /tmp/pkgs.txt + 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 and <application>XULrunner</application> Bundled</title> + <para>An APP file is basically a folder. Start with a folder stucture like this:</para> +<screen> + <prompt> + Evergreen.app + __Contents + ____Frameworks + ____Resources + ____MacOS</prompt> +</screen> + <para>Create an APP folder structure with the following commands:</para> +<screen> + <userinput> + mkdir -p Evergreen.app/Contents/Frameworks + mkdir -p Evergreen.app/Contents/Resources + mkdir -p Evergreen.app/Contents/MacOS</userinput> +</screen> + <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_1_6</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_1_6</string> + <key>CFBundleVersion</key> + <string>rel_1_6_1_6.rel_1_6_1_6</string> + <key>NSAppleScriptEnabled</key> + <true/> + <key>CFBundleTypeIconFile</key> + <string>Evergreen.icns</string> +</dict> +</plist> +]]></programlisting> + </listitem> + <listitem>Download and install an appropriate + <systemitem class="osname">Mac OS</systemitem> package of + <application>XULrunner</application> from the Mozilla website + <ulink url="https://developer.mozilla.org/en/xulrunner"> + https://developer.mozilla.org/en/xulrunner</ulink> (see + <xref linkend="staffclientinstallation-table-1"/> 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/ + __Contents/ + ____Frameworks/ + ______XUL.Framework/ + ______Versions/ + ________Current -> 1.9.1.3 (symlink) + ________1.9.1.3/ + ______XUL -> Versions/Current/XUL + ______libxpcom.dylib -> Versions/Current/libxpcom.dylib + ______xulrunner-bin -> Versions/Current/xulrunner-bin</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/ + __Contents/ + ____Resources/ + ______BUILD_ID + ______application.ini + ______chrome/ + ______components/ + ______etc.</prompt> +</screen> + </listitem> + <listitem>Put a <systemitem class="osname">Mac</systemitem> + 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 your + server to the remote workstation.</para> + <para>Execute the following commands, replacing <literal>USER</literal>, + <literal>WORKSTATION</literal>, and <literal>SOME_PATH</literal> with + appropriate values:</para> +<screen> + <userinput> + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + scp -r ./build USER@WORKSTATION:/SOME_PATH/</userinput> +</screen> + <para>You should test the newly copied Staff Client on the remote workstation. + Log into the workstation and execute the following command:</para> +<screen> + <userinput> + xulrunner /SOME_PATH/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 your + server to the new Linux system. You could manually build the Staff Client on the + new system, but you must ensure that the <envar>BUILD_ID</envar> you chose on + the server matches the <envar>BUILD_ID</envar> for each Staff Client you use on + other systems.</para> + <para>If you wish to use a pre-packaged <systemitem class="osname">Windows</systemitem> + version on some systems, you may want to choose the <envar>BUILD_ID</envar> on + both server and other versions to match that of the + <systemitem class="osname">Windows</systemitem> Staff Client. To determine which + <envar>BUILD_ID</envar> was used for existing Staff Client installations, + execute each Staff Client and click the <guibutton>'About this Client'</guibutton> + button.</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 <envar>BUILD_ID</envar> 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. As the + <systemitem class="username">root</systemitem> user, make the changes as follows:</para> +<screen> + <userinput> + # as the root user: + cd /openils/var/web/xul + 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 + <systemitem class="osname">Windows</systemitem> 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 instructions are + for building Staff Client version 1.2.1.4 on + <systemitem class="osname">Kubuntu 7.10</systemitem>; modify them as needed for + other distributions (the instructions should work as-is for + <systemitem class="osname">Ubuntu</systemitem> or + <systemitem class="osname">Ubuntu</systemitem> 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> + <userinput> + # as the root user: + sudo apt-get install subversion + 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 administrator, IT person, or HelpDesk to + determine which Staff Client versions are + supported.</para> + <para>Next, you need to determine which + <emphasis>tag</emphasis> to use when downloading the + source code. Tags are markers in the source code to create + a snapshot of the code as it existed at a certain time; + tags usually point to tested and stable code, or at least + a community-recognized release version.</para> + <para>To determine which tag to use, browse to + <ulink url="http://svn.open-ils.org/trac/ILS/browser"> + http://svn.open-ils.org/trac/ILS/browser</ulink>. + Look in the <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.6, 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_6'. This is the tag + you need; make a note of it for the next step.</para> + </listitem> + <listitem> + <para>Download the Code</para> + <para>As the + <systemitem class="username">opensrf</systemitem> + user, open a terminal (command-line prompt) and navigate + to the directory in which you wish to download the Staff + Client. Use the following commands to download the proper + version of the source code by tag name:</para> +<screen> + <userinput> + # as the opensrf user: + cd /DOWNLOAD/DIRECTORY + svn co rel_1_6_1_6/</userinput> +</screen> + <para>Remember to change "rel_1_6_1_6" 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 <envar>BUILD_ID</envar> + to use. The server checks the Staff Client + <envar>BUILD_ID</envar> against itself to determine whether or + not a connecting client is supported. For instance, for the + PINES installation (version 1.6.1.6) the supported + <envar>BUILD_ID</envar> is "rel_1_6_1_6". Modify the following + commands accordingly.</para> + <para>As the <systemitem class="username">opensrf</systemitem> + user, run the following commands to build the Staff Client:</para> +<screen> + <userinput> + # as the opensrf user: + wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.6.tar.gz + tar xfz Evergreen-ILS-1.6.1.6.tar.gz + cd /home/opensrf/Evergreen-ILS-1.6.1.6 + ./configure --prefix=/openils --sysconfdir=/openils/conf + cd ./Open-ILS/xul/staff_client/ + make STAFF_CLIENT_BUILD_ID='rel_1_6_1_6' install</userinput> +</screen> + </step> + <step> + <title>Run the Staff Client</title> + <para>As the <systemitem class="username">opensrf</systemitem> + user, navigate to the <filename class="directory">build/</filename> + subdirectory and run the following command:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client/build + xulrunner application.ini</userinput> +</screen> + </step> + <step> + <title>(OPTIONAL) Clean Up / Create 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 <literal>staging</literal> directory containing the + finished Staff Client that can then be copied to other + machines. To do this, execute the following commands (remember + to replace <emphasis>DOWNLOAD_DIRECTORY</emphasis> and + <emphasis>STAGING_DIRECTORY</emphasis> with the appropriate + paths):</para> +<screen> + <userinput> + # as the opensrf user: + mkdir ~/STAGING_DIRECTORY + cd ~/DOWNLOAD_DIRECTORY/Open-ILS/xul/ + cp -r staff_client ~/STAGING_DIRECTORY</userinput> +</screen> + <para>Test the Staff Client to verify that all necessary files + were copied to the staging directory:</para> +<screen> + <userinput> + # as the opensrf user: + cd ~/STAGING_DIRECTORY/staff_client/build + xulrunner application.ini</userinput> +</screen> + <para>If there were no problems, then finish the cleanup by + removing the original download directory as shown:</para> +<screen> + <userinput> + # as the opensrf user: + rm -r -f ~/DOWNLOAD_DIRECTORY</userinput> +</screen> + <para>Finally, the command:</para> +<screen> + <userinput> + # as the opensrf user: + xulrunner ~/STAGING_DIRECTORY/staff_client/build/application.ini</userinput> +</screen> + <para>will now run the Staff Client. You may wish to create a + shortcut for the Staff Client. To do so, use the previous + command as the target for the shortcut: + <menuchoice> + <guimenu>Desktop</guimenu> + <guimenuitem>StartMenu</guimenuitem> + <guimenuitem>K-Menu</guimenuitem> + </menuchoice></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 + <systemitem class="osname">Windows</systemitem> versions rather than manually + building the Staff Client. <application>Wine</application> is a Linux + application that allows users to directly run + <systemitem class="osname">Windows</systemitem> executables, and is a simple + way for casual Linux users to use the Staff Client. You can find more information + about <application>Wine</application> at + <ulink url="http://www.winehq.org/site/docs/wineusr-guide/getting-wine"> + http://www.winehq.org/site/docs/wineusr-guide/getting-wine</ulink>.</para> + <para>As the <systemitem class="username">root</systemitem> user, use + <command>apt-get</command> to install the package for <application>Wine</application>. + You can also use <command>synaptic</command>, the graphical user interface.</para> + <orderedlist> + <listitem> + <para>Install wine:</para> +<screen> + <userinput> + # as the root user: + sudo apt-get install wine</userinput> +</screen> + </listitem> + <listitem> + <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 + <systemitem class="osname">Microsoft Windows</systemitem> Installer + that contains the desired version of the Staff Client. Download + the installer and place it in a temporary directory.</para> + </listitem> + <listitem> + <para>As the <systemitem class="username">opensrf</systemitem> + user, navigate to the temporary directory where you downloaded + the <systemitem class="osname">Windows</systemitem> installer + file, then execute it with the <application>wine</application> + application (remember to replace <emphasis>VERSION</emphasis> with + the release number of the Staff Client you downloaded):</para> +<screen> + <userinput> + # as the opensrf user: + cd /TEMP_DIRECTORY + wine evergreen-setup-rel_VERSION.exe</userinput> +</screen> + <para>If this step fails, you may need to configure + <application>Wine</application> first to properly emulate + <systemitem class="osname">Windows XP</systemitem>. To do so, + type <command>winecfg</command> from the command line; in the + <literal>Applications</literal> tab of the window that pops up, + select <literal>Default Settings</literal> and choose + <literal>Windows XP</literal> 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 <literal>All Applications</literal> menu of + your Linux desktop. You may also find a new desktop shortcut for + the Staff Client. To launch the Staff Client, visit the + <literal>All Applications</literal> menu on your desktop and + find the section similar to:</para> + <para> + <menuchoice> + <guimenu>Wine</guimenu> + <guimenuitem>Program Files</guimenuitem> + <guimenuitem>Evergreen Staff Client</guimenuitem> + <guimenuitem>Evergreen Staff Client</guimenuitem> + </menuchoice>, + </para> + <para>or else launch the Staff Client from the new desktop shortcut.</para> + </listitem> + </orderedlist> + </simplesect> + </section> + </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.1.6/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 + variables that you can pass to <command>make</command> to influence the manual build + process:</para> + <simplesect> + <title> + Build Variable <envar>STAFF_CLIENT_BUILD_ID</envar></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 <envar>BUILD_ID</envar>.</para> + <para>You could use the following commands during the normal install process:</para> +<screen> + <userinput> + # as the root user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6 + make STAFF_CLIENT_BUILD_ID=1_6_1_6 install</userinput> +</screen> + <para>You can also manually build the Staff Client in the Staff Client + source directory with a different <envar>BUILD_ID</envar>.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, + execute the following commands to build the Staff Client (remember to replace + <emphasis>NEW_VERSION</emphasis> with an appropriate value):</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make STAFF_CLIENT_BUILD_ID=NEW_VERSION build</userinput> +</screen> + </simplesect> + <simplesect> + <title> + Build Variable <envar>STAFF_CLIENT_VERSION</envar></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 <envar>VERSION</envar> + similarly to the <envar>BUILD_ID</envar>.</para> + <para>You could use the following commands during the normal install process:</para> +<screen> + <userinput> + # as the root user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6 + make STAFF_CLIENT_VERSION=0mytest.200 install</userinput> +</screen> + <para>You can also manually build the Staff Client in the Staff Client + source directory with a different <envar>VERSION</envar>.</para> + <para>If you plan to make extensions update automatically, the + <envar>VERSION</envar> 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, + execute the following commands to build the Staff Client:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make STAFF_CLIENT_VERSION=0mytest.200 build</userinput> +</screen> + </simplesect> + <simplesect> + <title> + Build Variable <envar>STAFF_CLIENT_STAMP_ID</envar></title> + <para>During the normal <emphasis>make install</emphasis> Evergreen + server-side software build process, the variable is generated from + <envar>STAFF_CLIENT_VERSION</envar>. You may want to have multiple versions + of the Staff Client with different stamps, possibly for different uses or + client-side customizations. You can override the value of + <envar>STAMP_ID</envar> similarly to the <envar>BUILD_ID</envar>.</para> + <para>You could use the following commands during the normal install process:</para> +<screen> + <userinput> + # as the root user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6 + make STAFF_CLIENT_STAMP_ID=my_test_stamp install</userinput> +</screen> + <para>You can also manually build the Staff Client in the Staff Client + source directory with a different <envar>STAMP_ID</envar>.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, + execute the following commands to build the Staff Client:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + 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 the + <literal>staff_client</literal> directory. See the following table for a list of + possible <command>make</command> target keywords:</para> + <table> + <title>Keywords For Advanced Build Options</title> + <?dbfo keep-together="always" ?> + <tgroup align="left" cols="2" colsep="1" rowsep="1"> + <colspec colname="keyword" colnum="1" colwidth="1.0*"/> + <colspec colname="description" 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>Following are descriptions of other special build options:</para> + <simplesect> + <title>Developer Build</title> + <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> from the + <literal>staff_client</literal> directory. The build will contain an + extra configuration file that enables some developer options.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, run + the following commands from the Staff Client source directory:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make devbuild</userinput> +</screen> + </simplesect> + <simplesect> + <title>Compressed Javascript</title> + <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 + <option>build</option> when running <command>make</command>. + For more information on the Google Closure Compiler, see + <ulink url="http://code.google.com/closure/compiler/"> + http://code.google.com/closure/compiler</ulink>.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, run + the following commands from the Staff Client source directory:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + 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 <command>make</command> command from the Staff Client source directory + (the order of options is important):</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make devbuild compress-javascript</userinput> +</screen> + </simplesect> + <simplesect xml:id="staffclientinstallation-autoupdatehost"> + <title>Automatic Update Host</title> + <para>You can override the host used to check for automatic Staff Client updates + by specifying the <option>AUTOUPDATE_HOST</option> option.</para> + <para>You could use the following commands during the normal install process:</para> +<screen> + <userinput> + # as the root user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6 + make AUTOUPDATE_HOST=localhost install</userinput> +</screen> + <para>You can manually build the Staff Client in the Staff Client + source directory and set <option>AUTOUPDATE_HOST</option> to enable automatic + update checking.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, + execute the following commands to build the Staff Client:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make AUTOUPDATE_HOST=localhost build</userinput> +</screen> + <para>For more information on Automatic Updates, see + <xref linkend="staffclientinstallation-autoupdate"/>.</para> + </simplesect> + </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 from the + <literal>staff_client</literal> directory, 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 execute the following + commands:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + mkdir -p "/openils/var/web/xul/$(cat build/BUILD_ID)" + cp -R build/server "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput> +</screen> + </section> + <section> + <title>Packaging the Staff Client</title> + <para>Once you have built the Staff Client, you can create several forms of special client + packages by using a modified <command>make</command> command in the <literal>staff_client</literal> + directory.</para> + <simplesect> + <title>Packaging a Generic Client</title> + <para>This build creates a Staff Client packaged as an XPI file suitable for use with + the <option>--install-app</option> parameter of <application>XULrunner</application>. + It requires that you already have the <systemitem>zip</systemitem> utility + installed on your system.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, execute + the following commands:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make generic-client</userinput> +</screen> + <para>The output file <filename>evergreen_staff_client.xpi</filename> will be created.</para> + </simplesect> + <simplesect> + <title>Packaging a <systemitem class="osname">Windows</systemitem> Client</title> + <para>This build creates a Staff Client packaged as a + <systemitem class="osname">Windows</systemitem> executable. It requires that + you already have the <application>unzip</application> 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 + <systemitem class="osname">Windows</systemitem> installers (the + <application>"makensis"</application> utility is installed as part of the + <application>"nsis"</application> package). You should use Version 2.45 or + later.</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. <application>Resource Hacker</application> is an open-source + utility used to modify resources within 32-bit + <systemitem class="osname">Windows</systemitem> executables. + Some useful icon ID strings include the following:</para> + <table> + <?dbfo keep-together="always" ?> + <title>Icon IDs for Packaging a Windows Client</title> + <tgroup align="left" cols="2" colsep="1" rowsep="1"> + <colspec colname="keyword" colnum="1" colwidth="1.0*"/> + <colspec colname="icon" 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 + execute the following commands:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make win-client</userinput> +</screen> + <para>The output file <filename>evergreen_staff_client_setup.exe</filename> will be created.</para> + </simplesect> + <simplesect> + <title>Packaging a Linux Client</title> + <para>This build creates a Staff Client packaged as a compressed + <literal>tar</literal> archive file with <application>XULrunner</application> + already bundled with it. It requires that you already have the + <application>bzip2</application> utility installed on your system.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, + execute the following commands:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make linux-client</userinput> +</screen> + <para>The output file <filename>evergreen_staff_client.tar.bz2</filename> will be created.</para> + </simplesect> + <simplesect> + <title>Packaging a <application>Firefox</application> Extension</title> + <para>This build creates a Staff Client packaged as a <application>Firefox</application> + extension. It requires that you already have the <systemitem>zip</systemitem> + utility installed on your system.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, + execute the following commands:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make extension</userinput> +</screen> + <para>The output file <filename>evergreen.xpi</filename> will be created.</para> + </simplesect> + </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> + <warning> + <para>Automatic update server certificate requirements are more strict than + normal server requirements. <application>Firefox</application> 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"> + https://developer.mozilla.org/en/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> + </warning> + <simplesect> + <title>Autoupdate Host</title> + <para>You can manually set the name of the automatic update host. If you do + not set the name then, by default, the Staff Client will not include an + automatic update preference. You can set the autoupdate host name as + follows:</para> + <itemizedlist> + <listitem> + <para>At configuration time during the normal <emphasis>make install</emphasis> + process for Evergreen server-side software.</para> + <para>You can do this when you first configure the Evergreen server-side + software (see <xref linkend="serversideinstallation-configure"/>). + As the <systemitem class="username">opensrf</systemitem> user, execute + the following commands:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6 + ./configure --prefix=/openils --sysconfdir=/openils/conf --with-updateshost=hostname + make</userinput> +</screen> + </listitem> + <listitem> + <para>During a manual Staff Client build process.</para> + <para>You can override the variable + <envar>AUTOUPDATE_HOST=hostname</envar> and manually build the + Staff Client from the <literal>staff_client</literal> + directory (see <xref linkend="staffclientinstallation-autoupdatehost"/> + for details). If you specify only a bare hostname (for example, + <systemitem class="domainname">example.com</systemitem>) then + the Staff Client will automatically use the secure URL + <systemitem class="domainname">https://example.com</systemitem>. + If you wish to use a non-https URL, then you must explicitly + specify the full URL (for example, + <systemitem class="domainname">http://example.com</systemitem>).</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, + execute the following commands to build the Staff Client (remember to + replace <emphasis>SOME_URL</emphasis> with an appropriate value):</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make AUTOUPDATE_HOST=http://SOME_URL build</userinput> +</screen> + </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, you can use the targets + <option>generic-updates</option>, <option>win-updates</option>, + <option>linux-updates</option>, and <option>extension-updates</option> + 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 currently support + partial updates.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, change + directory to the Staff Client source directory, then execute the following + commands:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client</userinput> +</screen> + <para>Command to build all updates at once:</para> +<screen> + <userinput> + # as the opensrf user: + make updates</userinput> +</screen> + <para>commands to build updates individually:</para> +<screen> + <userinput> + # as the opensrf user: + make generic-updates + make win-updates + make linux-updates + 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 the phrase <literal>"-client"</literal> to each + target name (for example, you could specify <option>updates-client</option> to build + all the targets at once, or you could specify <option>win-updates-client</option> + to build updates individually). This process will not work for the option + <option>extension-updates</option>.</para> + <para>The clients will be installed alongside the updates and listed on the + <filename>manualupdate.html</filename> page, instead of being left in the + <literal>staff_client</literal> directory.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, execute + one of the following commands:</para> + <para>To build all updates at once:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make updates-client</userinput> +</screen> + <para>To build updates individually:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make generic-updates-client + make win-updates-client + 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 <literal>updates</literal> + 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 + <application>Firefox</application> trying to install it as an + extension).</para> + <para>To change the permissions for the scripts + <filename>check</filename>, <filename>download</filename>, + <filename>manualupdate.html</filename>, and + <filename>update.rdf</filename>, as the root user execute the following + commands:</para> +<screen> + <userinput> + # as the root user: + cd /openils/var/updates/pub + chmod +x check download manualupdate.html update.rdf</userinput> +</screen> + </simplesect> + </section> + <section> + <title>Other tips</title> + <simplesect xml:id="staffclientinstallation-othertips"> + <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 + <literal>"-profilemanager"</literal> or <literal>"-P"</literal> (uppercase "P") + to force the Profile Manager to start. Unchecking the <literal>"Don't ask at startup"</literal> + 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 any of the 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 option + <guimenuitem>"Evergreen Staff Client Profile Manager"</guimenuitem> to the + start menu.</para> + <para>As the <systemitem class="username">opensrf</systemitem> user, + execute the following commands:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make NSIS_EXTRAOPTS=-DPROFILES win-client</userinput> +</screen> + </simplesect> + <simplesect> + <title> Multiple Staff Clients</title> + <para>It 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 the previous + tip in <xref linkend="staffclientinstallation-othertips"/>).</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 + needed). 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 xml:id="staffclientinstallation-running-staffclient"> + <title>Running the Staff Client</title> + <indexterm> + <primary>staff client</primary> + <secondary>running</secondary> + <tertiary>linux</tertiary> + </indexterm> + <para>You can run the Staff Client on a Linux system by using the + <application>XULrunner</application> application (installed automatically and by default + with <application>Firefox</application> <literal>Version 3.0</literal> and later on + <systemitem class="osname">Ubuntu</systemitem> and + <systemitem class="osname">Debian</systemitem> 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.6/</filename> you can start the + Staff Client as shown in the following example:</para> +<screen> + <userinput> + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client/build + xulrunner application.ini</userinput> +</screen> + <section 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, one that 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="60%"/> + </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="60%"/> + </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="60%"/> + </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> + </section> + <section xml:id="staffclientinstallation-proxy"> + <title>Running the Staff Client Over An <systemitem class="protocal">SSH</systemitem> Tunnel</title> + <indexterm> + <primary>staff client</primary> + <secondary>running through an SSH tunnel</secondary> + </indexterm> + <para>You can configure the Staff Client to communicate with the Evergreen server over + an <systemitem class="protocal">SSH</systemitem> tunnel using a SOCKS 5 proxy + server. There are several reasons for sending network traffic for the Staff Client + through an <systemitem class="protocal">SSH</systemitem> proxy:</para> + <itemizedlist> + <listitem> + <para>Firewalls may prevent you from reaching the Evergreen + 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 in situations where + Staff Client traffic may be susceptible to network + eavesdropping. This is especially true when staff machines + connect via wireless links to the network.</para> + </listitem> + </itemizedlist> + <section> + <title>Setting Up an <systemitem class="protocal">SSH</systemitem> Tunnel</title> + <para>You will need a server that allows you to log in via + <systemitem class="protocal">SSH</systemitem> 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 <systemitem class="osname">Windows</systemitem> 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. + Following are instructions for setting up an <application>SSH</application> + session using the <application>PuTTY</application> utility:</para> + <mediaobject> + <alt> + <phrase>Setting up an <systemitem class="protocal">SSH</systemitem> + tunnel in <application>PuTTY</application></phrase> + </alt> + <imageobject> + <imagedata fileref="../media/staffclientinstallation-proxy-putty-1.png" format="PNG" scalefit="1" width="60%"/> + </imageobject> + </mediaobject> + <procedure> + <step> + <para>Using the menu on the left, find the section:</para> + <para> + <menuchoice> + <guimenu>Connection</guimenu> + <guimenuitem>SSH</guimenuitem> + <guimenuitem>Tunnels</guimenuitem> + </menuchoice> + </para> + </step> + <step> + <para>In the section on the right labeled <literal>"Source + port"</literal>, enter <literal>9999</literal>.</para> + </step> + <step> + <para>Set the checkbox <literal>"Dynamic"</literal>. Do not + enter anything in the <literal>"Destination"</literal> text + entry box.</para> + </step> + <step> + <para>Click <guibutton>'Add'</guibutton> and notice that + <literal>"D9999"</literal> now appears in the section + labeled <literal>"Forwarded ports"</literal>.</para> + </step> + <step> + <para>Use the menu on the left, find the + <literal>"Session"</literal> section, then enter the host name + of the <systemitem class="protocal">SSH</systemitem> + server.</para> + </step> + <step> + <para>A pop-up window will open to allow you to enter your + username and password. Once you are logged in, the tunnel is + open.</para> + </step> + </procedure> + <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> + </section> + <section> + <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 find edit the file <filename>all.js</filename>, usually located at + <filename>C:\Program Files\Evergreen Staff Client\greprefs\all.js</filename> + on a <systemitem class="osname">Windows</systemitem> system. + 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> + <para>Change the value of <literal>network.proxy.socks</literal> + from <literal>""</literal> to <literal>localhost</literal>.</para> + </listitem> + <listitem> + <para>Change the value of <literal>network.proxy.socks_port</literal> + from <literal>0</literal> to <literal>9999</literal>.</para> + </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> + </section> + </section> + <section> + <title>Navigating a Tabbed Interface</title> + <para>Like many popular current web browsers and other applications, the Staff Client + uses a "tabbed" interface. Tabs allow you to have several pages open at the same time + in a single window. This is easier to manage on your computer screen than multiple + windows, since you can easily switch between tabs in the same window.</para> + <mediaobject> + <alt> + <phrase>Tabs in the Staff Client window</phrase> + </alt> + <imageobject> + <imagedata fileref="../media/staffclientinstallation-tabbed-1.png" format="PNG" scalefit="1" width="70%"/> + </imageobject> + </mediaobject> + <para>The "tabs" appear below the menu bar in the Staff Client with a descriptive + title. Simply select a tab to bring it to the front and view the page displayed in the + tab. You can use tabs to have access to multiple things all at the same time: patron + records and searches, bibliographic records and searches, circulation or cataloging + interfaces - anything at all in the Staff Client.</para> + <itemizedlist> + <listitem>Create a new tab by pressing + <keycombo> + <keycap>Ctrl</keycap> + <keycap>T</keycap> + </keycombo> + on the keyboard or selecting: + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>New Tab</guimenuitem> + </menuchoice> + from the menu.</listitem> + <listitem>Close a tab by pressing + <keycombo> + <keycap>Ctrl</keycap> + <keycap>W</keycap> + </keycombo> on the keyboard or selecting + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>Close Tab</guimenuitem> + </menuchoice> + from the menu.</listitem> + <listitem>Switch tabs by pressing + <keycombo> + <keycap>Ctrl</keycap> + <keycap>Tab</keycap> + </keycombo> + on the keyboard or selecting the tab in the tab bar.</listitem> + </itemizedlist> + </section> + </section> +</chapter>