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 Windows, Mac or Linux systems. Installing the
18 Staff Client in each of these environments is described in the following sections.</para>
19 <section xml:id="staffclientinstallation-installing-windows">
20 <title>Installing on Windows</title>
22 <primary>staff client</primary>
23 <secondary>installing</secondary>
24 <tertiary>Windows</tertiary>
26 <para>In this section we describe the process of installing the Staff Client on the
27 <systemitem class="osname">Microsoft Windows</systemitem> operating
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 Microsoft Windows Installer that contains the current version of
32 the Staff Client. Download the Installer, then run it. A screen that looks similar to
33 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="70%"/>
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="70%"/>
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 Mac OS</title>
70 <primary>staff client</primary>
71 <secondary>installing</secondary>
72 <tertiary>Mac OS</tertiary>
74 <para>In this section, we describe Mac packages and related versions of XULRunner
75 that can be used to run the Staff Client in a Mac OS environment.</para>
77 <title>Evergreen Version 1.2.3.0</title>
80 <para>A Mac package that contains an early version of the Staff Client
81 (version 1.2.3.0) for use with XULRunner is available. Current releases
82 of XULRunner can be found here:
83 <ulink url="http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases">
84 http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases</ulink> .
85 Download and install the latest version. Further information about
86 XULRunner can be found here:
87 <ulink url="https://developer.mozilla.org/en/xulrunner">
88 https://developer.mozilla.org/en/xulrunner</ulink></para>
89 <para>Note that later versions of XULRunner (e.g., version 1.9.2.13) have
90 replaced version 1.8.0.4, which has known security holes and is not
91 recommended for applications that deal with public web content.</para>
94 <para>A Mac OS Installation package for Staff Client version 1.2.3.0
95 is available from Evergreen Indiana. Download and install it from here:
96 <ulink url="http://evergreen.lib.in.us/opac/extras/files/evergreen_osx_staff_client_1_2_3.zip">
97 evergreen_osx_staff_client_1_2_3.zip</ulink> .
101 <para>To upgrade to a more recent version of the Staff Client, you can
102 copy the <filename class="directory">build</filename> directory from a
103 working Windows installation of the desired version of the Staff Client
104 to your Mac. The required files may be located in a directory like this
105 on the Windows machine: <filename class="directory">
106 C:\Program Files\Evergreen Staff Client\build</filename>.
107 Copy these files to the <filename class="directory">Resources</filename>
108 folder within the <package>Open-ILS</package> package in your
109 <filename class="directory">Applications</filename> directory on the Mac,
110 overwriting files with the same names.</para>
112 <listitem>Drag the application's icon to your toolbar for easier
115 <para>When you run the Staff Client installer, a screen will appear that looks
116 similar to this:</para>
119 <phrase>Running the Staff Client installer for Mac OS</phrase>
122 <imagedata fileref="../media/staffclientinstallation-staffclient-3.png" format="PNG" scalefit="1" width="20%"/>
125 <para>Click <guibutton>'Continue'</guibutton>, accept the license, then finish the
126 installation. The application will be located at the destination you selected
127 during installation. You will then be able to drag the application into your
128 toolbar for easier access.</para>
131 <phrase>Finishing the installation</phrase>
134 <imagedata fileref="../media/staffclientinstallation-staffclient-4.png" format="PNG" scalefit="1" width="20%"/>
139 <title>Running directly using XULRunner</title>
141 <primary>staff client</primary>
142 <secondary>XULRunner</secondary>
144 <para>You must install an apropriate version of XULRunner to match the Evergreen
145 version. See the following table for the recommended version of
148 <title>Evergreen / XULRunner Dependencies</title>
149 <tgroup align="left" cols="2" colsep="1" rowsep="1">
150 <colspec colnum="1" colwidth="1.0*"/>
151 <colspec colnum="2" colwidth="3.0*"/>
154 <entry>Evergreen 1.6.x.x</entry>
155 <entry>XULrunner 1.9</entry>
158 <entry>Evergreen 1.4.x.x</entry>
159 <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry>
162 <entry>Evergreen 1.2.x.x</entry>
163 <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry>
168 <note>If you have issues removing previously installed XULRunner versions see
169 <xref linkend="staffclientinstallation-remove-xulrunner"/> for further
172 <para>The Staff Client data from the directory
173 <filename class="directory">./staff_client/build</filename> must be placed
174 somewhere on the machine
175 (e.g. <filename class="directory">~/Desktop/Evergreen_Staff_Client</filename>).
176 Remember to call XULRunner with the full path to the binary, followed by the
177 install command and the path to the client data:</para>
179 <prompt># as the root user</prompt>
180 <userinput>/Library/Frameworks/XUL.framework/xulrunner-bin --install-app ~/Desktop/Evergreen_Staff_Client</userinput>
182 <para>This command should exit quietly. The folder
183 <filename class="directory">/Applications/OpenILS</filename> will be created,
184 containing a launcher named <application>open_ils_staff_client</application>.</para>
186 <simplesect xml:id="staffclientinstallation-remove-xulrunner">
187 <title>Removing previously installed XULRunner versions</title>
189 <primary>XULRunner</primary>
190 <secondary>removing previous versions</secondary>
192 <para>If you already have a newer version installed, per the release notes, you
193 will need to remove the entire directory
194 <filename class="directory">/Library/Frameworks/XUL.framework</filename>
195 before downgrading.</para>
196 <para>In addition, you may also need to remove the previous
197 file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> .</para>
198 <para>If file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> does
199 not exist (possibly in newer OSX releases), you need to flush the file
200 <filename>receiptdb</filename>.</para>
201 <note>If you install a newer version over a previous (older) install, the older
202 one is not removed but the symlinks are changed to the newer one.</note>
205 <title>Flush Receiptdb file:</title>
206 <para>First, get the package identifier, then purge/forget the build that was
207 initially installed:</para>
209 <prompt># as the root user</prompt>
210 <userinput>sudo pkgutil --pkgs > /tmp/pkgs.txt</userinput>
211 <userinput>sudo pkgutil --forget org.mozilla.xulrunner</userinput>
213 <note>It may not be necessary to edit the file
214 <filename>/Library/Receipts/InstallHistory.plist</filename> after deleting the
215 folder <filename class="directory">XUL.framework</filename>. See
216 <ulink url="http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html">
217 http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html</ulink>
218 for more information.</note>
221 <title>Creating an APP file: Staff Client & XULRunner Bundled</title>
222 <para>An APP file is basically a folder. Start with a folder stucture like this:</para>
230 <para>Create an APP folder structure with the following commands:</para>
232 <prompt># as the root user</prompt>
233 <userinput>mkdir -p Evergreen.app/Contents/Frameworks</userinput>
234 <userinput>mkdir -p Evergreen.app/Contents/Resources</userinput>
235 <userinput>mkdir -p Evergreen.app/Contents/MacOS</userinput>
240 <para>Create a new file in the folder
241 <filename class="directory">Evergreen.app/Contents/Info.plist</filename>
242 containing the following data (adjust for your version of
244 <programlisting language="xml"><![CDATA[
245 <?xml version="1.0" encoding="UTF-8"?>
246 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
247 <plist version="1.0">
249 <key>CFBundleExecutable</key>
250 <string>xulrunner</string>
251 <key>CFBundleGetInfoString</key>
252 <string>OpenILS open_ils_staff_client rel_1_6_0_7</string>
253 <key>CFBundleInfoDictionaryVersion</key>
255 <key>CFBundleName</key>
256 <string>Evergreen Staff Client</string>
257 <key>CFBundlePackageType</key>
258 <string>APPL</string>
259 <key>CFBundleShortVersionString</key>
260 <string>rel_1_6_0_7</string>
261 <key>CFBundleVersion</key>
262 <string>rel_1_6_0_7.rel_1_6_0_7</string>
263 <key>NSAppleScriptEnabled</key>
265 <key>CFBundleTypeIconFile</key>
266 <string>Evergreen.icns</string>
271 <listitem>Download and install an appropriate Mac OS package of
272 XULRunner from the Mozilla website (see above for
273 recommendations).</listitem>
275 <para>Make a copy of the folder
276 <filename class="directory">/Library/Frameworks/XUL.Framework</filename>
277 inside your APP file. It should look something like this:</para>
279 <prompt>* Evergreen.app/</prompt>
280 <prompt>__* Contents/</prompt>
281 <prompt>____* Frameworks/</prompt>
282 <prompt>______* XUL.Framework/</prompt>
283 <prompt>______* Versions/</prompt>
284 <prompt>________* Current -> 1.9.1.3 (symlink)</prompt>
285 <prompt>________* 1.9.1.3/</prompt>
286 <prompt>______* XUL -> Versions/Current/XUL</prompt>
287 <prompt>______* libxpcom.dylib -> Versions/Current/libxpcom.dylib</prompt>
288 <prompt>______* xulrunner-bin -> Versions/Current/xulrunner-bin</prompt>
292 <filename>XUL.Framework/Versions/Current/xulrunner</filename> into the
293 folder <filename class="directory">Evergreen.app/MacOS</filename>
294 (do not symlink; copy the file).</listitem>
296 <para>Make <filename>Evergreen.app/Resources</filename> the root
297 of your Evergreen application files like this:</para>
299 <prompt>* Evergreen.app/</prompt>
300 <prompt>__* Contents/</prompt>
301 <prompt>____* Resources/</prompt>
302 <prompt>______* BUILD_ID</prompt>
303 <prompt>______* application.ini</prompt>
304 <prompt>______* chrome/</prompt>
305 <prompt>______* components/</prompt>
306 <prompt>______* etc.</prompt>
309 <listitem>Put a Mac format icon file named <filename>Evergreen.icns</filename> in
310 <filename class="resources">Resources</filename>.</listitem>
314 <section xml:id="staffclientinstallation-installing-linux">
315 <title>Installing on Linux</title>
317 <title>Quick Upgrade of the Staff Client</title>
318 <para>A Linux Staff Client is automatically built on the server as part of the
319 normal <emphasis>make install</emphasis> process for Evergreen server-side
320 software. To upgrade the Staff Client on a remote Linux workstation with a new
321 version, just copy the directory tree containing the Staff Client from the
322 server to the remote workstation.</para>
323 <para>The following example assumes you already have an
324 <systemitem class="username">opensrf</systemitem> user account on both the
325 server and the remote workstation. Replace <literal>USER</literal>,
326 <literal>LINUX_MACHINE</literal>, and <literal>HOME_DIRECTORY</literal>
327 with appropriate values.</para>
328 <para>As the <systemitem class="username">opensrf</systemitem> user, execute the
329 following commands:</para>
331 <prompt># as the opensrf user</prompt>
332 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
333 <userinput>scp -r ./build USER@LINUX_MACHINE:~/HOME_DIRECTORY/</userinput>
335 <para>You must now test the newly copied Staff Client.
336 As the <systemitem class="username">opensrf</systemitem> user, log into the
337 remote workstation and execute the following command:</para>
339 <prompt># as the opensrf user</prompt>
340 <userinput>xulrunner ~/HOME_DIRECTORY/build/application.ini</userinput>
344 <title>Building the Staff Client on the Server</title>
346 <primary>staff client</primary>
347 <secondary>building on the server</secondary>
349 <para>A Linux Staff Client is automatically built on the server as part of the
350 normal <emphasis>make install</emphasis> process for Evergreen server-side
351 software. See <xref linkend="serversideinstallation-compile"/> for details of
352 the build process.</para>
353 <para>In order to install a compatible Staff Client on another Linux system, you
354 can copy the appropriate files from the Staff Client build directory on the
355 server to the new Linux system, or just manually build it on the new
356 system. Ensure that the BUILD_ID you choose on the new system matches the
357 BUILD_ID for each Staff Client you use on other systems.</para>
358 <para>If you wish to use a pre-packaged Windows version on some systems, you
359 may want to choose the BUILD_ID on both server and other versions to match that
360 of the Windows Staff Client. To determine which BUILD_ID used in an existing
361 Staff Client installation, execute the Staff Client and click
362 <guibutton>'About this Client'</guibutton>.</para>
363 <para>If you are allowed to make changes on the Evergreen server, another option
364 is to create a symbolic link. In order for a copy of the Staff Client and server
365 to work together, the BUILD_ID must match the name of the directory containing
366 the server components of the Staff Client, or the name of a symbolic link to
367 that directory.</para>
369 <prompt># as the root user</prompt>
370 <userinput>cd /openils/var/web/xul</userinput>
371 <userinput>ln -s SERVER_BUILD_ID/ CLIENT_BUILD_ID</userinput>
375 <title>Building the Staff Client on a client Machine</title>
376 <para>This section is directed toward end-users who wish to use Linux rather
377 than Windows for client machines, but have limited Linux experience. You can
378 build the Staff Client on a Linux system without installing the Evergreen Server
379 component. This is a relatively simple process compared to server installation,
380 but does require some command-line work. The following directions are for
381 building Staff Client version 1.2.1.4 on Kubuntu 7.10; you must modify them for
382 other distributions (the instructions should work as-is for Ubuntu or Ubuntu
386 <title>Prerequisites</title>
387 <para>Both <application>subversion</application> and
388 <application>xulrunner</application> are required to build the Staff
389 Client. As the <systemitem class="username">root</systemitem> user,
390 use <command>apt-get</command> to install packages for
391 <application>subversion</application> and
392 <application>xulrunner</application>. You can also use
393 <command>synaptic</command>, the graphical user interface for
394 <command>apt-get</command>. For <application>subversion</application>,
395 select the latest version; for <application>xulrunner</application>,
396 select version <emphasis>1.8.1.4-2ubuntu5</emphasis>.</para>
398 <prompt># as the root user</prompt>
399 <userinput>sudo apt-get install subversion</userinput>
400 <userinput>sudo apt-get install xulrunner</userinput>
404 <title>Download the Source Code</title>
407 <para>Determine which version is needed</para>
408 <para>For most end-users, a specific version is required
409 to communicate properly with the Evergreen server. Check
410 with your system admininstrator, IT person, or HelpDesk to
411 determine which Staff Client versions are
413 <para>Next, you need to determine which
414 <emphasis>tag</emphasis> to use when downloading the
415 source code. Tags are markers in the source code to create
416 a snapshot of the code as it existed at a certain time;
417 tags usually point to tested and stable code, or at least
418 a community-recognized release version.</para>
419 <para>To determine which tag to use, browse to
420 <ulink url="http://svn.open-ils.org/trac/ILS/browser">
421 http://svn.open-ils.org/trac/ILS/browser</ulink>.
422 Look in the <guilabel>Visit</guilabel> drop-down box; see
423 the list of <guilabel>Branches</guilabel> and, further
424 down, a list of <guilabel>Tags</guilabel>. You may have
425 to do some guesswork, but it is fairly straightforward to
426 determine which tag to use. If the server is version
427 1.6.1.2, you will want to use the tag that looks most
428 appropriate. For example, as you look through the tag
429 list, notice the tag named 'rel_1_6_1_2'. This is the tag
430 you need; make a note of it for the next step.</para>
433 <para>Download the Code</para>
435 <systemitem class="username">opensrf</systemitem>
436 user, open a terminal (command-line prompt) and navigate
437 to the directory in which you wish to download the Staff
438 Client. Use the following commands to download the proper
439 version of the source code by tag name:</para>
441 <prompt># as the opensrf user</prompt>
442 <userinput>cd /DOWNLOAD/DIRECTORY</userinput>
443 <userinput>svn co rel_1_6_1_2/</userinput>
445 <para>Remember to change "rel_1_6_1_2" to the appropriate
446 tag for your installation.</para>
451 <title>Build the Staff Client</title>
452 <para>In the following
453 example, navigate to the directory in which the source code was
454 downloaded, then navigate to the proper subdirectory and run the
455 "make" utility to actually build the Staff Client. Remember to
456 check with your system administrator about which Staff Client
457 BUILD_ID to use. The server checks the Staff Client BUILD_ID
458 against itself to determine whether or not a connecting client
459 is supported. For instance, for the PINES installation (version
460 1.2.1.4) the supported BUILD_ID is "rel_1_2_1_4". Modify the
461 following commands accordingly.</para>
462 <para>As the <systemitem class="username">opensrf</systemitem>
463 user, run the following commands to build the Staff Client:</para>
465 <prompt># as the opensrf user</prompt>
466 <userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput>
467 <userinput>cd Open-ILS/xul/staff_client</userinput>
468 <userinput>make STAFF_CLIENT_BUILD_ID='rel_1_6_1_2'</userinput>
472 <title>Run the Staff Client (from the command line)</title>
473 <para>As the <systemitem class="username">opensrf</systemitem>
474 user, navigate to the <filename class="directory">build/</filename>
475 subdirectory (not <filename class="directory">staff_client/</filename>)
476 and run the following command:</para>
478 <prompt># as the opensrf user</prompt>
479 <userinput>xulrunner application.ini</userinput>
483 <title>(OPTIONAL) Cleaning Up / Creating Shortcuts</title>
484 <para>The source code download included many files that are
485 needed to build the Staff Client but are not necessary to run
486 it. You may wish to remove them to save space or to create a
487 clean directory containing the built Staff Client that can then
488 be copied to other machines.</para>
489 <para>To create a clean "staging" directory in which to place
490 the finished Staff Client, execute the following commands
491 (remember to replace <literal>DESTINATION_DIRECTORY</literal>
492 with the appropriate path):</para>
494 <prompt># as the opensrf user</prompt>
495 <userinput>mkdir ~/DESTINATION_DIRECTORY</userinput>
496 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/</userinput>
497 <userinput>cp -r staff_client ~/DESTINATION_DIRECTORY</userinput>
499 <para>Finally, test the Staff Client to verify that all necessary
500 files were moved to the destination directory:</para>
502 <prompt># as the opensrf user</prompt>
503 <userinput>cd ~/DESTINATION_DIRECTORY/staff_client/build</userinput>
504 <userinput>xulrunner application.ini</userinput>
506 <para>If there were no problems, then finish the cleanup by removing the
507 original download directory and all subdirectories as shown:</para>
509 <prompt># as the opensrf user</prompt>
510 <userinput>rm -r -f ~/DOWNLOAD_DIRECTORY</userinput>
512 <para>You may wish to create a shortcut for the Staff Client:</para>
514 <guimenu>Desktop</guimenu>
515 <guimenuitem>StartMenu</guimenuitem>
516 <guimenuitem>K-Menu</guimenuitem>
518 <para>Use the command: <command>xulrunner
519 ~/DESTINATION_DIRECTORY/staff_client/build/application.ini</command>
520 as the target for the shortcut.</para>
525 <title>Using Wine to Install on Linux</title>
527 <primary>staff client</primary>
528 <secondary>using wine to install on Linux</secondary>
530 <para>The Linux application <application>Wine</application> is another alternative if you
531 wish to install the packaged Windows versions rather than building the Staff Client
532 manually. Wine is a Linux application that allows users to directly run Windows
533 executables, and is a simple way for casual Linux users to use the Staff Client. More
534 information about Wine can be found at
535 <ulink url="http://www.winehq.org/site/docs/wineusr-guide/getting-wine">
536 http://www.winehq.org/site/docs/wineusr-guide/getting-wine</ulink>.</para>
537 <para>As the <systemitem class="username">root</systemitem> user, use
538 <command>apt-get</command> to install the package for <application>Wine</application>.
539 You can also use <command>synaptic</command>, the graphical user interface.</para>
542 <para>Install wine:</para>
544 <prompt># as the root user</prompt>
545 <userinput>sudo apt-get install wine</userinput>
549 <para>Download Windows installer for the Staff Client</para>
550 <para>As the <systemitem class="username">opensrf</systemitem> user, run
551 the following commands to download the Windows installer for the proper
552 Staff Client from the <ulink url="http://open-ils.org">open-ils.org</ulink>
553 website and place it in a temporary directory:</para>
555 <prompt># as the opensrf user</prompt>
556 <userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput>
557 <userinput>wget http://open-ils.org/downloads/evergreen-setup-rel_version-number.exe</userinput>
561 <para>Run the downloaded Windows installer</para>
562 <para>As the <systemitem class="username">opensrf</systemitem> user,
563 navigate to the directory where you downloaded the Windows executable
564 file, then execute it:</para>
566 <prompt># as the opensrf user</prompt>
567 <userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput>
568 <userinput>wine evergreen-setup-rel_version-number.exe</userinput>
570 <para>If this step fails, you may need to configure Wine first to properly
571 emulate Windows XP. To do so, type "winecfg" from the command line; in the
572 "Applications" tab of the window that pops up, select "Default Settings"
573 and choose "Windows XP" from the drop-down menu, then click
574 <guibutton>'Apply'</guibutton>.</para>
577 <para>Launch the Staff Client</para>
578 <para>A new entry for the Staff Client should now appear somewhere in the
579 "All Applications" menu of your Linux desktop. Also, find a new desktop
580 shortcut for the Staff Client. To launch the Staff Client, visit the "All
581 Applications" menu, find a section similar to "Wine->Program
582 Files->Evergreen Staff Client->Evergreen Staff Client", or else launch the
583 Staff Client from the desktop shortcut.</para>
587 <simplesect xml:id="staffclientinstallation-workstationnames">
588 <title>Assigning Workstation Names</title>
590 <primary>staff client</primary>
591 <secondary>assigning workstation names</secondary>
593 <para>The Staff Client must be assigned to a library and given a unique name before it
594 will connect fully to the Evergreen server. The only restriction is that the workstation's
595 name must be unique within the assigned library. Make sure to select a workstation name
596 that you will remember later, and reflects the role, purpose, and/or location of a
597 particular computer. These names will come up later in statistical reporting, and can also
598 be handy when troubleshooting.</para>
601 <phrase>Example of unconfigured Staff Client</phrase>
604 <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-1.png" format="PNG" scalefit="1" width="70%"/>
607 <para>In order to assign a workstation a name, a user with appropriate permissions must
608 login to the Staff Client. In PINES, the local system administrator (OPSM) has the ability
609 to assign workstation names in their library system. Library managers (LIBM's) have the
610 ability within their branch. To assign a workstation a name, login to the system. You will
611 be prompted to assign the workstation a library and a name:</para>
614 <phrase>Example of configured Staff Client</phrase>
617 <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-2.png" format="PNG" scalefit="1" width="70%"/>
620 <para>Select the library this workstation physically operates in from the drop down
621 menu. In this example, we have selected "MGRL-MA". Type in a friendly name for the
622 workstation. In this example, we are installing the Staff Client on the director's
623 personal system, and have named it as such. Then click
624 <guibutton>'Register'</guibutton>.</para>
625 <para>Once you have registered your workstation
626 with the server, your screen will look like this:</para>
629 <phrase>Example of registered Staff Client</phrase>
632 <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-3.png" format="PNG" scalefit="1" width="70%"/>
635 <para>You are now ready to log into the Staff Client for the first time. Type in your
636 password again, and click <guibutton>'Login'</guibutton>.</para>
640 <title>Building the Staff Client</title>
642 <primary>staff client</primary>
643 <secondary>building</secondary>
645 <para>You can also manually build the Staff Client by using the <command>make</command>
646 utility in the Staff Client source directory (e.g., the directory
647 <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.0.x/Open-ILS/xul/staff_client</filename>
648 for the current Evergreen version). There are a number of possible options to manually
649 build special versions of the Staff Client on a Linux system. Following is a list of
650 environment variables that can be passed to <command>make</command> to influence the
651 manual build process:</para>
653 <title>Option STAFF_CLIENT_BUILD_ID</title>
654 <para>During the normal <emphasis>make install</emphasis> Evergreen server-side
655 software build process, the variable defaults to an automatically generated
656 date/time string, but you can also override the value of BUILD_ID.</para>
657 <para>The following commands could be used during the normal build process:</para>
659 <prompt># as the root user</prompt>
660 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
661 <userinput>make STAFF_CLIENT_BUILD_ID=1.6.1.2 install</userinput>
663 <para>The following commands will manually build the Staff Client using a different BUILD_ID.</para>
664 <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff
665 Client source directory, then set the variable and build the Staff Client:</para>
667 <prompt># as the opensrf user</prompt>
668 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
669 <userinput>make STAFF_CLIENT_BUILD_ID=my_test_id build</userinput>
673 <title>Option STAFF_CLIENT_VERSION</title>
674 <para>During the normal <emphasis>make install</emphasis> Evergreen server-side
675 software build process, the variable is pulled automatically from a README file
676 in the Evergreen source root. The variable defaults to
677 <emphasis>0trunk.revision</emphasis>, where the value of "revision" is
678 automatically generated. You can override the value of VERSION similarly to the
680 <para>The following commands could be used during the normal build process:</para>
682 <prompt># as the root user</prompt>
683 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
684 <userinput>make STAFF_CLIENT_VERSION=0mytest.200 install</userinput>
686 <para>The following commands will manually build the Staff Client using a different VERSION.</para>
687 <para>If you plan to make extensions update automatically, the VERSION needs to
688 conform to the format recommended in
689 <ulink url="https://developer.mozilla.org/en/Toolkit_version_format">
690 Toolkit Version Format</ulink> and newer versions need to be "higher" than older
692 <para>As the <systemitem class="username">opensrf</systemitem> user, change
693 directory to the Staff Client source directory, then set the variable and build
694 the Staff Client:</para>
696 <prompt># as the opensrf user</prompt>
697 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
698 <userinput>make STAFF_CLIENT_VERSION=0mytest.200 build</userinput>
702 <title>Option STAFF_CLIENT_STAMP_ID variable</title>
703 <para>During the normal <emphasis>make install</emphasis> Evergreen server-side software
704 build process, this variable is generated from STAFF_CLIENT_VERSION. You can override the
705 value of STAMP_ID similarly to the BUILD_ID.</para>
706 <para>The following commands could be used during the normal build process:</para>
708 <prompt># as the root user</prompt>
709 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
710 <userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp install</userinput>
712 <para>The following commands will manually build the Staff Client using a
713 different STAMP_ID.</para>
714 <para>It is possible to have multiple versions of the
715 Staff Client by specifying a different STAMP_ID for each, possibly for different
716 uses or client-side customizations.</para>
717 <para>As the <systemitem class="username">opensrf</systemitem>
718 user, change directory to the Staff Client source directory, then set the variable and
719 build the Staff Client:</para>
721 <prompt># as the opensrf user</prompt>
722 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
723 <userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp build</userinput>
728 <title>Advanced Build Options</title>
730 <primary>staff client</primary>
731 <secondary>building</secondary>
732 <tertiary>advanced build options</tertiary>
734 <para>In addition to the basic options listed above, there are a number of advanced options for
735 building the Staff Client. Most are target names for the <command>make</command> utility and
736 require that you build the Staff Client from its source directory. See the following table for a
737 list of possible <command>make</command> target keywords:</para>
739 <title>Keywords Targets for "make" Command</title>
740 <tgroup align="left" cols="2" colsep="1" rowsep="1">
741 <colspec colnum="1" colwidth="1.0*"/>
742 <colspec colnum="2" colwidth="3.0*"/>
745 <entry>Keyword</entry>
746 <entry>Description</entry>
751 <entry>clients</entry>
752 <entry>Runs "make win-client", "make linux-client", and "make
753 generic-client" individually</entry>
756 <entry>client_dir</entry>
757 <entry>Builds a client directory from the build directory, without
758 doing a rebuild. The same as "copy everything but
762 <entry>client_app</entry>
763 <entry>Prerequisite "client_dir"; removes "install.rdf" from
764 client directory so an APP bundle can't be installed as an
768 <entry>client_ext</entry>
769 <entry>Prerequisite "client_dir"; remove "application.ini",
770 "autoupdate.js", "standalone_xul_app.js" from client directory so
771 an extension won't break Firefox</entry>
774 <entry>extension</entry>
775 <entry>Prerequisite "client_ext"; rewritten to use "client_ext"</entry>
778 <entry>generic-client</entry>
779 <entry>Prerequisite "client_app"; makes an XPI file suitable for
780 use with "xulrunner --install-app""</entry>
783 <entry>win-xulrunner</entry>
784 <entry>Prerequisite "client_app"; adds Windows xulrunner to client build</entry>
787 <entry>linux-xulrunner</entry>
788 <entry>Prerequisite "client_app"; adds Linux xulrunner to client build</entry>
791 <entry>win-client</entry>
792 <entry>Prerequisite "win-xulrunner"; builds "setup exe" (requires
793 that "nsis" package be installed, will add options for automatic
794 update if configured and developer options if client build was a
795 "make devbuild")</entry>
798 <entry>linux-client</entry>
799 <entry>Prerequisite "linux_xulrunner"; builds a "tar.bz2" bundle
800 of the Linux client</entry>
803 <entry>[generic-|win-|linux-|extension-]updates[-client]</entry>
804 <entry>Calls external/make_updates.sh to build full and partial
805 updates generic/win/linux/extension prefix limit to that
806 distribution; Adding <option>-client</option> builds clients and
807 copies them to a subdirectory of the
808 <filename class="directory">updates</filename> directory as well;
809 <option>extension-updates-client</option> doesn't exist.</entry>
814 <para>Descriptions of other special build options follow:</para>
817 <para>Developer Build</para>
818 <para>You can create a so-called <emphasis>developer build</emphasis> of the Staff
819 Client by substituting <option>devbuild</option> for <option>build</option> when
820 running <command>make</command>. The build will contain an extra configuration
821 file that enables some developer options.</para>
822 <para>As the <systemitem class="username">opensrf</systemitem> user, run
823 <command>make</command> from the Staff Client source directory:</para>
825 <prompt># as the opensrf user</prompt>
826 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
827 <userinput>make devbuild</userinput>
831 <para>Compressed Javascript</para>
832 <para>You can execute the Google <systemitem class="resource">Closure
833 Compiler</systemitem> utility to automatically review and compress Javascript code
834 after the build process completes, by substituting
835 <option>compress-javascript</option> for "build" when running
836 <command>make</command>. For more information see
837 <ulink url="http://code.google.com/closure/compiler/">Google Closure Compiler</ulink>.</para>
838 <para>As the <systemitem class="username">opensrf</systemitem> user, run the
839 following commands from the Staff Client source directory:</para>
841 <prompt># as the opensrf user</prompt>
842 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
843 <userinput>make compress-javascript</userinput>
845 <para>You can also combine Javascript review and compression, and also perform a
846 <emphasis>developer build</emphasis>.</para>
847 <para>As the <systemitem class="username">opensrf</systemitem> user, run the
848 following commands from the Staff Client source directory:</para>
849 <note>In the following <command>make</command> below, the order of options is
852 <prompt># as the opensrf user</prompt>
853 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
854 <userinput>make devbuild compress-javascript</userinput>
858 <para>Automatic Update Host</para>
859 <para>The host used to check for automatic Staff Client updates can be overridden
860 by specifying the <option>AUTOUPDATE_HOST</option> option. The following commands
861 could have been used during the normal build process:</para>
863 <prompt># as the root user</prompt>
864 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
865 <userinput>make AUTOUPDATE_HOST=localhost install</userinput>
867 <para>You can manually set <option>AUTOUPDATE_HOST</option> to set up automatic
868 update checking. The following commands will manually build the Staff Client using
869 a different <option>AUTOUPDATE_HOST</option>.</para>
870 <para>As the <systemitem class="username">opensrf</systemitem> user, change
871 directory to the Staff Client source directory, then set the variable and build
872 the Staff Client:</para>
874 <prompt># as the opensrf user</prompt>
875 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
876 <userinput>make AUTOUPDATE_HOST=localhost build</userinput>
878 <para>For more information on Automatic Updates, see
879 <xref linkend="staffclientinstallation-autoupdate"/>.</para>
884 <title>Installing and Activating a Manually Built Staff Client</title>
885 <para>The Staff Client is automatically built, installed and activated as part of the normal
886 <command>make <option>install</option></command> process for Evergreen server-side
887 software. However, if you manually build the Staff Client, then you need to take additional steps
888 to properly install and activate it. You also have the option of installing the Staff Client on
889 the same machine it was built on, or on a different machine.</para>
890 <para>Assuming you have already built the Staff Client, and that your installation is in the
891 directory <filename class="directory">/openils/var/web/xul</filename>, as the
892 <systemitem class="username">opensrf</systemitem> user, change directory to the
893 Staff Client source directory, then execute the following commands:</para>
895 <prompt># as the opensrf user</prompt>
896 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
897 <userinput>mkdir -p "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput>
898 <userinput>cp -R build/server "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput>
902 <title>Packaging the Staff Client</title>
903 <para>Once the Staff Client has been built, you can create several forms of client packages by
904 using some targetted <command>make</command> commands in the Staff Client source directory.</para>
907 <para>Packaging a Generic Client</para>
908 <para>This build creates a Staff Client packaged as an XPI file to use with
909 <application>xulrunner</application>. It requires that you already have the
910 <systemitem>zip</systemitem> utility installed on your system. It will create the
911 output file <filename>evergreen_staff_client.xpi</filename>, suitable for use with
912 the <application>xulrunner</application> parameter
913 <option>--install-app</option>>.</para>
914 <para>As the <systemitem class="username">opensrf</systemitem> user, change
915 directory to the Staff Client source directory, then execute the following
918 <prompt># as the opensrf user</prompt>
919 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
920 <userinput>make generic-client</userinput>
924 <para>Packaging a Windows Client</para>
925 <para>This build creates a Staff Client packaged as a Windows executable. It
926 requires that you already have the "unzip" utility installed on your system. It
927 also requires that you install <ulink url="http://nsis.sourceforge.net/">NSIS
928 (Nullsoft Scriptable Install System)</ulink>, a professional open source utility
929 package used to create Windows installers (the "makensis" utility is installed as
930 part of the "nsis" package). We recommend using Version 2.45 or later. This build
931 will create the output file "evergreen_staff_client_setup.exe".</para>
932 <para>If you wish for the Staff Client to have a link icon/tray icon by default,
933 you may wish to provide a pre-modified <application>xulrunner-stub.exe</application>.
934 Place it in the Staff Client source directory and <command>make</command> will
935 automatically use it instead of the one that comes with the downloaded
936 <application>XULRunner</application> release. The version of
937 <application>xulrunner-stub.exe</application> need not match exactly.</para>
938 <para>You can also use a tool such as
939 <ulink url="http://www.angusj.com/resourcehacker/">Resource Hacker</ulink> to
940 embed icons. Resource Hacker is an open-source utility used to view, modify,
941 rename, add, delete and extract resources in 32bit Windows executables.
942 See the following table for some useful icon ID strings:</para>
944 <title>Useful icon ID strings</title>
945 <tgroup align="left" cols="2" colsep="1" rowsep="1">
946 <colspec colnum="1" colwidth="1.0*"/>
947 <colspec colnum="2" colwidth="1.0*"/>
950 <entry>IDI_APPICON</entry>
951 <entry>Tray icon</entry>
955 <entry>Default window icon</entry>
960 <para>As the <systemitem class="username">opensrf</systemitem> user, change
961 directory to the Staff Client source directory, then execute the following
964 <prompt># as the opensrf user</prompt>
965 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
966 <userinput>make win-client</userinput>
970 <para>Packaging a Linux Client</para>
971 <para>This build creates a Staff Client package for Linux as a "tar.bz2" file with
972 <application>XULRunner</application> already bundled with it. It creates the
973 output file "evergreen_staff_client.tar.bz2".</para>
974 <para>As the <systemitem class="username">opensrf</systemitem> user, change
975 directory to the Staff Client source directory, then execute the following
978 <prompt># as the opensrf user</prompt>
979 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
980 <userinput>make linux-client</userinput>
984 <para>Packaging a Firefox Extension</para>
985 <para>This build requires that you already have the <systemitem>zip</systemitem>
986 utility installed on your system. It creates a Staff Client packaged as a Firefox
987 extension and creates the output file <filename>evergreen.xpi</filename>.</para>
988 <para>As the <systemitem class="username">opensrf</systemitem> user, change
989 directory to the Staff Client source directory, then execute the following
992 <prompt># as the opensrf user</prompt>
993 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
994 <userinput>make extension</userinput>
999 <section xml:id="staffclientinstallation-autoupdate">
1000 <title>Staff Client Automatic Updates</title>
1002 <primary>staff client</primary>
1003 <secondary>automatic updates</secondary>
1005 <para>It is possible to set up support for automatic Staff Client updates, either during the
1006 normal Evergreen server-side build process, or by manually building the Staff Client with certain
1007 special options.</para>
1009 <para>Automatic update server certificate requirements are more strict than normal
1010 server requirements. Firefox and <application>XULRunner</application> will both ignore
1011 any automatic update server that is not validated by a trusted certificate authority.
1012 Servers with exceptions added to force the Staff Client to accept them
1013 <emphasis>WILL NOT WORK</emphasis>.</para>
1014 <para>In addition, automatic updates have special requirements for the file
1015 <filename>update.rdf</filename>:</para>
1017 <listitem>It must be served from an SSL server, or</listitem>
1018 <listitem>It must be signed with the
1019 <ulink url="https://developer.mozilla.org/en/McCoy">McCoy</ulink> tool.</listitem>
1021 <para>You can pre-install the signing key into the file <filename>install.rdf</filename>
1022 directly, or install it into a copy as <filename>install.mccoy.rdf</filename>. If the
1023 latter exists it will be copied into the build instead of the original file
1024 <filename>install.rdf</filename>.</para>
1027 <title>Autoupdate Host</title>
1028 <para>The name of the automatic update host can be provided in either of two ways:</para>
1030 <listitem>At configuration time for the normal build of the Evergreen server-side
1031 software, or</listitem>
1032 <listitem>During a manual Staff Client build process.</listitem>
1037 <para>At configuration time for the normal build of Evergreen server-side
1039 <para>This must be done when the Evergreen server-side software is first
1040 configured (see <xref linkend="serversideinstallation-configure"/>). As
1041 the <systemitem class="username">opensrf</systemitem> user, use the
1042 utility "configure" as shown:</para>
1044 <prompt># as the opensrf user</prompt>
1045 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
1046 <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf --with-updateshost=hostname</userinput>
1047 <userinput>make</userinput>
1051 <para>During a manual Staff Client build process</para>
1052 <para>You will used the variable AUTOUPDATE_HOST=hostname (see above).
1053 If you specify just a hostname (such as
1054 <systemitem class="domainname">example.com</systemitem>) then
1055 the URL will be a secure URL (such as
1056 <systemitem class="domainname">https://example.com</systemitem>.
1057 If you wish to use a non-HTTPS URL then prefix the hostname with
1058 <systemitem class="domainname">http://</systemitem> (such as
1059 <systemitem class="domainname">http://example.com</systemitem>).</para>
1060 <para>If neither option is used then, by default, the Staff Client will
1061 not include the automatic update preferences.</para>
1066 <title>Building Updates</title>
1068 <primary>staff client</primary>
1069 <secondary>automatic updates</secondary>
1070 <tertiary>building</tertiary>
1072 <para>Similar to building clients, the targets <option>generic-updates</option>,
1073 <option>win-updates</option>, <option>linux-updates</option>, and
1074 <option>extension-updates</option> can be used individually with <command>make</command>
1075 to build the update files for the Staff Client. To build all the targets at once, simply
1076 use the target <option>updates</option>.</para>
1077 <para>A full update will be built for each specified target (or for all if you use the
1078 target <option>updates</option>). For all but extensions any previous full updates
1079 (archived by default in the directory
1080 <filename class="directory">/openils/var/updates/archives</filename>) will be used to make partial
1081 updates. Partial updates tend to be much smaller and will thus download more quickly, but
1082 if something goes wrong with a partial update the full update will be used as a
1083 fallback. Extensions do not currentlysupport partial updates.</para>
1084 <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to
1085 the Staff Client source directory, then execute the following commands:</para>
1087 <prompt># as the opensrf user</prompt>
1088 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
1090 <para>Command to build all updates at once:</para>
1092 <prompt># as the opensrf user</prompt>
1093 <userinput>make updates</userinput>
1095 <para>commands to build updates individually:</para>
1097 <prompt># as the opensrf user</prompt>
1098 <userinput>make generic-updates</userinput>
1099 <userinput>make win-updates</userinput>
1100 <userinput>make linux-updates</userinput>
1101 <userinput>make extension-updates</userinput>
1105 <title>Building updates with clients</title>
1107 <primary>staff client</primary>
1108 <secondary>automatic updates</secondary>
1109 <tertiary>building with clients</tertiary>
1111 <para>To save time and effort you can build updates and manual download clients at the
1112 same time by adding <option>-client</option> to each target name. For instance, you can
1113 specify <option>win-updates-client</option>. You can also specify
1114 <option>updates-client</option> to build all the targets at once. This does not work for
1115 <option>extension-updates</option>.</para>
1116 <para>The clients will be installed alongside the updates and listed on the
1117 <filename>manualupdate.html</filename> page, rather than left in the Staff Client
1119 <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to
1120 the Staff Client source directory, then execute the following commands:</para>
1122 <prompt># as the opensrf user</prompt>
1123 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
1125 <para>Command to build all updates at once:</para>
1127 <prompt># as the opensrf user</prompt>
1128 <userinput>make updates-client</userinput>
1130 <para>Command to build updates individually:</para>
1132 <prompt># as the opensrf user</prompt>
1133 <userinput>make generic-updates-client</userinput>
1134 <userinput>make win-updates-client</userinput>
1135 <userinput>make linux-updates-client</userinput>
1139 <title>Activating the Update Server</title>
1141 <primary>staff client</primary>
1142 <secondary>automatic updates</secondary>
1143 <tertiary>activating the update server</tertiary>
1145 <para>This section reviews scripts associated with the update server, and requires some
1146 final adjustments to file permissions.</para>
1147 <para>The Apache example configuration creates an "updates" directory that, by default,
1148 points to the directory <filename class="directory">/openils/var/updates/pub</filename>.
1149 This directory contains one HTML file and several specially-named script files.</para>
1150 <para>The <filename>updatedetails.html</filename> file is the fallback web page for the
1151 update details. The <filename>check</filename> script is used for
1152 <application>XULRunner</application> updates. The <filename>update.rdf</filename> script
1153 is used for extension updates. The <filename>manualupdate.html</filename> file checks for
1154 clients to provide download links when automatic updates have failed and uses the download
1155 script to force a download of the generic client XPI (compared to Firefox trying to
1156 install it as an extension).</para>
1157 <para>The following scripts should be marked as executable: <filename>check</filename>,
1158 <filename>download</filename>, <filename>manualupdate.html</filename>,
1159 <filename>update.rdf</filename>. Execute the following commands:</para>
1161 <prompt># as the root user</prompt>
1162 <userinput>cd /openils/var/updates/pub</userinput>
1163 <userinput>chmod +x check download manualupdate.html update.rdf</userinput>
1168 <title>Other tips</title>
1170 <title>Multiple workstations on one install</title>
1171 <para>Multiple workstation registrations for the same server can be accomplished with a
1172 single Staff Client install by using multiple profiles. When running
1173 <application>XULRunner</application> you can specify the option "-profilemanager" or "-P"
1174 (uppercase "P") to force the Profile Manager to start. Unchecking the "Don't ask at
1175 startup" option will make this the default.</para>
1176 <para>Once you have opened the Profile Manager you can create additional profiles, one for
1177 each workstation you wish to register. You may need to install SSL exceptions for each
1179 <para>When building targets <option>win-client</option>,
1180 <option>win-updates-client</option>, or <option>updates-client</option>, you can specify
1181 <option>NSIS_EXTRAOPTS=-DPROFILES</option> to add an <guimenuitem>Evergreen Staff Client
1182 Profile Manager</guimenuitem> option to the start menu.</para>
1183 <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to
1184 the Staff Client source directory, then execute the following commands:</para>
1186 <prompt># as the opensrf user</prompt>
1187 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
1188 <userinput>make NSIS_EXTRAOPTS=-DPROFILES win-client</userinput>
1192 <title> Multiple Staff Clients</title>
1193 <para>This may be confusing if you are not careful, but you can log in to multiple
1194 Evergreen servers at the same time, or a single Evergreen server multiple times. In either
1195 case you will need to create an additional profile for each additional server or
1196 workstation you want to log in as (see previous tip).</para>
1197 <para>Once you have created the profiles, run <application>XULRunner</application> with
1198 the option <option>-no-remote</option> (in addition to <option>-profilemanger</option> or
1199 <option>-P</option> if neeeded). Instead of <application>XULRunner</application> opening a
1200 new login window on your existing session it will start a new session instead, which can
1201 then be logged in to a different server or workstation ID.</para>
1206 <section xml:id="staffclientinstallation-running-staffclient">
1207 <title>Running the Staff Client</title>
1209 <primary>staff client</primary>
1210 <secondary>running</secondary>
1211 <tertiary>linux</tertiary>
1213 <para>Run the Staff Client on a Linux system by using the application
1214 <application>XULRunner</application> (installed automatically and by default with Firefox version 3.0
1215 and later on Ubuntu and Debian distributions).</para>
1216 <para>For example, if the source files for the Evergreen installation are in the directory
1217 <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2/</filename>, start the Staff
1218 Client as shown in the following example:</para>
1220 <prompt># as the opensrf user</prompt>
1221 <userinput>xulrunner /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client/build/application.ini</userinput>
1223 <simplesect xml:id="staffclientinstallation-proxy">
1224 <title>Running the Staff Client over an SSH Tunnel</title>
1226 <primary>staff client</primary>
1227 <secondary>running through an SSH tunnel</secondary>
1229 <para>The Staff Client can use an SSH tunnel as a SOCKS 5 proxy.</para>
1231 <title>Configuring a Proxy for the Staff Client</title>
1232 <para>There are several reasons for sending network traffic for the Staff Client through an SSH
1236 <para>Firewalls may prevent you from reaching the server. This may happen when you
1237 are connecting the Staff Client to a test server that should not be available
1238 generally, or it may be the result of network design priorities other than ease of
1242 <para>You may wish to improve security where Staff Client traffic may be
1243 susceptible to network eavesdropping. This is especially true when wireless is
1244 otherwise the best option for connecting a staff machine to the network.</para>
1249 <title>Setting Up an SSH Tunnel</title>
1250 <para>You will need a server that allows you to log in via SSH and has network access to
1251 the Evergreen server you want to reach. You will use your username and password for that
1252 <systemitem class="protocal">SSH</systemitem> server to set up a tunnel.</para>
1253 <para>For Windows users, one good solution is the open-source utility
1254 <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty/">PuTTY</ulink>, a free
1255 <systemitem class="protocal">telnet/SSH</systemitem> client. When setting up a PuTTY
1259 <phrase>Setting up an SSH tunnel in PuTTY</phrase>
1262 <imagedata fileref="../media/staffclientinstallation-proxy-putty.png" format="PNG" scalefit="1" width="70%"/>
1266 <listitem>Use the menu on the left to go to Connection > SSH > Tunnels.</listitem>
1267 <listitem>Enter ''9999'' in the "Source port".</listitem>
1268 <listitem>Choose "Dynamic". Do not enter anything in the Destination text entry box.</listitem>
1269 <listitem>Click <guibutton>'Add'</guibutton>; "D9999" will now appear in the "Forwarded
1270 ports" list.</listitem>
1271 <listitem>Use the menu on the left to go back to "Session", and enter the host name of the
1272 <systemitem class="protocal">SSH</systemitem> server.</listitem>
1273 <listitem>A window will open up so that you can enter your username and password. Once you
1274 are logged in, the tunnel is open.</listitem>
1276 <para>See <ulink url="http://inside.mines.edu/~gmurray/HowTo/sshNotes.html">How to set up
1277 <systemitem class="protocal">SSH</systemitem> (for the beginner)</ulink> for information on
1278 setting up <systemitem class="protocal">SSH</systemitem> for other client operating
1282 <title>Configuring the Staff Client to Use the <systemitem class="protocal">SSH</systemitem> Tunnel</title>
1283 <para>In order to tell the Staff Client that all traffic should be sent through the
1284 <systemitem class="protocal">SSH</systemitem> tunnel just configured, you must edit the
1285 file <filename>C:\Program Files\Evergreen Staff
1286 Client\greprefs\all.js</filename>. Search this file for the word
1287 <literal>socks</literal> to find the appropriate section for the following
1291 <phrase>The SOCKS section of "all.js" before changes</phrase>
1294 <imagedata fileref="../media/staffclientinstallation-proxy-socks-1.png" format="PNG" scalefit="1" width="70%"/>
1297 <para>Make the following changes:</para>
1299 <listitem>Change the value of <literal>network.proxy.socks</literal> from
1300 <literal>""</literal> to <literal>localhost</literal>.</listitem>
1301 <listitem>Change the value of <literal>network.proxy.socks_port</literal> from
1302 <literal>0</literal> to <literal>9999</literal>.</listitem>
1306 <phrase>The SOCKS section of "all.js" after changes</phrase>
1309 <imagedata fileref="../media/staffclientinstallation-proxy-socks-2.png" format="PNG" scalefit="1" width="70%"/>
1312 <para>If everything is working correctly, you should now be able to run the Staff Client and all
1313 its data will be sent encrypted through the <systemitem class="protocal">SSH</systemitem> tunnel
1314 you have just configured.</para>
projects / working / Evergreen.git / blob