1 <?xml version="1.0" encoding="UTF-8"?>
2 <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">
4 <title>Installation of Evergreen Staff Client Software</title>
6 <para>This section describes installation of the Evergreen Staff Client software.</para>
9 <section xml:id="staffclientinstallation-installing-staffclient">
10 <title>Installing the Staff Client</title>
12 <primary>staff client</primary>
13 <secondary>installing</secondary>
15 <section xml:id="staffclientinstallation-installing-prebuilt">
16 <title>Installing a Pre-Built Staff Client</title>
17 <para>A pre-built Staff Client is available for <systemitem class="osname">Windows</systemitem>,
18 <systemitem class="osname">Mac</systemitem> or Linux systems. Installing the Staff Client in
19 each of these environments is described in the following sections.</para>
20 <section xml:id="staffclientinstallation-installing-windows">
21 <title>Installing on <systemitem class="osname">Windows</systemitem></title>
23 <primary>staff client</primary>
24 <secondary>installing</secondary>
25 <tertiary>Windows</tertiary>
27 <para>In this section we describe the process of installing the Staff Client on the
28 <systemitem class="osname">Microsoft Windows</systemitem> operating system.</para>
29 <para>Visit the downloads section of the Evergreen website at
30 <ulink url="http://www.evergreen-ils.org/downloads.php">http://www.evergreen-ils.org/downloads.php</ulink>
31 and find the standard <systemitem class="osname">Microsoft Windows</systemitem> Installer
32 that contains the current version of the Staff Client. Download the Installer, then run
33 it. A screen that looks similar to this should appear:</para>
36 <phrase>Running the Staff Client installer</phrase>
39 <imagedata fileref="../media/staffclientinstallation-staffclient-1.png" format="PNG" scalefit="1" width="60%"/>
42 <para>Click <guibutton>'Next'</guibutton> to continue through the guided install
43 process. The Install Wizard will ask you to agree to the end-user license, ask you where
44 to install the software, ask about where to place icons, and then will automatically
45 install the software on your workstation.</para>
46 <para>When you run the Staff Client for the first time, a screen similar to this should
50 <phrase>Running the Staff Client for the first time</phrase>
53 <imagedata fileref="../media/staffclientinstallation-staffclient-2.png" format="PNG" scalefit="1" width="60%"/>
56 <para>First, add the name of your Evergreen server to the field
57 <emphasis role="bold">Hostname</emphasis> in the <emphasis role="bold">Server</emphasis>
58 section. For example, the PINES demo system is
59 <ulink url="http://demo.gapines.org">http://demo.gapines.org</ulink>.
60 After adding the server name, click <guibutton>'Re-Test Server'</guibutton>.</para>
61 <para>Because this is the initial run of the Staff Client, you will see a warning in the
62 upper-right saying: <emphasis role="bold">Not yet configured for the specified
63 server</emphasis>. The first thing you must do to the Staff Client on every workstation
64 is to assign it a workstation name. This is covered in
65 <xref linkend="staffclientinstallation-workstationnames"/>.</para>
67 <section xml:id="staffclientinstallation-installing-macos">
68 <title>Installing on <systemitem class="osname">Mac OS</systemitem></title>
70 <primary>staff client</primary>
71 <secondary>installing</secondary>
72 <tertiary>Mac OS</tertiary>
74 <para>This section describes <systemitem class="osname">Mac OS</systemitem>
75 packages and related versions of <application>XULrunner</application> that can
76 be used to run the Staff Client in a <systemitem class="osname">Mac OS</systemitem>
79 <title>Evergreen Version 1.2.3.0</title>
82 <para>A <systemitem class="osname">Mac OS</systemitem> package that
83 contains an early version of the Staff Client (version 1.2.3.0) for use
84 with <application>XULrunner</application> is available. You can find
85 current releases of <application>XULrunner</application> here:
86 <ulink url="http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases">
87 http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases</ulink> .
88 Download and install the latest version. You can find further information
89 about <application>XULrunner</application> here:
90 <ulink url="https://developer.mozilla.org/en/xulrunner">
91 https://developer.mozilla.org/en/xulrunner</ulink>.</para>
92 <para>Note that later versions of <application>XULrunner</application>
93 (e.g., version 1.9.2.13) have replaced version 1.8.0.4, which has known
94 security holes and is not recommended for applications that deal with
95 public web content.</para>
98 <para>A <systemitem class="osname">Mac OS</systemitem>
99 Installation package for Staff Client version 1.2.3.0 is
100 available from Evergreen Indiana. Download and install it from
102 <ulink url="http://evergreen.lib.in.us/opac/extras/files/evergreen_osx_staff_client_1_2_3.zip">
103 evergreen_osx_staff_client_1_2_3.zip</ulink> .
107 <para>To upgrade to a more recent version of the Staff Client, you can
108 copy the <filename class="directory">build</filename> directory from a
109 working <systemitem class="osname">Windows</systemitem> installation of
110 the desired version of the Staff Client to your
111 <systemitem class="osname">Mac</systemitem>.
112 The required files may be located in a directory like this on the
113 <systemitem class="osname">Windows</systemitem> machine:
114 <filename class="directory">C:\Program Files\Evergreen Staff Client\build</filename>.
115 Copy these files to the <filename class="directory">Resources</filename>
116 folder within the <package>Open-ILS</package> package in your
117 <filename class="directory">Applications</filename> directory on the Mac,
118 overwriting files with the same names.</para>
120 <listitem>Drag the application's icon to your toolbar for easier
123 <para>When you run the Staff Client installer, a screen will appear that looks
124 similar to this:</para>
127 <phrase>Running the Staff Client installer for
128 <systemitem class="osname">Mac OS</systemitem></phrase>
131 <imagedata fileref="../media/staffclientinstallation-staffclient-3.png" format="PNG" scalefit="1" width="20%"/>
134 <para>Click <guibutton>'Continue'</guibutton>, accept the license, then finish the
135 installation. The application will be located at the destination you selected
136 during installation. You will then be able to drag the application into your
137 toolbar for easier access.</para>
140 <phrase>Finishing the installation</phrase>
143 <imagedata fileref="../media/staffclientinstallation-staffclient-4.png" format="PNG" scalefit="1" width="20%"/>
148 <title>Running directly using <application>XULrunner</application></title>
150 <primary>staff client</primary>
151 <secondary>XULRunner</secondary>
153 <para>You must install an appropriate version of <application>XULrunner</application>
154 to match the Evergreen version. See the following table for the recommended version of
155 <application>XULrunner</application>:</para>
156 <table xml:id="staffclientinstallation-table-1">
157 <?dbfo keep-together="always" ?>
158 <title>Evergreen / <application>XULrunner</application> Dependencies</title>
159 <tgroup align="left" cols="2" colsep="1" rowsep="1">
160 <colspec colname="evergreen_version" colnum="1" colwidth="1.0*"/>
161 <colspec colname="xulrunner_version" colnum="2" colwidth="1.0*"/>
164 <entry>Evergreen Version</entry>
165 <entry>XULRunner Version</entry>
170 <entry>Evergreen 1.6.x.x</entry>
171 <entry>XULrunner 1.9.x.x</entry>
174 <entry>Evergreen 1.4.x.x</entry>
175 <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry>
178 <entry>Evergreen 1.2.x.x</entry>
179 <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry>
184 <note>If you have issues removing previously installed
185 <application>XULrunner</application> versions see
186 <xref linkend="staffclientinstallation-remove-xulrunner"/>
187 for further information.</note>
188 <para>The Staff Client data from the directory
189 <filename class="directory">./staff_client/build</filename> must be placed
190 somewhere on the machine (e.g.
191 <filename class="directory">~/Desktop/Evergreen_Staff_Client</filename>).</para>
192 <para>Remember to call <application>XULrunner</application> with the full path to the
193 binary, followed by the install command and the path to the client data:</para>
196 /Library/Frameworks/XUL.framework/xulrunner-bin --install-app ~/Desktop/Evergreen_Staff_Client</userinput>
198 <para>The command should exit quietly and will create the folder
199 <filename class="directory">/Applications/OpenILS</filename>,
200 containing a launcher named <application>open_ils_staff_client</application>.</para>
202 <simplesect xml:id="staffclientinstallation-remove-xulrunner">
203 <title>(OPTIONAL) Removing previously installed XULRunner versions</title>
205 <primary>XULRunner</primary>
206 <secondary>removing previous versions</secondary>
208 <para>If you already have a newer version of
209 <application>XULrunner</application> installed, per the release notes,
210 you will need to remove the entire directory
211 <filename class="directory">/Library/Frameworks/XUL.framework</filename>
212 before downgrading.</para>
213 <para>In addition, you may also need to remove the previous file
214 <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> .</para>
215 <para>If file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> does
216 not exist (possibly in newer <systemitem class="osname">Mac OS</systemitem>
217 releases), you need to flush the file <filename>receiptdb</filename>.</para>
218 <note>If you install a newer version of <application>XULrunner</application>
219 over a previous (older) install, the older install is not removed but the
220 symlinks are changed to the newer one.</note>
223 <title>(OPTIONAL) Flush Receiptdb file:</title>
224 <para>First, get the package identifier, then purge/forget the build that was
225 initially installed:</para>
228 sudo pkgutil --pkgs > /tmp/pkgs.txt
229 sudo pkgutil --forget org.mozilla.xulrunner</userinput>
231 <note>It may not be necessary to edit the file
232 <filename>/Library/Receipts/InstallHistory.plist</filename> after deleting the
233 folder <filename class="directory">XUL.framework</filename>. See
234 <ulink url="http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html">
235 http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html</ulink>
236 for more information.</note>
239 <title>Creating an APP file: Staff Client and <application>XULrunner</application> Bundled</title>
240 <para>An APP file is basically a folder. Start with a folder stucture like this:</para>
249 <para>Create an APP folder structure with the following commands:</para>
252 mkdir -p Evergreen.app/Contents/Frameworks
253 mkdir -p Evergreen.app/Contents/Resources
254 mkdir -p Evergreen.app/Contents/MacOS</userinput>
258 <para>Create a new file in the folder
259 <filename class="directory">Evergreen.app/Contents/Info.plist</filename>
260 containing the following data (adjust for your version of
262 <programlisting language="xml"><![CDATA[
263 <?xml version="1.0" encoding="UTF-8"?>
264 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
265 <plist version="1.0">
267 <key>CFBundleExecutable</key>
268 <string>xulrunner</string>
269 <key>CFBundleGetInfoString</key>
270 <string>OpenILS open_ils_staff_client rel_1_6_1_6</string>
271 <key>CFBundleInfoDictionaryVersion</key>
273 <key>CFBundleName</key>
274 <string>Evergreen Staff Client</string>
275 <key>CFBundlePackageType</key>
276 <string>APPL</string>
277 <key>CFBundleShortVersionString</key>
278 <string>rel_1_6_1_6</string>
279 <key>CFBundleVersion</key>
280 <string>rel_1_6_1_6.rel_1_6_1_6</string>
281 <key>NSAppleScriptEnabled</key>
283 <key>CFBundleTypeIconFile</key>
284 <string>Evergreen.icns</string>
289 <listitem>Download and install an appropriate
290 <systemitem class="osname">Mac OS</systemitem> package of
291 <application>XULrunner</application> from the Mozilla website
292 <ulink url="https://developer.mozilla.org/en/xulrunner">
293 https://developer.mozilla.org/en/xulrunner</ulink> (see
294 <xref linkend="staffclientinstallation-table-1"/> for recommendations).</listitem>
296 <para>Make a copy of the folder
297 <filename class="directory">/Library/Frameworks/XUL.Framework</filename>
298 inside your APP file. It should look something like this:</para>
306 ________Current -> 1.9.1.3 (symlink)
308 ______XUL -> Versions/Current/XUL
309 ______libxpcom.dylib -> Versions/Current/libxpcom.dylib
310 ______xulrunner-bin -> Versions/Current/xulrunner-bin</prompt>
314 <filename>XUL.Framework/Versions/Current/xulrunner</filename> into the
315 folder <filename class="directory">Evergreen.app/MacOS</filename>
316 (do not symlink; copy the file).</listitem>
318 <para>Make <filename>Evergreen.app/Resources</filename> the root
319 of your Evergreen application files like this:</para>
326 ______application.ini
332 <listitem>Put a <systemitem class="osname">Mac</systemitem>
333 format icon file named <filename>Evergreen.icns</filename> in
334 <filename class="resources">Resources</filename>.</listitem>
338 <section xml:id="staffclientinstallation-installing-linux">
339 <title>Installing on Linux</title>
341 <title>Quick Upgrade of the Staff Client</title>
342 <para>A Linux Staff Client is automatically built on the server as part of the
343 normal <emphasis>make install</emphasis> process for Evergreen server-side
344 software. To upgrade the Staff Client on a remote Linux workstation with a new
345 version, just copy the directory tree containing the Staff Client from your
346 server to the remote workstation.</para>
347 <para>Execute the following commands, replacing <literal>USER</literal>,
348 <literal>WORKSTATION</literal>, and <literal>SOME_PATH</literal> with
349 appropriate values:</para>
352 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
353 scp -r ./build USER@WORKSTATION:/SOME_PATH/</userinput>
355 <para>You should test the newly copied Staff Client on the remote workstation.
356 Log into the workstation and execute the following command:</para>
359 xulrunner /SOME_PATH/build/application.ini</userinput>
363 <title>Building the Staff Client on the Server</title>
365 <primary>staff client</primary>
366 <secondary>building on the server</secondary>
368 <para>A Linux Staff Client is automatically built on the server as part of the
369 normal <emphasis>make install</emphasis> process for Evergreen server-side
370 software. See <xref linkend="serversideinstallation-compile"/> for details of
371 the build process.</para>
372 <para>In order to install a compatible Staff Client on another Linux system, you
373 can copy the appropriate files from the Staff Client build directory on your
374 server to the new Linux system. You could manually build the Staff Client on the
375 new system, but you must ensure that the <envar>BUILD_ID</envar> you chose on
376 the server matches the <envar>BUILD_ID</envar> for each Staff Client you use on
377 other systems.</para>
378 <para>If you wish to use a pre-packaged <systemitem class="osname">Windows</systemitem>
379 version on some systems, you may want to choose the <envar>BUILD_ID</envar> on
380 both server and other versions to match that of the
381 <systemitem class="osname">Windows</systemitem> Staff Client. To determine which
382 <envar>BUILD_ID</envar> was used for existing Staff Client installations,
383 execute each Staff Client and click the <guibutton>'About this Client'</guibutton>
385 <para>If you are allowed to make changes on the Evergreen server, another option
386 is to create a symbolic link. In order for a copy of the Staff Client and server
387 to work together, the <envar>BUILD_ID</envar> must match the name of the
388 directory containing the server components of the Staff Client, or the name of a
389 symbolic link to that directory. As the
390 <systemitem class="username">root</systemitem> user, make the changes as follows:</para>
394 cd /openils/var/web/xul
395 ln -s SERVER_BUILD_ID/ CLIENT_BUILD_ID</userinput>
399 <title>Building the Staff Client on a Client Machine</title>
400 <para>This section is directed toward end-users who wish to use Linux rather than
401 <systemitem class="osname">Windows</systemitem> for client machines, but have limited
402 Linux experience. You can build the Staff Client on a Linux system without installing the
403 Evergreen Server component. This is a relatively simple process compared to server
404 installation, but does require some command-line work. The following instructions are
405 for building Staff Client version 1.2.1.4 on
406 <systemitem class="osname">Kubuntu 7.10</systemitem>; modify them as needed for
407 other distributions (the instructions should work as-is for
408 <systemitem class="osname">Ubuntu</systemitem> or
409 <systemitem class="osname">Ubuntu</systemitem> derivatives).</para>
412 <title>Prerequisites</title>
413 <para>Both <application>subversion</application> and
414 <application>XULrunner</application> are required to build the Staff
415 Client. As the <systemitem class="username">root</systemitem> user,
416 use <command>apt-get</command> to install packages for
417 <application>subversion</application> and
418 <application>XULrunner</application>. You can also use
419 <command>synaptic</command>, the graphical user interface for
420 <command>apt-get</command>. For <application>subversion</application>,
421 select the latest version; for <application>XULrunner</application>,
422 select version <emphasis>1.8.1.4-2ubuntu5</emphasis>.</para>
426 sudo apt-get install subversion
427 sudo apt-get install xulrunner</userinput>
431 <title>Download the Source Code</title>
434 <para>Determine which version is needed</para>
435 <para>For most end-users, a specific version is required
436 to communicate properly with the Evergreen server. Check
437 with your system administrator, IT person, or HelpDesk to
438 determine which Staff Client versions are
440 <para>Next, you need to determine which
441 <emphasis>tag</emphasis> to use when downloading the
442 source code. Tags are markers in the source code to create
443 a snapshot of the code as it existed at a certain time;
444 tags usually point to tested and stable code, or at least
445 a community-recognized release version.</para>
446 <para>To determine which tag to use, browse to
447 <ulink url="http://svn.open-ils.org/trac/ILS/browser">
448 http://svn.open-ils.org/trac/ILS/browser</ulink>.
449 Look in the <guilabel>Visit</guilabel> drop-down box; see
450 the list of <guilabel>Branches</guilabel> and, further
451 down, a list of <guilabel>Tags</guilabel>. You may have
452 to do some guesswork, but it is fairly straightforward to
453 determine which tag to use. If the server is version
454 1.6.1.6, you will want to use the tag that looks most
455 appropriate. For example, as you look through the tag
456 list, notice the tag named 'rel_1_6_1_6'. This is the tag
457 you need; make a note of it for the next step.</para>
460 <para>Download the Code</para>
462 <systemitem class="username">opensrf</systemitem>
463 user, open a terminal (command-line prompt) and navigate
464 to the directory in which you wish to download the Staff
465 Client. Use the following commands to download the proper
466 version of the source code by tag name:</para>
469 # as the opensrf user:
470 cd /DOWNLOAD/DIRECTORY
471 svn co rel_1_6_1_6/</userinput>
473 <para>Remember to change "rel_1_6_1_6" to the appropriate
474 tag for your installation.</para>
479 <title>Build the Staff Client</title>
480 <para>In the following example, navigate to the directory in
481 which the source code was downloaded, then navigate to the
482 proper subdirectory and run the "make" utility to actually build
483 the Staff Client. Remember to check with your system
484 administrator about which Staff Client <envar>BUILD_ID</envar>
485 to use. The server checks the Staff Client
486 <envar>BUILD_ID</envar> against itself to determine whether or
487 not a connecting client is supported. For instance, for the
488 PINES installation (version 1.6.1.6) the supported
489 <envar>BUILD_ID</envar> is "rel_1_6_1_6". Modify the following
490 commands accordingly.</para>
491 <para>As the <systemitem class="username">opensrf</systemitem>
492 user, run the following commands to build the Staff Client:</para>
495 # as the opensrf user:
496 wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.6.tar.gz
497 tar xfz Evergreen-ILS-1.6.1.6.tar.gz
498 cd /home/opensrf/Evergreen-ILS-1.6.1.6
499 ./configure --prefix=/openils --sysconfdir=/openils/conf
500 cd ./Open-ILS/xul/staff_client/
501 make STAFF_CLIENT_BUILD_ID='rel_1_6_1_6' install</userinput>
505 <title>Run the Staff Client</title>
506 <para>As the <systemitem class="username">opensrf</systemitem>
507 user, navigate to the <filename class="directory">build/</filename>
508 subdirectory and run the following command:</para>
511 # as the opensrf user:
512 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client/build
513 xulrunner application.ini</userinput>
517 <title>(OPTIONAL) Clean Up / Create Shortcuts</title>
518 <para>The source code download included many files that are
519 needed to build the Staff Client but are not necessary to run
520 it. You may wish to remove them to save space, or to create a
521 clean <literal>staging</literal> directory containing the
522 finished Staff Client that can then be copied to other
523 machines. To do this, execute the following commands (remember
524 to replace <emphasis>DOWNLOAD_DIRECTORY</emphasis> and
525 <emphasis>STAGING_DIRECTORY</emphasis> with the appropriate
529 # as the opensrf user:
530 mkdir ~/STAGING_DIRECTORY
531 cd ~/DOWNLOAD_DIRECTORY/Open-ILS/xul/
532 cp -r staff_client ~/STAGING_DIRECTORY</userinput>
534 <para>Test the Staff Client to verify that all necessary files
535 were copied to the staging directory:</para>
538 # as the opensrf user:
539 cd ~/STAGING_DIRECTORY/staff_client/build
540 xulrunner application.ini</userinput>
542 <para>If there were no problems, then finish the cleanup by
543 removing the original download directory as shown:</para>
546 # as the opensrf user:
547 rm -r -f ~/DOWNLOAD_DIRECTORY</userinput>
549 <para>Finally, the command:</para>
552 # as the opensrf user:
553 xulrunner ~/STAGING_DIRECTORY/staff_client/build/application.ini</userinput>
555 <para>will now run the Staff Client. You may wish to create a
556 shortcut for the Staff Client. To do so, use the previous
557 command as the target for the shortcut:
559 <guimenu>Desktop</guimenu>
560 <guimenuitem>StartMenu</guimenuitem>
561 <guimenuitem>K-Menu</guimenuitem>
567 <title>Using Wine to Install on Linux</title>
569 <primary>staff client</primary>
570 <secondary>using wine to install on Linux</secondary>
572 <para>The Linux application <application>Wine</application> is another
573 alternative if you wish to install the packaged
574 <systemitem class="osname">Windows</systemitem> versions rather than manually
575 building the Staff Client. <application>Wine</application> is a Linux
576 application that allows users to directly run
577 <systemitem class="osname">Windows</systemitem> executables, and is a simple
578 way for casual Linux users to use the Staff Client. You can find more information
579 about <application>Wine</application> at
580 <ulink url="http://www.winehq.org/site/docs/wineusr-guide/getting-wine">
581 http://www.winehq.org/site/docs/wineusr-guide/getting-wine</ulink>.</para>
582 <para>As the <systemitem class="username">root</systemitem> user, use
583 <command>apt-get</command> to install the package for <application>Wine</application>.
584 You can also use <command>synaptic</command>, the graphical user interface.</para>
587 <para>Install wine:</para>
591 sudo apt-get install wine</userinput>
595 <para>Visit the downloads section of the Evergreen website at
596 <ulink url="http://www.evergreen-ils.org/downloads.php">
597 http://www.evergreen-ils.org/downloads.php</ulink> and find the
598 <systemitem class="osname">Microsoft Windows</systemitem> Installer
599 that contains the desired version of the Staff Client. Download
600 the installer and place it in a temporary directory.</para>
603 <para>As the <systemitem class="username">opensrf</systemitem>
604 user, navigate to the temporary directory where you downloaded
605 the <systemitem class="osname">Windows</systemitem> installer
606 file, then execute it with the <application>wine</application>
607 application (remember to replace <emphasis>VERSION</emphasis> with
608 the release number of the Staff Client you downloaded):</para>
611 # as the opensrf user:
613 wine evergreen-setup-rel_VERSION.exe</userinput>
615 <para>If this step fails, you may need to configure
616 <application>Wine</application> first to properly emulate
617 <systemitem class="osname">Windows XP</systemitem>. To do so,
618 type <command>winecfg</command> from the command line; in the
619 <literal>Applications</literal> tab of the window that pops up,
620 select <literal>Default Settings</literal> and choose
621 <literal>Windows XP</literal> from the drop-down menu, then
622 click <guibutton>'Apply'</guibutton>.</para>
625 <para>Launch the Staff Client</para>
626 <para>A new entry for the Staff Client should now appear
627 somewhere in the <literal>All Applications</literal> menu of
628 your Linux desktop. You may also find a new desktop shortcut for
629 the Staff Client. To launch the Staff Client, visit the
630 <literal>All Applications</literal> menu on your desktop and
631 find the section similar to:</para>
634 <guimenu>Wine</guimenu>
635 <guimenuitem>Program Files</guimenuitem>
636 <guimenuitem>Evergreen Staff Client</guimenuitem>
637 <guimenuitem>Evergreen Staff Client</guimenuitem>
640 <para>or else launch the Staff Client from the new desktop shortcut.</para>
647 <title>Building the Staff Client</title>
649 <primary>staff client</primary>
650 <secondary>building</secondary>
652 <para>You can also manually build the Staff Client by using the <command>make</command>
653 utility in the Staff Client source directory (e.g., the directory
654 <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client</filename>
655 for the current Evergreen version). There are a number of possible options to manually
656 build special versions of the Staff Client on a Linux system. Following is a list of
657 variables that you can pass to <command>make</command> to influence the manual build
661 Build Variable <envar>STAFF_CLIENT_BUILD_ID</envar></title>
662 <para>During the normal <emphasis>make install</emphasis> Evergreen server-side
663 software build process, the variable defaults to an automatically generated
664 date/time string, but you can also override the value of <envar>BUILD_ID</envar>.</para>
665 <para>You could use the following commands during the normal install process:</para>
669 cd /home/opensrf/Evergreen-ILS-1.6.1.6
670 make STAFF_CLIENT_BUILD_ID=1_6_1_6 install</userinput>
672 <para>You can also manually build the Staff Client in the Staff Client
673 source directory with a different <envar>BUILD_ID</envar>.</para>
674 <para>As the <systemitem class="username">opensrf</systemitem> user,
675 execute the following commands to build the Staff Client (remember to replace
676 <emphasis>NEW_VERSION</emphasis> with an appropriate value):</para>
679 # as the opensrf user:
680 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
681 make STAFF_CLIENT_BUILD_ID=NEW_VERSION build</userinput>
686 Build Variable <envar>STAFF_CLIENT_VERSION</envar></title>
687 <para>During the normal <emphasis>make install</emphasis> Evergreen server-side
688 software build process, the variable is pulled automatically from a README file
689 in the Evergreen source root. The variable defaults to
690 <emphasis>0trunk.revision</emphasis>, where the value of "revision" is
691 automatically generated. You can override the value of <envar>VERSION</envar>
692 similarly to the <envar>BUILD_ID</envar>.</para>
693 <para>You could use the following commands during the normal install process:</para>
697 cd /home/opensrf/Evergreen-ILS-1.6.1.6
698 make STAFF_CLIENT_VERSION=0mytest.200 install</userinput>
700 <para>You can also manually build the Staff Client in the Staff Client
701 source directory with a different <envar>VERSION</envar>.</para>
702 <para>If you plan to make extensions update automatically, the
703 <envar>VERSION</envar> needs to conform to the format recommended in
704 <ulink url="https://developer.mozilla.org/en/Toolkit_version_format">
705 Toolkit Version Format</ulink> and newer versions need to be "higher" than older
707 <para>As the <systemitem class="username">opensrf</systemitem> user,
708 execute the following commands to build the Staff Client:</para>
711 # as the opensrf user:
712 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
713 make STAFF_CLIENT_VERSION=0mytest.200 build</userinput>
718 Build Variable <envar>STAFF_CLIENT_STAMP_ID</envar></title>
719 <para>During the normal <emphasis>make install</emphasis> Evergreen
720 server-side software build process, the variable is generated from
721 <envar>STAFF_CLIENT_VERSION</envar>. You may want to have multiple versions
722 of the Staff Client with different stamps, possibly for different uses or
723 client-side customizations. You can override the value of
724 <envar>STAMP_ID</envar> similarly to the <envar>BUILD_ID</envar>.</para>
725 <para>You could use the following commands during the normal install process:</para>
729 cd /home/opensrf/Evergreen-ILS-1.6.1.6
730 make STAFF_CLIENT_STAMP_ID=my_test_stamp install</userinput>
732 <para>You can also manually build the Staff Client in the Staff Client
733 source directory with a different <envar>STAMP_ID</envar>.</para>
734 <para>As the <systemitem class="username">opensrf</systemitem> user,
735 execute the following commands to build the Staff Client:</para>
738 # as the opensrf user:
739 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
740 make STAFF_CLIENT_STAMP_ID=my_test_stamp build</userinput>
745 <title>Advanced Build Options</title>
747 <primary>staff client</primary>
748 <secondary>building</secondary>
749 <tertiary>advanced build options</tertiary>
751 <para>In addition to the basic options listed above, there are a number of advanced
752 options for building the Staff Client. Most are target names for the
753 <command>make</command> utility and require that you build the Staff Client from the
754 <literal>staff_client</literal> directory. See the following table for a list of
755 possible <command>make</command> target keywords:</para>
757 <title>Keywords For Advanced Build Options</title>
758 <?dbfo keep-together="always" ?>
759 <tgroup align="left" cols="2" colsep="1" rowsep="1">
760 <colspec colname="keyword" colnum="1" colwidth="1.0*"/>
761 <colspec colname="description" colnum="2" colwidth="3.0*"/>
764 <entry>Keyword</entry>
765 <entry>Description</entry>
770 <entry>clients</entry>
771 <entry>Runs "make win-client", "make linux-client", and "make
772 generic-client" individually</entry>
775 <entry>client_dir</entry>
776 <entry>Builds a client directory from the build directory, without
777 doing a rebuild. The same as "copy everything but
781 <entry>client_app</entry>
782 <entry>Prerequisite "client_dir"; removes "install.rdf" from
783 client directory so an APP bundle can't be installed as an
787 <entry>client_ext</entry>
788 <entry>Prerequisite "client_dir"; remove "application.ini",
789 "autoupdate.js", "standalone_xul_app.js" from client directory so
790 an extension won't break Firefox</entry>
793 <entry>extension</entry>
794 <entry>Prerequisite "client_ext"; rewritten to use "client_ext"</entry>
797 <entry>generic-client</entry>
798 <entry>Prerequisite "client_app"; makes an XPI file suitable for
799 use with "xulrunner --install-app""</entry>
802 <entry>win-xulrunner</entry>
803 <entry>Prerequisite "client_app"; adds Windows xulrunner to client build</entry>
806 <entry>linux-xulrunner</entry>
807 <entry>Prerequisite "client_app"; adds Linux xulrunner to client build</entry>
810 <entry>win-client</entry>
811 <entry>Prerequisite "win-xulrunner"; builds "setup exe" (requires
812 that "nsis" package be installed, will add options for automatic
813 update if configured and developer options if client build was a
814 "make devbuild")</entry>
817 <entry>linux-client</entry>
818 <entry>Prerequisite "linux_xulrunner"; builds a "tar.bz2" bundle
819 of the Linux client</entry>
822 <entry>[generic-|win-|linux-|extension-]updates[-client]</entry>
823 <entry>Calls external/make_updates.sh to build full and partial
824 updates generic/win/linux/extension prefix limit to that
825 distribution; Adding <option>-client</option> builds clients and
826 copies them to a subdirectory of the
827 <filename class="directory">updates</filename> directory as well;
828 <option>extension-updates-client</option> doesn't exist.</entry>
833 <para>Following are descriptions of other special build options:</para>
835 <title>Developer Build</title>
836 <para>You can create a so-called <emphasis>developer build</emphasis>
837 of the Staff Client by substituting <option>devbuild</option> for
838 <option>build</option> when running <command>make</command> from the
839 <literal>staff_client</literal> directory. The build will contain an
840 extra configuration file that enables some developer options.</para>
841 <para>As the <systemitem class="username">opensrf</systemitem> user, run
842 the following commands from the Staff Client source directory:</para>
845 # as the opensrf user:
846 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
847 make devbuild</userinput>
851 <title>Compressed Javascript</title>
852 <para>You can execute the Google <systemitem class="resource">Closure Compiler</systemitem>
853 utility to automatically review and compress Javascript code after the build
854 process completes, by substituting <option>compress-javascript</option> for
855 <option>build</option> when running <command>make</command>.
856 For more information on the Google Closure Compiler, see
857 <ulink url="http://code.google.com/closure/compiler/">
858 http://code.google.com/closure/compiler</ulink>.</para>
859 <para>As the <systemitem class="username">opensrf</systemitem> user, run
860 the following commands from the Staff Client source directory:</para>
863 # as the opensrf user:
864 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
865 make compress-javascript</userinput>
867 <para>You can also combine Javascript review and compression, and also perform a
868 <emphasis>developer build</emphasis>.</para>
869 <para>As the <systemitem class="username">opensrf</systemitem> user, run
870 the following <command>make</command> command from the Staff Client source directory
871 (the order of options is important):</para>
874 # as the opensrf user:
875 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
876 make devbuild compress-javascript</userinput>
879 <simplesect xml:id="staffclientinstallation-autoupdatehost">
880 <title>Automatic Update Host</title>
881 <para>You can override the host used to check for automatic Staff Client updates
882 by specifying the <option>AUTOUPDATE_HOST</option> option.</para>
883 <para>You could use the following commands during the normal install process:</para>
887 cd /home/opensrf/Evergreen-ILS-1.6.1.6
888 make AUTOUPDATE_HOST=localhost install</userinput>
890 <para>You can manually build the Staff Client in the Staff Client
891 source directory and set <option>AUTOUPDATE_HOST</option> to enable automatic
892 update checking.</para>
893 <para>As the <systemitem class="username">opensrf</systemitem> user,
894 execute the following commands to build the Staff Client:</para>
897 # as the opensrf user:
898 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
899 make AUTOUPDATE_HOST=localhost build</userinput>
901 <para>For more information on Automatic Updates, see
902 <xref linkend="staffclientinstallation-autoupdate"/>.</para>
906 <title>Installing and Activating a Manually Built Staff Client</title>
907 <para>The Staff Client is automatically built, installed and activated as part of the
908 normal <command>make<option>install</option></command> process for Evergreen
909 server-side software. However, if you manually build the Staff Client from the
910 <literal>staff_client</literal> directory, then you need to take additional steps to
911 properly install and activate it. You also have the option of installing the Staff
912 Client on the same machine it was built on, or on a different machine.</para>
913 <para>Assuming you have already built the Staff Client, and that your installation is
914 in the directory <filename class="directory">/openils/var/web/xul</filename>, as the
915 <systemitem class="username">opensrf</systemitem> user execute the following
919 # as the opensrf user:
920 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
921 mkdir -p "/openils/var/web/xul/$(cat build/BUILD_ID)"
922 cp -R build/server "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput>
926 <title>Packaging the Staff Client</title>
927 <para>Once you have built the Staff Client, you can create several forms of special client
928 packages by using a modified <command>make</command> command in the <literal>staff_client</literal>
931 <title>Packaging a Generic Client</title>
932 <para>This build creates a Staff Client packaged as an XPI file suitable for use with
933 the <option>--install-app</option> parameter of <application>XULrunner</application>.
934 It requires that you already have the <systemitem>zip</systemitem> utility
935 installed on your system.</para>
936 <para>As the <systemitem class="username">opensrf</systemitem> user, execute
937 the following commands:</para>
940 # as the opensrf user:
941 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
942 make generic-client</userinput>
944 <para>The output file <filename>evergreen_staff_client.xpi</filename> will be created.</para>
947 <title>Packaging a <systemitem class="osname">Windows</systemitem> Client</title>
948 <para>This build creates a Staff Client packaged as a
949 <systemitem class="osname">Windows</systemitem> executable. It requires that
950 you already have the <application>unzip</application> utility installed on
951 your system. It also requires that you install
952 <ulink url="http://nsis.sourceforge.net/">NSIS (Nullsoft Scriptable Install System)</ulink>,
953 a professional open source utility package used to create
954 <systemitem class="osname">Windows</systemitem> installers (the
955 <application>"makensis"</application> utility is installed as part of the
956 <application>"nsis"</application> package). You should use Version 2.45 or
958 <para>If you wish for the Staff Client to have a link icon/tray icon by
959 default, you may wish to provide a pre-modified
960 <application>xulrunner-stub.exe</application>. Place it in the Staff Client
961 source directory and <command>make</command> will automatically use it instead
962 of the one that comes with the downloaded <application>XULrunner</application>
963 release. The version of <application>xulrunner-stub.exe</application> need not
964 match exactly.</para>
965 <para>You can also use a tool such as
966 <ulink url="http://www.angusj.com/resourcehacker/">Resource Hacker</ulink>
967 to embed icons. <application>Resource Hacker</application> is an open-source
968 utility used to modify resources within 32-bit
969 <systemitem class="osname">Windows</systemitem> executables.
970 Some useful icon ID strings include the following:</para>
972 <?dbfo keep-together="always" ?>
973 <title>Icon IDs for Packaging a Windows Client</title>
974 <tgroup align="left" cols="2" colsep="1" rowsep="1">
975 <colspec colname="keyword" colnum="1" colwidth="1.0*"/>
976 <colspec colname="icon" colnum="2" colwidth="1.0*"/>
979 <entry>IDI_APPICON</entry>
980 <entry>Tray icon</entry>
984 <entry>Default window icon</entry>
989 <para>As the <systemitem class="username">opensrf</systemitem> user
990 execute the following commands:</para>
993 # as the opensrf user:
994 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
995 make win-client</userinput>
997 <para>The output file <filename>evergreen_staff_client_setup.exe</filename> will be created.</para>
1000 <title>Packaging a Linux Client</title>
1001 <para>This build creates a Staff Client packaged as a compressed
1002 <literal>tar</literal> archive file with <application>XULrunner</application>
1003 already bundled with it. It requires that you already have the
1004 <application>bzip2</application> utility installed on your system.</para>
1005 <para>As the <systemitem class="username">opensrf</systemitem> user,
1006 execute the following commands:</para>
1009 # as the opensrf user:
1010 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
1011 make linux-client</userinput>
1013 <para>The output file <filename>evergreen_staff_client.tar.bz2</filename> will be created.</para>
1016 <title>Packaging a <application>Firefox</application> Extension</title>
1017 <para>This build creates a Staff Client packaged as a <application>Firefox</application>
1018 extension. It requires that you already have the <systemitem>zip</systemitem>
1019 utility installed on your system.</para>
1020 <para>As the <systemitem class="username">opensrf</systemitem> user,
1021 execute the following commands:</para>
1024 # as the opensrf user:
1025 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
1026 make extension</userinput>
1028 <para>The output file <filename>evergreen.xpi</filename> will be created.</para>
1031 <section xml:id="staffclientinstallation-autoupdate">
1032 <title>Staff Client Automatic Updates</title>
1034 <primary>staff client</primary>
1035 <secondary>automatic updates</secondary>
1037 <para>It is possible to set up support for automatic Staff Client updates, either during
1038 the normal Evergreen server-side build process, or by manually building the Staff Client
1039 with certain special options.</para>
1041 <para>Automatic update server certificate requirements are more strict than
1042 normal server requirements. <application>Firefox</application> and
1043 <application>XULrunner</application> will both ignore any automatic update
1044 server that is not validated by a trusted certificate authority. Servers with
1045 exceptions added to force the Staff Client to accept them <emphasis>WILL NOT
1046 WORK</emphasis>.</para>
1047 <para>In addition, automatic updates have special requirements for the file
1048 <filename>update.rdf</filename>:</para>
1050 <listitem>It must be served from an SSL server, or</listitem>
1051 <listitem>It must be signed with the <ulink url="https://developer.mozilla.org/en/McCoy">
1052 https://developer.mozilla.org/en/McCoy</ulink> tool.</listitem>
1054 <para>You can pre-install the signing key into the file
1055 <filename>install.rdf</filename> directly, or install it into a copy as
1056 <filename>install.mccoy.rdf</filename>. If the latter exists it will be copied
1057 into the build instead of the original file
1058 <filename>install.rdf</filename>.</para>
1061 <title>Autoupdate Host</title>
1062 <para>You can manually set the name of the automatic update host. If you do
1063 not set the name then, by default, the Staff Client will not include an
1064 automatic update preference. You can set the autoupdate host name as
1068 <para>At configuration time during the normal <emphasis>make install</emphasis>
1069 process for Evergreen server-side software.</para>
1070 <para>You can do this when you first configure the Evergreen server-side
1071 software (see <xref linkend="serversideinstallation-configure"/>).
1072 As the <systemitem class="username">opensrf</systemitem> user, execute
1073 the following commands:</para>
1076 # as the opensrf user:
1077 cd /home/opensrf/Evergreen-ILS-1.6.1.6
1078 ./configure --prefix=/openils --sysconfdir=/openils/conf --with-updateshost=hostname
1083 <para>During a manual Staff Client build process.</para>
1084 <para>You can override the variable
1085 <envar>AUTOUPDATE_HOST=hostname</envar> and manually build the
1086 Staff Client from the <literal>staff_client</literal>
1087 directory (see <xref linkend="staffclientinstallation-autoupdatehost"/>
1088 for details). If you specify only a bare hostname (for example,
1089 <systemitem class="domainname">example.com</systemitem>) then
1090 the Staff Client will automatically use the secure URL
1091 <systemitem class="domainname">https://example.com</systemitem>.
1092 If you wish to use a non-https URL, then you must explicitly
1093 specify the full URL (for example,
1094 <systemitem class="domainname">http://example.com</systemitem>).</para>
1095 <para>As the <systemitem class="username">opensrf</systemitem> user,
1096 execute the following commands to build the Staff Client (remember to
1097 replace <emphasis>SOME_URL</emphasis> with an appropriate value):</para>
1100 # as the opensrf user:
1101 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
1102 make AUTOUPDATE_HOST=http://SOME_URL build</userinput>
1108 <title>Building Updates</title>
1110 <primary>staff client</primary>
1111 <secondary>automatic updates</secondary>
1112 <tertiary>building</tertiary>
1114 <para>Similar to building clients, you can use the targets
1115 <option>generic-updates</option>, <option>win-updates</option>,
1116 <option>linux-updates</option>, and <option>extension-updates</option>
1117 individually with <command>make</command> to build the update files for the
1118 Staff Client. To build all the targets at once, simply use the target
1119 <option>updates</option>.</para>
1120 <para>A full update will be built for each specified target (or for all if you
1121 use the target <option>updates</option>). For all but extensions any previous
1122 full updates (archived by default in the directory
1123 <filename class="directory">/openils/var/updates/archives</filename>) will be
1124 used to make partial updates. Partial updates tend to be much smaller and will
1125 thus download more quickly, but if something goes wrong with a partial update
1126 the full update will be used as a fallback. Extensions do not currently support
1127 partial updates.</para>
1128 <para>As the <systemitem class="username">opensrf</systemitem> user, change
1129 directory to the Staff Client source directory, then execute the following
1133 # as the opensrf user:
1134 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client</userinput>
1136 <para>Command to build all updates at once:</para>
1139 # as the opensrf user:
1140 make updates</userinput>
1142 <para>commands to build updates individually:</para>
1145 # as the opensrf user:
1146 make generic-updates
1149 make extension-updates</userinput>
1153 <title>Building updates with clients</title>
1155 <primary>staff client</primary>
1156 <secondary>automatic updates</secondary>
1157 <tertiary>building with clients</tertiary>
1159 <para>To save time and effort you can build updates and manual download
1160 clients at the same time by adding the phrase <literal>"-client"</literal> to each
1161 target name (for example, you could specify <option>updates-client</option> to build
1162 all the targets at once, or you could specify <option>win-updates-client</option>
1163 to build updates individually). This process will not work for the option
1164 <option>extension-updates</option>.</para>
1165 <para>The clients will be installed alongside the updates and listed on the
1166 <filename>manualupdate.html</filename> page, instead of being left in the
1167 <literal>staff_client</literal> directory.</para>
1168 <para>As the <systemitem class="username">opensrf</systemitem> user, execute
1169 one of the following commands:</para>
1170 <para>To build all updates at once:</para>
1173 # as the opensrf user:
1174 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
1175 make updates-client</userinput>
1177 <para>To build updates individually:</para>
1180 # as the opensrf user:
1181 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
1182 make generic-updates-client
1183 make win-updates-client
1184 make linux-updates-client</userinput>
1188 <title>Activating the Update Server</title>
1190 <primary>staff client</primary>
1191 <secondary>automatic updates</secondary>
1192 <tertiary>activating the update server</tertiary>
1194 <para>This section reviews scripts associated with the update server, and
1195 requires some final adjustments to file permissions.</para>
1196 <para>The Apache example configuration creates an <literal>updates</literal>
1197 directory that, by default, points to the directory
1198 <filename class="directory">/openils/var/updates/pub</filename>. This
1199 directory contains one HTML file and several specially-named script files.</para>
1200 <para>The <filename>updatedetails.html</filename> file is the fallback web
1201 page for the update details. The <filename>check</filename> script is used for
1202 <application>XULrunner</application> updates. The
1203 <filename>update.rdf</filename> script is used for extension updates.
1204 The <filename>manualupdate.html</filename> file checks for clients to provide
1205 download links when automatic updates have failed and uses the download script
1206 to force a download of the generic client XPI (compared to
1207 <application>Firefox</application> trying to install it as an
1209 <para>To change the permissions for the scripts
1210 <filename>check</filename>, <filename>download</filename>,
1211 <filename>manualupdate.html</filename>, and
1212 <filename>update.rdf</filename>, as the root user execute the following
1217 cd /openils/var/updates/pub
1218 chmod +x check download manualupdate.html update.rdf</userinput>
1223 <title>Other tips</title>
1224 <simplesect xml:id="staffclientinstallation-othertips">
1225 <title>Multiple workstations on one install</title>
1226 <para>Multiple workstation registrations for the same server can be accomplished
1227 with a single Staff Client install by using multiple profiles. When running
1228 <application>XULrunner</application> you can specify the option
1229 <literal>"-profilemanager"</literal> or <literal>"-P"</literal> (uppercase "P")
1230 to force the Profile Manager to start. Unchecking the <literal>"Don't ask at startup"</literal>
1231 option will make this the default.</para>
1232 <para>Once you have opened the Profile Manager you can create additional
1233 profiles, one for each workstation you wish to register. You may need to install
1234 SSL exceptions for each profile.</para>
1235 <para>When building any of the targets <option>win-client</option>,
1236 <option>win-updates-client</option>, or <option>updates-client</option>, you can
1237 specify <option>NSIS_EXTRAOPTS=-DPROFILES</option> to add an option
1238 <guimenuitem>"Evergreen Staff Client Profile Manager"</guimenuitem> to the
1240 <para>As the <systemitem class="username">opensrf</systemitem> user,
1241 execute the following commands:</para>
1244 # as the opensrf user:
1245 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client
1246 make NSIS_EXTRAOPTS=-DPROFILES win-client</userinput>
1250 <title> Multiple Staff Clients</title>
1251 <para>It may be confusing if you are not careful, but you can log in to
1252 multiple Evergreen servers at the same time, or a single Evergreen server
1253 multiple times. In either case you will need to create an additional profile for
1254 each additional server or workstation you want to log in as (see the previous
1255 tip in <xref linkend="staffclientinstallation-othertips"/>).</para>
1256 <para>Once you have created the profiles, run
1257 <application>XULrunner</application> with the option <option>-no-remote</option>
1258 (in addition to <option>"-profilemanger"</option> or <option>"-P"</option> if
1259 needed). Instead of <application>XULrunner</application> opening a new login
1260 window on your existing session it will start a new session instead, which can
1261 then be logged in to a different server or workstation ID.</para>
1265 <section xml:id="staffclientinstallation-running-staffclient">
1266 <title>Running the Staff Client</title>
1268 <primary>staff client</primary>
1269 <secondary>running</secondary>
1270 <tertiary>linux</tertiary>
1272 <para>You can run the Staff Client on a Linux system by using the
1273 <application>XULrunner</application> application (installed automatically and by default
1274 with <application>Firefox</application> <literal>Version 3.0</literal> and later on
1275 <systemitem class="osname">Ubuntu</systemitem> and
1276 <systemitem class="osname">Debian</systemitem> distributions).</para>
1277 <para>For example, if the source files for the Evergreen installation are in the directory
1278 <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.6/</filename> you can start the
1279 Staff Client as shown in the following example:</para>
1282 # as the opensrf user:
1283 cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client/build
1284 xulrunner application.ini</userinput>
1286 <section xml:id="staffclientinstallation-workstationnames">
1287 <title>Assigning Workstation Names</title>
1289 <primary>staff client</primary>
1290 <secondary>assigning workstation names</secondary>
1292 <para>The Staff Client must be assigned to a library and given a unique name before it
1293 will connect fully to the Evergreen server. The only restriction is that the workstation's
1294 name must be unique within the assigned library. Make sure to select a workstation name
1295 that you will remember later, one that reflects the role, purpose, and/or location of a
1296 particular computer. These names will come up later in statistical reporting, and can also
1297 be handy when troubleshooting.</para>
1300 <phrase>Example of unconfigured Staff Client</phrase>
1303 <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-1.png" format="PNG" scalefit="1" width="60%"/>
1306 <para>In order to assign a workstation a name, a user with appropriate
1307 permissions must login to the Staff Client. In PINES, the local system
1308 administrator (OPSM) has the ability to assign workstation names in their
1309 library system. Library managers (LIBM's) have the ability within their
1310 branch. To assign a workstation a name, login to the system. You will be
1311 prompted to assign the workstation a library and a name:</para>
1314 <phrase>Example of configured Staff Client</phrase>
1317 <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-2.png" format="PNG" scalefit="1" width="60%"/>
1320 <para>Select the library this workstation physically operates in from the drop
1321 down menu. In this example, we have selected "MGRL-MA". Type in a friendly name
1322 for the workstation. In this example, we are installing the Staff Client on the
1323 director's personal system, and have named it as such. Then click
1324 <guibutton>'Register'</guibutton>.</para>
1325 <para>Once you have registered your workstation
1326 with the server, your screen will look like this:</para>
1329 <phrase>Example of registered Staff Client</phrase>
1332 <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-3.png" format="PNG" scalefit="1" width="60%"/>
1335 <para>You are now ready to log into the Staff Client for the first time. Type in
1336 your password again, and click <guibutton>'Login'</guibutton>.</para>
1338 <section xml:id="staffclientinstallation-proxy">
1339 <title>Running the Staff Client Over An <systemitem class="protocal">SSH</systemitem> Tunnel</title>
1341 <primary>staff client</primary>
1342 <secondary>running through an SSH tunnel</secondary>
1344 <para>You can configure the Staff Client to communicate with the Evergreen server over
1345 an <systemitem class="protocal">SSH</systemitem> tunnel using a SOCKS 5 proxy
1346 server. There are several reasons for sending network traffic for the Staff Client
1347 through an <systemitem class="protocal">SSH</systemitem> proxy:</para>
1350 <para>Firewalls may prevent you from reaching the Evergreen
1351 server. This may happen when you are connecting the Staff
1352 Client to a test server that should not be available
1353 generally, or it may be the result of network design
1354 priorities other than ease of use.</para>
1357 <para>You may wish to improve security in situations where
1358 Staff Client traffic may be susceptible to network
1359 eavesdropping. This is especially true when staff machines
1360 connect via wireless links to the network.</para>
1364 <title>Setting Up an <systemitem class="protocal">SSH</systemitem> Tunnel</title>
1365 <para>You will need a server that allows you to log in via
1366 <systemitem class="protocal">SSH</systemitem> and has network access to the
1367 Evergreen server you want to reach. You will use your username and password
1368 for that <systemitem class="protocal">SSH</systemitem> server to set up a
1370 <para>For <systemitem class="osname">Windows</systemitem> users, one good
1371 solution is the open-source utility
1372 <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty/">PuTTY</ulink>,
1373 a free <systemitem class="protocal">telnet/SSH</systemitem> client.
1374 Following are instructions for setting up an <application>SSH</application>
1375 session using the <application>PuTTY</application> utility:</para>
1378 <phrase>Setting up an <systemitem class="protocal">SSH</systemitem>
1379 tunnel in <application>PuTTY</application></phrase>
1382 <imagedata fileref="../media/staffclientinstallation-proxy-putty-1.png" format="PNG" scalefit="1" width="60%"/>
1387 <para>Using the menu on the left, find the section:</para>
1390 <guimenu>Connection</guimenu>
1391 <guimenuitem>SSH</guimenuitem>
1392 <guimenuitem>Tunnels</guimenuitem>
1397 <para>In the section on the right labeled <literal>"Source
1398 port"</literal>, enter <literal>9999</literal>.</para>
1401 <para>Set the checkbox <literal>"Dynamic"</literal>. Do not
1402 enter anything in the <literal>"Destination"</literal> text
1406 <para>Click <guibutton>'Add'</guibutton> and notice that
1407 <literal>"D9999"</literal> now appears in the section
1408 labeled <literal>"Forwarded ports"</literal>.</para>
1411 <para>Use the menu on the left, find the
1412 <literal>"Session"</literal> section, then enter the host name
1413 of the <systemitem class="protocal">SSH</systemitem>
1417 <para>A pop-up window will open to allow you to enter your
1418 username and password. Once you are logged in, the tunnel is
1422 <para>See <ulink url="http://inside.mines.edu/~gmurray/HowTo/sshNotes.html">How to set up
1423 <systemitem class="protocal">SSH</systemitem> (for the beginner)</ulink> for information on
1424 setting up <systemitem class="protocal">SSH</systemitem> for other client operating
1428 <title>Configuring the Staff Client to Use the <systemitem class="protocal">SSH</systemitem> Tunnel</title>
1429 <para>In order to tell the Staff Client that all traffic should be sent
1430 through the <systemitem class="protocal">SSH</systemitem> tunnel just configured,
1431 you must find edit the file <filename>all.js</filename>, usually located at
1432 <filename>C:\Program Files\Evergreen Staff Client\greprefs\all.js</filename>
1433 on a <systemitem class="osname">Windows</systemitem> system.
1434 Search this file for the word <literal>socks</literal> to find the appropriate
1435 section for the following changes.</para>
1438 <phrase>The SOCKS section of "all.js" before changes</phrase>
1441 <imagedata fileref="../media/staffclientinstallation-proxy-socks-1.png" format="PNG" scalefit="1" width="70%"/>
1444 <para>Make the following changes:</para>
1447 <para>Change the value of <literal>network.proxy.socks</literal>
1448 from <literal>""</literal> to <literal>localhost</literal>.</para>
1451 <para>Change the value of <literal>network.proxy.socks_port</literal>
1452 from <literal>0</literal> to <literal>9999</literal>.</para>
1457 <phrase>The SOCKS section of "all.js" after changes</phrase>
1460 <imagedata fileref="../media/staffclientinstallation-proxy-socks-2.png" format="PNG" scalefit="1" width="70%"/>
1463 <para>If everything is working correctly, you should now be able to run
1464 the Staff Client and all its data will be sent encrypted through the
1465 <systemitem class="protocal">SSH</systemitem> tunnel you have just configured.</para>
1469 <title>Navigating a Tabbed Interface</title>
1470 <para>Like many popular current web browsers and other applications, the Staff Client
1471 uses a "tabbed" interface. Tabs allow you to have several pages open at the same time
1472 in a single window. This is easier to manage on your computer screen than multiple
1473 windows, since you can easily switch between tabs in the same window.</para>
1476 <phrase>Tabs in the Staff Client window</phrase>
1479 <imagedata fileref="../media/staffclientinstallation-tabbed-1.png" format="PNG" scalefit="1" width="70%"/>
1482 <para>The "tabs" appear below the menu bar in the Staff Client with a descriptive
1483 title. Simply select a tab to bring it to the front and view the page displayed in the
1484 tab. You can use tabs to have access to multiple things all at the same time: patron
1485 records and searches, bibliographic records and searches, circulation or cataloging
1486 interfaces - anything at all in the Staff Client.</para>
1488 <listitem>Create a new tab by pressing
1490 <keycap>Ctrl</keycap>
1493 on the keyboard or selecting:
1495 <guimenu>File</guimenu>
1496 <guimenuitem>New Tab</guimenuitem>
1498 from the menu.</listitem>
1499 <listitem>Close a tab by pressing
1501 <keycap>Ctrl</keycap>
1503 </keycombo> on the keyboard or selecting
1505 <guimenu>File</guimenu>
1506 <guimenuitem>Close Tab</guimenuitem>
1508 from the menu.</listitem>
1509 <listitem>Switch tabs by pressing
1511 <keycap>Ctrl</keycap>
1512 <keycap>Tab</keycap>
1514 on the keyboard or selecting the tab in the tab bar.</listitem>
projects / working / Evergreen.git / blob