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="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 <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 <title>Evergreen / <application>XULrunner</application> Dependencies</title>
158 <tgroup align="left" cols="2" colsep="1" rowsep="1">
159 <colspec colnum="1" colwidth="1.0*"/>
160 <colspec colnum="2" colwidth="3.0*"/>
163 <entry>Evergreen 1.6.x.x</entry>
164 <entry>XULrunner 1.9.x.x</entry>
167 <entry>Evergreen 1.4.x.x</entry>
168 <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry>
171 <entry>Evergreen 1.2.x.x</entry>
172 <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry>
177 <note>If you have issues removing previously installed
178 <application>XULrunner</application> versions see
179 <xref linkend="staffclientinstallation-remove-xulrunner"/>
180 for further information.</note>
181 <para>The Staff Client data from the directory
182 <filename class="directory">./staff_client/build</filename> must be placed
183 somewhere on the machine (e.g.
184 <filename class="directory">~/Desktop/Evergreen_Staff_Client</filename>).</para>
185 <para>Remember to call <application>XULrunner</application> with the full path to the
186 binary, followed by the install command and the path to the client data:</para>
188 <userinput>/Library/Frameworks/XUL.framework/xulrunner-bin --install-app ~/Desktop/Evergreen_Staff_Client</userinput>
190 <para>The command should exit quietly and will create the folder
191 <filename class="directory">/Applications/OpenILS</filename>,
192 containing a launcher named <application>open_ils_staff_client</application>.</para>
194 <simplesect xml:id="staffclientinstallation-remove-xulrunner">
195 <title>(OPTIONAL) Removing previously installed XULRunner versions</title>
197 <primary>XULRunner</primary>
198 <secondary>removing previous versions</secondary>
200 <para>If you already have a newer version of
201 <application>XULrunner</application> installed, per the release notes,
202 you will need to remove the entire directory
203 <filename class="directory">/Library/Frameworks/XUL.framework</filename>
204 before downgrading.</para>
205 <para>In addition, you may also need to remove the previous file
206 <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> .</para>
207 <para>If file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> does
208 not exist (possibly in newer <systemitem class="osname">Mac OS</systemitem>
209 releases), you need to flush the file <filename>receiptdb</filename>.</para>
210 <note>If you install a newer version of <application>XULrunner</application>
211 over a previous (older) install, the older install is not removed but the
212 symlinks are changed to the newer one.</note>
215 <title>(OPTIONAL) Flush Receiptdb file:</title>
216 <para>First, get the package identifier, then purge/forget the build that was
217 initially installed:</para>
219 <userinput>sudo pkgutil --pkgs > /tmp/pkgs.txt</userinput>
220 <userinput>sudo pkgutil --forget org.mozilla.xulrunner</userinput>
222 <note>It may not be necessary to edit the file
223 <filename>/Library/Receipts/InstallHistory.plist</filename> after deleting the
224 folder <filename class="directory">XUL.framework</filename>. See
225 <ulink url="http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html">
226 http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html</ulink>
227 for more information.</note>
230 <title>Creating an APP file: Staff Client and <application>XULrunner</application> Bundled</title>
231 <para>An APP file is basically a folder. Start with a folder stucture like this:</para>
233 <prompt>Evergreen.app</prompt>
234 <prompt>__Contents</prompt>
235 <prompt>____Frameworks</prompt>
236 <prompt>____Resources</prompt>
237 <prompt>____MacOS</prompt>
239 <para>Create an APP folder structure with the following commands:</para>
241 <userinput>mkdir -p Evergreen.app/Contents/Frameworks</userinput>
242 <userinput>mkdir -p Evergreen.app/Contents/Resources</userinput>
243 <userinput>mkdir -p Evergreen.app/Contents/MacOS</userinput>
247 <para>Create a new file in the folder
248 <filename class="directory">Evergreen.app/Contents/Info.plist</filename>
249 containing the following data (adjust for your version of
251 <programlisting language="xml"><![CDATA[
252 <?xml version="1.0" encoding="UTF-8"?>
253 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
254 <plist version="1.0">
256 <key>CFBundleExecutable</key>
257 <string>xulrunner</string>
258 <key>CFBundleGetInfoString</key>
259 <string>OpenILS open_ils_staff_client rel_1_6_1_2</string>
260 <key>CFBundleInfoDictionaryVersion</key>
262 <key>CFBundleName</key>
263 <string>Evergreen Staff Client</string>
264 <key>CFBundlePackageType</key>
265 <string>APPL</string>
266 <key>CFBundleShortVersionString</key>
267 <string>rel_1_6_1_2</string>
268 <key>CFBundleVersion</key>
269 <string>rel_1_6_1_2.rel_1_6_1_2</string>
270 <key>NSAppleScriptEnabled</key>
272 <key>CFBundleTypeIconFile</key>
273 <string>Evergreen.icns</string>
278 <listitem>Download and install an appropriate
279 <systemitem class="osname">Mac OS</systemitem> package of
280 <application>XULrunner</application> from the Mozilla website
281 <ulink url="https://developer.mozilla.org/en/xulrunner">
282 https://developer.mozilla.org/en/xulrunner</ulink> (see
283 <xref linkend="staffclientinstallation-table-1"/> for recommendations).</listitem>
285 <para>Make a copy of the folder
286 <filename class="directory">/Library/Frameworks/XUL.Framework</filename>
287 inside your APP file. It should look something like this:</para>
289 <prompt>Evergreen.app/</prompt>
290 <prompt>__Contents/</prompt>
291 <prompt>____Frameworks/</prompt>
292 <prompt>______XUL.Framework/</prompt>
293 <prompt>______Versions/</prompt>
294 <prompt>________Current -> 1.9.1.3 (symlink)</prompt>
295 <prompt>________1.9.1.3/</prompt>
296 <prompt>______XUL -> Versions/Current/XUL</prompt>
297 <prompt>______libxpcom.dylib -> Versions/Current/libxpcom.dylib</prompt>
298 <prompt>______xulrunner-bin -> Versions/Current/xulrunner-bin</prompt>
302 <filename>XUL.Framework/Versions/Current/xulrunner</filename> into the
303 folder <filename class="directory">Evergreen.app/MacOS</filename>
304 (do not symlink; copy the file).</listitem>
306 <para>Make <filename>Evergreen.app/Resources</filename> the root
307 of your Evergreen application files like this:</para>
309 <prompt>Evergreen.app/</prompt>
310 <prompt>__Contents/</prompt>
311 <prompt>____Resources/</prompt>
312 <prompt>______BUILD_ID</prompt>
313 <prompt>______application.ini</prompt>
314 <prompt>______chrome/</prompt>
315 <prompt>______components/</prompt>
316 <prompt>______etc.</prompt>
319 <listitem>Put a <systemitem class="osname">Mac</systemitem>
320 format icon file named <filename>Evergreen.icns</filename> in
321 <filename class="resources">Resources</filename>.</listitem>
325 <section xml:id="staffclientinstallation-installing-linux">
326 <title>Installing on Linux</title>
328 <title>Quick Upgrade of the Staff Client</title>
329 <para>A Linux Staff Client is automatically built on the server as part of the
330 normal <emphasis>make install</emphasis> process for Evergreen server-side
331 software. To upgrade the Staff Client on a remote Linux workstation with a new
332 version, just copy the directory tree containing the Staff Client from your
333 server to the remote workstation.</para>
334 <para>Execute the following commands, replacing <literal>USER</literal>,
335 <literal>WORKSTATION</literal>, and <literal>SOME_PATH</literal> with
336 appropriate values:</para>
338 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
339 <userinput>scp -r ./build USER@WORKSTATION:/SOME_PATH/</userinput>
341 <para>You should test the newly copied Staff Client on the remote workstation.
342 Log into the workstation and execute the following command:</para>
344 <userinput>xulrunner /SOME_PATH/build/application.ini</userinput>
348 <title>Building the Staff Client on the Server</title>
350 <primary>staff client</primary>
351 <secondary>building on the server</secondary>
353 <para>A Linux Staff Client is automatically built on the server as part of the
354 normal <emphasis>make install</emphasis> process for Evergreen server-side
355 software. See <xref linkend="serversideinstallation-compile"/> for details of
356 the build process.</para>
357 <para>In order to install a compatible Staff Client on another Linux system, you
358 can copy the appropriate files from the Staff Client build directory on your
359 server to the new Linux system. You could manually build the Staff Client on the
360 new system, but you must ensure that the <envar>BUILD_ID</envar> you chose on
361 the server matches the <envar>BUILD_ID</envar> for each Staff Client you use on
362 other systems.</para>
363 <para>If you wish to use a pre-packaged <systemitem class="osname">Windows</systemitem>
364 version on some systems, you may want to choose the <envar>BUILD_ID</envar> on
365 both server and other versions to match that of the
366 <systemitem class="osname">Windows</systemitem> Staff Client. To determine which
367 <envar>BUILD_ID</envar> was used for existing Staff Client installations,
368 execute each Staff Client and click the <guibutton>'About this Client'</guibutton>
370 <para>If you are allowed to make changes on the Evergreen server, another option
371 is to create a symbolic link. In order for a copy of the Staff Client and server
372 to work together, the <envar>BUILD_ID</envar> must match the name of the
373 directory containing the server components of the Staff Client, or the name of a
374 symbolic link to that directory. As the
375 <systemitem class="username">root</systemitem> user, make the changes as follows:</para>
377 <prompt># as the root user</prompt>
378 <userinput>cd /openils/var/web/xul</userinput>
379 <userinput>ln -s SERVER_BUILD_ID/ CLIENT_BUILD_ID</userinput>
383 <title>Building the Staff Client on a Client Machine</title>
384 <para>This section is directed toward end-users who wish to use Linux rather than
385 <systemitem class="osname">Windows</systemitem> for client machines, but have limited
386 Linux experience. You can build the Staff Client on a Linux system without installing the
387 Evergreen Server component. This is a relatively simple process compared to server
388 installation, but does require some command-line work. The following instructions are
389 for building Staff Client version 1.2.1.4 on
390 <systemitem class="osname">Kubuntu 7.10</systemitem>; modify them as needed for
391 other distributions (the instructions should work as-is for
392 <systemitem class="osname">Ubuntu</systemitem> or
393 <systemitem class="osname">Ubuntu</systemitem> derivatives).</para>
396 <title>Prerequisites</title>
397 <para>Both <application>subversion</application> and
398 <application>XULrunner</application> are required to build the Staff
399 Client. As the <systemitem class="username">root</systemitem> user,
400 use <command>apt-get</command> to install packages for
401 <application>subversion</application> and
402 <application>XULrunner</application>. You can also use
403 <command>synaptic</command>, the graphical user interface for
404 <command>apt-get</command>. For <application>subversion</application>,
405 select the latest version; for <application>XULrunner</application>,
406 select version <emphasis>1.8.1.4-2ubuntu5</emphasis>.</para>
408 <prompt># as the root user</prompt>
409 <userinput>sudo apt-get install subversion</userinput>
410 <userinput>sudo apt-get install xulrunner</userinput>
414 <title>Download the Source Code</title>
417 <para>Determine which version is needed</para>
418 <para>For most end-users, a specific version is required
419 to communicate properly with the Evergreen server. Check
420 with your system admininstrator, IT person, or HelpDesk to
421 determine which Staff Client versions are
423 <para>Next, you need to determine which
424 <emphasis>tag</emphasis> to use when downloading the
425 source code. Tags are markers in the source code to create
426 a snapshot of the code as it existed at a certain time;
427 tags usually point to tested and stable code, or at least
428 a community-recognized release version.</para>
429 <para>To determine which tag to use, browse to
430 <ulink url="http://svn.open-ils.org/trac/ILS/browser">
431 http://svn.open-ils.org/trac/ILS/browser</ulink>.
432 Look in the <guilabel>Visit</guilabel> drop-down box; see
433 the list of <guilabel>Branches</guilabel> and, further
434 down, a list of <guilabel>Tags</guilabel>. You may have
435 to do some guesswork, but it is fairly straightforward to
436 determine which tag to use. If the server is version
437 1.6.1.2, you will want to use the tag that looks most
438 appropriate. For example, as you look through the tag
439 list, notice the tag named 'rel_1_6_1_2'. This is the tag
440 you need; make a note of it for the next step.</para>
443 <para>Download the Code</para>
445 <systemitem class="username">opensrf</systemitem>
446 user, open a terminal (command-line prompt) and navigate
447 to the directory in which you wish to download the Staff
448 Client. Use the following commands to download the proper
449 version of the source code by tag name:</para>
451 <prompt># as the opensrf user</prompt>
452 <userinput>cd /DOWNLOAD/DIRECTORY</userinput>
453 <userinput>svn co rel_1_6_1_2/</userinput>
455 <para>Remember to change "rel_1_6_1_2" to the appropriate
456 tag for your installation.</para>
461 <title>Build the Staff Client</title>
462 <para>In the following example, navigate to the directory in
463 which the source code was downloaded, then navigate to the
464 proper subdirectory and run the "make" utility to actually build
465 the Staff Client. Remember to check with your system
466 administrator about which Staff Client <envar>BUILD_ID</envar>
467 to use. The server checks the Staff Client
468 <envar>BUILD_ID</envar> against itself to determine whether or
469 not a connecting client is supported. For instance, for the
470 PINES installation (version 1.6.1.2) the supported
471 <envar>BUILD_ID</envar> is "rel_1_6_1_2". Modify the following
472 commands accordingly.</para>
473 <para>As the <systemitem class="username">opensrf</systemitem>
474 user, run the following commands to build the Staff Client:</para>
476 <prompt># as the opensrf user</prompt>
477 <userinput>wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz</userinput>
478 <userinput>tar xfz Evergreen-ILS-1.6.1.2.tar.gz</userinput>
479 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
480 <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>
481 <userinput>cd ./Open-ILS/xul/staff_client/</userinput>
482 <userinput>make STAFF_CLIENT_BUILD_ID='rel_1_6_1_2' install</userinput>
486 <title>Run the Staff Client</title>
487 <para>As the <systemitem class="username">opensrf</systemitem>
488 user, navigate to the <filename class="directory">build/</filename>
489 subdirectory and run the following command:</para>
491 <prompt># as the opensrf user</prompt>
492 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client/build</userinput>
493 <userinput>xulrunner application.ini</userinput>
497 <title>(OPTIONAL) Clean Up / Create Shortcuts</title>
498 <para>The source code download included many files that are
499 needed to build the Staff Client but are not necessary to run
500 it. You may wish to remove them to save space, or to create a
501 clean <literal>staging</literal> directory containing the
502 finished Staff Client that can then be copied to other
503 machines. To do this, execute the following commands (remember
504 to replace <literal>DOWNLOAD_DIRECTORY</literal> and
505 <literal>STAGING_DIRECTORY</literal> with the appropriate
508 <prompt># as the opensrf user</prompt>
509 <userinput>mkdir ~/STAGING_DIRECTORY</userinput>
510 <userinput>cd ~/DOWNLOAD_DIRECTORY/Open-ILS/xul/</userinput>
511 <userinput>cp -r staff_client ~/STAGING_DIRECTORY</userinput>
513 <para>Test the Staff Client to verify that all necessary files
514 were copied to the staging directory:</para>
516 <prompt># as the opensrf user</prompt>
517 <userinput>cd ~/STAGING_DIRECTORY/staff_client/build</userinput>
518 <userinput>xulrunner application.ini</userinput>
520 <para>If there were no problems, then finish the cleanup by
521 removing the original download directory as shown:</para>
523 <prompt># as the opensrf user</prompt>
524 <userinput>rm -r -f ~/DOWNLOAD_DIRECTORY</userinput>
526 <para>Finally, the command:</para>
528 <prompt># as the opensrf user</prompt>
529 <userinput>xulrunner ~/STAGING_DIRECTORY/staff_client/build/application.ini</userinput>
531 <para>will now run the Staff Client. You may wish to create a
532 shortcut for the Staff Client. To do so, use the previous
533 command as the target for the shortcut:
534 <menuchoice><guimenu>Desktop</guimenu><guimenuitem>StartMenu</guimenuitem><guimenuitem>K-Menu</guimenuitem></menuchoice></para>
539 <title>Using Wine to Install on Linux</title>
541 <primary>staff client</primary>
542 <secondary>using wine to install on Linux</secondary>
544 <para>The Linux application <application>Wine</application> is another
545 alternative if you wish to install the packaged
546 <systemitem class="osname">Windows</systemitem> versions rather than manually
547 building the Staff Client. <application>Wine</application> is a Linux
548 application that allows users to directly run
549 <systemitem class="osname">Windows</systemitem> executables, and is a simple
550 way for casual Linux users to use the Staff Client. You can find more information
551 about <application>Wine</application> at
552 <ulink url="http://www.winehq.org/site/docs/wineusr-guide/getting-wine">
553 http://www.winehq.org/site/docs/wineusr-guide/getting-wine</ulink>.</para>
554 <para>As the <systemitem class="username">root</systemitem> user, use
555 <command>apt-get</command> to install the package for <application>Wine</application>.
556 You can also use <command>synaptic</command>, the graphical user interface.</para>
559 <para>Install wine:</para>
561 <prompt># as the root user</prompt>
562 <userinput>sudo apt-get install wine</userinput>
566 <para>Visit the downloads section of the Evergreen website at
567 <ulink url="http://www.evergreen-ils.org/downloads.php">
568 http://www.evergreen-ils.org/downloads.php</ulink> and find the
569 <systemitem class="osname">Microsoft Windows</systemitem> Installer
570 that contains the desired version of the Staff Client. Download
571 the installer and place it in a temporary directory.</para>
574 <para>As the <systemitem class="username">opensrf</systemitem>
575 user, navigate to the temporary directory where you downloaded
576 the <systemitem class="osname">Windows</systemitem> installer
577 file, then execute it with the <application>wine</application>
578 application (remember to replace <literal>VERSION</literal> with
579 the release number of the Staff Client you downloaded):</para>
581 <prompt># as the opensrf user</prompt>
582 <userinput>cd /TEMP_DIRECTORY</userinput>
583 <userinput>wine evergreen-setup-rel_VERSION.exe</userinput>
585 <para>If this step fails, you may need to configure
586 <application>Wine</application> first to properly emulate
587 <systemitem class="osname">Windows XP</systemitem>. To do so,
588 type <command>winecfg</command> from the command line; in the
589 <literal>Applications</literal> tab of the window that pops up,
590 select <literal>Default Settings</literal> and choose
591 <literal>Windows XP</literal> from the drop-down menu, then
592 click <guibutton>'Apply'</guibutton>.</para>
594 <listitem><para>Launch the Staff Client</para> <para>A new entry for the
595 Staff Client should now appear somewhere in the <literal>All
596 Applications</literal> menu of your Linux desktop. You may also
597 find a new desktop shortcut for the Staff Client. To launch the
598 Staff Client, visit the your desktop's <literal>All
599 Applications</literal> menu and find the section similar to
600 <menuchoice><guimenu>Wine</guimenu><guimenuitem>Program Files</guimenuitem><guimenuitem>Evergreen Staff Client</guimenuitem><guimenuitem>Evergreen Staff Client</guimenuitem></menuchoice>
601 or else launch the Staff Client from the new desktop shortcut.</para></listitem>
607 <title>Building the Staff Client</title>
609 <primary>staff client</primary>
610 <secondary>building</secondary>
612 <para>You can also manually build the Staff Client by using the <command>make</command>
613 utility in the Staff Client source directory (e.g., the directory
614 <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</filename>
615 for the current Evergreen version). There are a number of possible options to manually
616 build special versions of the Staff Client on a Linux system. Following is a list of
617 variables that you can pass to <command>make</command> to influence the manual build
621 <envar>STAFF_CLIENT_BUILD_ID</envar>
623 <para>During the normal <emphasis>make install</emphasis> Evergreen server-side
624 software build process, the variable defaults to an automatically generated
625 date/time string, but you can also override the value of <envar>BUILD_ID</envar>.</para>
626 <para>You could use the following commands during the normal install process:</para>
628 <prompt># as the root user</prompt>
629 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
630 <userinput>make STAFF_CLIENT_BUILD_ID=1_6_1_2 install</userinput>
632 <para>You can also manually build the Staff Client in the Staff Client
633 source directory with a different <envar>BUILD_ID</envar>.</para>
634 <para>As the <systemitem class="username">opensrf</systemitem> user,
635 execute the following commands to build the Staff Client (remember to replace
636 <literal>NEW_VERSION</literal> with an appropriate value):</para>
638 <prompt># as the opensrf user</prompt>
639 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
640 <userinput>make STAFF_CLIENT_BUILD_ID=NEWVERSION build</userinput>
645 <envar>STAFF_CLIENT_VERSION</envar>
647 <para>During the normal <emphasis>make install</emphasis> Evergreen server-side
648 software build process, the variable is pulled automatically from a README file
649 in the Evergreen source root. The variable defaults to
650 <emphasis>0trunk.revision</emphasis>, where the value of "revision" is
651 automatically generated. You can override the value of <envar>VERSION</envar>
652 similarly to the <envar>BUILD_ID</envar>.</para>
653 <para>You could use the following commands during the normal install process:</para>
655 <prompt># as the root user</prompt>
656 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
657 <userinput>make STAFF_CLIENT_VERSION=0mytest.200 install</userinput>
659 <para>You can also manually build the Staff Client in the Staff Client
660 source directory with a different <envar>VERSION</envar>.</para>
661 <para>If you plan to make extensions update automatically, the
662 <envar>VERSION</envar> needs to conform to the format recommended in
663 <ulink url="https://developer.mozilla.org/en/Toolkit_version_format">
664 Toolkit Version Format</ulink> and newer versions need to be "higher" than older
666 <para>As the <systemitem class="username">opensrf</systemitem> user,
667 execute the following commands to build the Staff Client:</para>
669 <prompt># as the opensrf user</prompt>
670 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
671 <userinput>make STAFF_CLIENT_VERSION=0mytest.200 build</userinput>
676 <envar>STAFF_CLIENT_STAMP_ID</envar>
678 <para>During the normal <emphasis>make install</emphasis> Evergreen
679 server-side software build process, the variable is generated from
680 <envar>STAFF_CLIENT_VERSION</envar>. You may want to have multiple versions
681 of the Staff Client with different stamps, possibly for different uses or
682 client-side customizations. You can override the value of
683 <envar>STAMP_ID</envar> similarly to the <envar>BUILD_ID</envar>.</para>
684 <para>You could use the following commands during the normal install process:</para>
686 <prompt># as the root user</prompt>
687 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
688 <userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp install</userinput>
690 <para>You can also manually build the Staff Client in the Staff Client
691 source directory with a different <envar>STAMP_ID</envar>.</para>
692 <para>As the <systemitem class="username">opensrf</systemitem> user,
693 execute the following commands to build the Staff Client:</para>
695 <prompt># as the opensrf user</prompt>
696 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
697 <userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp build</userinput>
702 <title>Advanced Build Options</title>
704 <primary>staff client</primary>
705 <secondary>building</secondary>
706 <tertiary>advanced build options</tertiary>
708 <para>In addition to the basic options listed above, there are a number of advanced
709 options for building the Staff Client. Most are target names for the
710 <command>make</command> utility and require that you build the Staff Client from the
711 <literal>staff_client</literal> directory. See the following table for a list of
712 possible <command>make</command> target keywords:</para>
714 <title>Keywords Targets for "make" Command</title>
715 <tgroup align="left" cols="2" colsep="1" rowsep="1">
716 <colspec colnum="1" colwidth="1.0*"/>
717 <colspec colnum="2" colwidth="3.0*"/>
720 <entry>Keyword</entry>
721 <entry>Description</entry>
726 <entry>clients</entry>
727 <entry>Runs "make win-client", "make linux-client", and "make
728 generic-client" individually</entry>
731 <entry>client_dir</entry>
732 <entry>Builds a client directory from the build directory, without
733 doing a rebuild. The same as "copy everything but
737 <entry>client_app</entry>
738 <entry>Prerequisite "client_dir"; removes "install.rdf" from
739 client directory so an APP bundle can't be installed as an
743 <entry>client_ext</entry>
744 <entry>Prerequisite "client_dir"; remove "application.ini",
745 "autoupdate.js", "standalone_xul_app.js" from client directory so
746 an extension won't break Firefox</entry>
749 <entry>extension</entry>
750 <entry>Prerequisite "client_ext"; rewritten to use "client_ext"</entry>
753 <entry>generic-client</entry>
754 <entry>Prerequisite "client_app"; makes an XPI file suitable for
755 use with "xulrunner --install-app""</entry>
758 <entry>win-xulrunner</entry>
759 <entry>Prerequisite "client_app"; adds Windows xulrunner to client build</entry>
762 <entry>linux-xulrunner</entry>
763 <entry>Prerequisite "client_app"; adds Linux xulrunner to client build</entry>
766 <entry>win-client</entry>
767 <entry>Prerequisite "win-xulrunner"; builds "setup exe" (requires
768 that "nsis" package be installed, will add options for automatic
769 update if configured and developer options if client build was a
770 "make devbuild")</entry>
773 <entry>linux-client</entry>
774 <entry>Prerequisite "linux_xulrunner"; builds a "tar.bz2" bundle
775 of the Linux client</entry>
778 <entry>[generic-|win-|linux-|extension-]updates[-client]</entry>
779 <entry>Calls external/make_updates.sh to build full and partial
780 updates generic/win/linux/extension prefix limit to that
781 distribution; Adding <option>-client</option> builds clients and
782 copies them to a subdirectory of the
783 <filename class="directory">updates</filename> directory as well;
784 <option>extension-updates-client</option> doesn't exist.</entry>
789 <para>Following are descriptions of other special build options:</para>
791 <title>Developer Build</title>
792 <para>You can create a so-called <emphasis>developer build</emphasis>
793 of the Staff Client by substituting <option>devbuild</option> for
794 <option>build</option> when running <command>make</command> from the
795 <literal>staff_client</literal> directory. The build will contain an
796 extra configuration file that enables some developer options.</para>
797 <para>As the <systemitem class="username">opensrf</systemitem> user, run
798 the following commands from the Staff Client source directory:</para>
800 <prompt># as the opensrf user</prompt>
801 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
802 <userinput>make devbuild</userinput>
806 <title>Compressed Javascript</title>
807 <para>You can execute the Google <systemitem class="resource">Closure Compiler</systemitem>
808 utility to automatically review and compress Javascript code after the build
809 process completes, by substituting <option>compress-javascript</option> for
810 <option>build</option> when running <command>make</command>.
811 For more information on the Google Closure Compiler, see
812 <ulink url="http://code.google.com/closure/compiler/">
813 http://code.google.com/closure/compiler</ulink>.</para>
814 <para>As the <systemitem class="username">opensrf</systemitem> user, run
815 the following commands from the Staff Client source directory:</para>
817 <prompt># as the opensrf user</prompt>
818 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
819 <userinput>make compress-javascript</userinput>
821 <para>You can also combine Javascript review and compression, and also perform a
822 <emphasis>developer build</emphasis>.</para>
823 <para>As the <systemitem class="username">opensrf</systemitem> user, run the
824 following commands from the Staff Client source directory:</para>
825 <note>In the following <command>make</command> below, the order of options is
828 <prompt># as the opensrf user</prompt>
829 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
830 <userinput>make devbuild compress-javascript</userinput>
833 <simplesect xml:id="staffclientinstallation-autoupdatehost">
834 <title>Automatic Update Host</title>
835 <para>You can override the host used to check for automatic Staff Client updates
836 by specifying the <option>AUTOUPDATE_HOST</option> option.</para>
837 <para>You could use the following commands during the normal install process:</para>
839 <prompt># as the root user</prompt>
840 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
841 <userinput>make AUTOUPDATE_HOST=localhost install</userinput>
843 <para>You can manually build the Staff Client in the Staff Client
844 source directory and set <option>AUTOUPDATE_HOST</option> to enable automatic
845 update checking.</para>
846 <para>As the <systemitem class="username">opensrf</systemitem> user,
847 execute the following commands to build the Staff Client:</para>
849 <prompt># as the opensrf user</prompt>
850 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
851 <userinput>make AUTOUPDATE_HOST=localhost build</userinput>
853 <para>For more information on Automatic Updates, see
854 <xref linkend="staffclientinstallation-autoupdate"/>.</para>
858 <title>Installing and Activating a Manually Built Staff Client</title>
859 <para>The Staff Client is automatically built, installed and activated as part of the
860 normal <command>make<option>install</option></command> process for Evergreen
861 server-side software. However, if you manually build the Staff Client from the
862 <literal>staff_client</literal> directory, then you need to take additional steps to
863 properly install and activate it. You also have the option of installing the Staff
864 Client on the same machine it was built on, or on a different machine.</para>
865 <para>Assuming you have already built the Staff Client, and that your installation is
866 in the directory <filename class="directory">/openils/var/web/xul</filename>, as the
867 <systemitem class="username">opensrf</systemitem> user execute the following
870 <prompt># as the opensrf user</prompt>
871 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
872 <userinput>mkdir -p "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput>
873 <userinput>cp -R build/server "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput>
877 <title>Packaging the Staff Client</title>
878 <para>Once you have built the Staff Client, you can create several forms of special client
879 packages by using a modified <command>make</command> command in the <literal>staff_client</literal>
882 <title>Packaging a Generic Client</title>
883 <para>This build creates a Staff Client packaged as an XPI file suitable for use with
884 the <option>--install-app</option> parameter of <application>XULrunner</application>.
885 It requires that you already have the <systemitem>zip</systemitem> utility
886 installed on your system.</para>
887 <para>As the <systemitem class="username">opensrf</systemitem> user, execute
888 the following commands:</para>
890 <prompt># as the opensrf user</prompt>
891 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
892 <userinput>make generic-client</userinput>
894 <para>The output file <filename>evergreen_staff_client.xpi</filename> will be created.</para>
897 <title>Packaging a <systemitem class="osname">Windows</systemitem> Client</title>
898 <para>This build creates a Staff Client packaged as a
899 <systemitem class="osname">Windows</systemitem> executable. It requires that
900 you already have the <application>unzip</application> utility installed on
901 your system. It also requires that you install
902 <ulink url="http://nsis.sourceforge.net/">NSIS (Nullsoft Scriptable Install System)</ulink>,
903 a professional open source utility package used to create
904 <systemitem class="osname">Windows</systemitem> installers (the
905 <application>"makensis"</application> utility is installed as part of the
906 <application>"nsis"</application> package). You should use Version 2.45 or
908 <para>If you wish for the Staff Client to have a link icon/tray icon by
909 default, you may wish to provide a pre-modified
910 <application>xulrunner-stub.exe</application>. Place it in the Staff Client
911 source directory and <command>make</command> will automatically use it instead
912 of the one that comes with the downloaded <application>XULrunner</application>
913 release. The version of <application>xulrunner-stub.exe</application> need not
914 match exactly.</para>
915 <para>You can also use a tool such as
916 <ulink url="http://www.angusj.com/resourcehacker/">Resource Hacker</ulink>
917 to embed icons. <application>Resource Hacker</application> is an open-source
918 utility used to modify resources within 32-bit
919 <systemitem class="osname">Windows</systemitem> executables.
920 Some useful icon ID strings include the following:</para>
922 <title>Useful icon ID strings</title>
923 <tgroup align="left" cols="2" colsep="1" rowsep="1">
924 <colspec colnum="1" colwidth="1.0*"/>
925 <colspec colnum="2" colwidth="1.0*"/>
928 <entry>IDI_APPICON</entry>
929 <entry>Tray icon</entry>
933 <entry>Default window icon</entry>
938 <para>As the <systemitem class="username">opensrf</systemitem> user
939 execute the following commands:</para>
941 <prompt># as the opensrf user</prompt>
942 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
943 <userinput>make win-client</userinput>
945 <para>The output file <filename>evergreen_staff_client_setup.exe</filename> will be created.</para>
948 <title>Packaging a Linux Client</title>
949 <para>This build creates a Staff Client packaged as a compressed
950 <literal>tar</literal> archive file with <application>XULrunner</application>
951 already bundled with it. It requires that you already have the
952 <application>bzip2</application> utility installed on your system.</para>
953 <para>As the <systemitem class="username">opensrf</systemitem> user,
954 execute the following commands:</para>
956 <prompt># as the opensrf user</prompt>
957 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
958 <userinput>make linux-client</userinput>
960 <para>The output file <filename>evergreen_staff_client.tar.bz2</filename> will be created.</para>
963 <title>Packaging a <application>Firefox</application> Extension</title>
964 <para>This build creates a Staff Client packaged as a <application>Firefox</application>
965 extension. It requires that you already have the <systemitem>zip</systemitem>
966 utility installed on your system.</para>
967 <para>As the <systemitem class="username">opensrf</systemitem> user,
968 execute the following commands:</para>
970 <prompt># as the opensrf user</prompt>
971 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
972 <userinput>make extension</userinput>
974 <para>The output file <filename>evergreen.xpi</filename> will be created.</para>
977 <section xml:id="staffclientinstallation-autoupdate">
978 <title>Staff Client Automatic Updates</title>
980 <primary>staff client</primary>
981 <secondary>automatic updates</secondary>
983 <para>It is possible to set up support for automatic Staff Client updates, either during
984 the normal Evergreen server-side build process, or by manually building the Staff Client
985 with certain special options.</para>
987 <para>Automatic update server certificate requirements are more strict than
988 normal server requirements. <application>Firefox</application> and
989 <application>XULrunner</application> will both ignore any automatic update
990 server that is not validated by a trusted certificate authority. Servers with
991 exceptions added to force the Staff Client to accept them <emphasis>WILL NOT
992 WORK</emphasis>.</para>
993 <para>In addition, automatic updates have special requirements for the file
994 <filename>update.rdf</filename>:</para>
996 <listitem>It must be served from an SSL server, or</listitem>
997 <listitem>It must be signed with the <ulink url="https://developer.mozilla.org/en/McCoy">
998 https://developer.mozilla.org/en/McCoy</ulink> tool.</listitem>
1000 <para>You can pre-install the signing key into the file
1001 <filename>install.rdf</filename> directly, or install it into a copy as
1002 <filename>install.mccoy.rdf</filename>. If the latter exists it will be copied
1003 into the build instead of the original file
1004 <filename>install.rdf</filename>.</para>
1007 <title>Autoupdate Host</title>
1008 <para>You can manually set the name of the automatic update host. If you do
1009 not set the name then, by default, the Staff Client will not include an
1010 automatic update preference. You can set the autoupdate host name as
1014 <para>At configuration time during the normal <emphasis>make install</emphasis>
1015 process for Evergreen server-side software.</para>
1016 <para>You can do this when you first configure the Evergreen server-side
1017 software (see <xref linkend="serversideinstallation-configure"/>).
1018 As the <systemitem class="username">opensrf</systemitem> user, execute
1019 the following commands:</para>
1021 <prompt># as the opensrf user</prompt>
1022 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
1023 <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf --with-updateshost=hostname</userinput>
1024 <userinput>make</userinput>
1028 <para>During a manual Staff Client build process.</para>
1029 <para>You can override the variable
1030 <envar>AUTOUPDATE_HOST=hostname</envar> and manually build the
1031 Staff Client from the <literal>staff_client</literal>
1032 directory (see <xref linkend="staffclientinstallation-autoupdatehost"/>
1033 for details). If you specify only a bare hostname (for example,
1034 <systemitem class="domainname">example.com</systemitem>) then
1035 the Staff Client will automatically use the secure URL
1036 <systemitem class="domainname">https://example.com</systemitem>.
1037 If you wish to use a non-https URL, then you must explicitly
1038 specify the full URL (for example,
1039 <systemitem class="domainname">http://example.com</systemitem>).</para>
1040 <para>As the <systemitem class="username">opensrf</systemitem> user,
1041 execute the following commands to build the Staff Client (remember to
1042 replace <literal>SOME_URL</literal> with an appropriate value)
1045 <prompt># as the opensrf user</prompt>
1046 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
1047 <userinput>make AUTOUPDATE_HOST=http://SOME_URL build</userinput>
1053 <title>Building Updates</title>
1055 <primary>staff client</primary>
1056 <secondary>automatic updates</secondary>
1057 <tertiary>building</tertiary>
1059 <para>Similar to building clients, you can use the targets
1060 <option>generic-updates</option>, <option>win-updates</option>,
1061 <option>linux-updates</option>, and <option>extension-updates</option>
1062 individually with <command>make</command> to build the update files for the
1063 Staff Client. To build all the targets at once, simply use the target
1064 <option>updates</option>.</para>
1065 <para>A full update will be built for each specified target (or for all if you
1066 use the target <option>updates</option>). For all but extensions any previous
1067 full updates (archived by default in the directory
1068 <filename class="directory">/openils/var/updates/archives</filename>) will be
1069 used to make partial updates. Partial updates tend to be much smaller and will
1070 thus download more quickly, but if something goes wrong with a partial update
1071 the full update will be used as a fallback. Extensions do not currently support
1072 partial updates.</para>
1073 <para>As the <systemitem class="username">opensrf</systemitem> user, change
1074 directory to the Staff Client source directory, then execute the following
1077 <prompt># as the opensrf user</prompt>
1078 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
1080 <para>Command to build all updates at once:</para>
1082 <prompt># as the opensrf user</prompt>
1083 <userinput>make updates</userinput>
1085 <para>commands to build updates individually:</para>
1087 <prompt># as the opensrf user</prompt>
1088 <userinput>make generic-updates</userinput>
1089 <userinput>make win-updates</userinput>
1090 <userinput>make linux-updates</userinput>
1091 <userinput>make extension-updates</userinput>
1095 <title>Building updates with clients</title>
1097 <primary>staff client</primary>
1098 <secondary>automatic updates</secondary>
1099 <tertiary>building with clients</tertiary>
1101 <para>To save time and effort you can build updates and manual download
1102 clients at the same time by adding the phrase <literal>"-client"</literal> to each
1103 target name (for example, you could specify <option>updates-client</option> to build
1104 all the targets at once, or you could specify <option>win-updates-client</option>
1105 to build updates individually). This process will not work for the option
1106 <option>extension-updates</option>.</para>
1107 <para>The clients will be installed alongside the updates and listed on the
1108 <filename>manualupdate.html</filename> page, instead of being left in the
1109 <literal>staff_client</literal> directory.</para>
1110 <para>As the <systemitem class="username">opensrf</systemitem> user, execute
1111 one of the following commands:</para>
1112 <para>To build all updates at once:</para>
1114 <prompt># as the opensrf user</prompt>
1115 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
1116 <userinput>make updates-client</userinput>
1118 <para>To build updates individually:</para>
1120 <prompt># as the opensrf user</prompt>
1121 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
1122 <userinput>make generic-updates-client</userinput>
1123 <userinput>make win-updates-client</userinput>
1124 <userinput>make linux-updates-client</userinput>
1128 <title>Activating the Update Server</title>
1130 <primary>staff client</primary>
1131 <secondary>automatic updates</secondary>
1132 <tertiary>activating the update server</tertiary>
1134 <para>This section reviews scripts associated with the update server, and
1135 requires some final adjustments to file permissions.</para>
1136 <para>The Apache example configuration creates an <literal>updates</literal>
1137 directory that, by default, points to the directory
1138 <filename class="directory">/openils/var/updates/pub</filename>. This
1139 directory contains one HTML file and several specially-named script files.</para>
1140 <para>The <filename>updatedetails.html</filename> file is the fallback web
1141 page for the update details. The <filename>check</filename> script is used for
1142 <application>XULrunner</application> updates. The
1143 <filename>update.rdf</filename> script is used for extension updates.
1144 The <filename>manualupdate.html</filename> file checks for clients to provide
1145 download links when automatic updates have failed and uses the download script
1146 to force a download of the generic client XPI (compared to
1147 <application>Firefox</application> trying to install it as an
1149 <para>To change the permissions for the scripts
1150 <filename>check</filename>, <filename>download</filename>,
1151 <filename>manualupdate.html</filename>, and
1152 <filename>update.rdf</filename>, as the root user execute the following
1155 <prompt># as the root user</prompt>
1156 <userinput>cd /openils/var/updates/pub</userinput>
1157 <userinput>chmod +x check download manualupdate.html update.rdf</userinput>
1162 <title>Other tips</title>
1163 <simplesect xml:id="staffclientinstallation-othertips">
1164 <title>Multiple workstations on one install</title>
1165 <para>Multiple workstation registrations for the same server can be accomplished
1166 with a single Staff Client install by using multiple profiles. When running
1167 <application>XULrunner</application> you can specify the option
1168 <literal>"-profilemanager"</literal> or <literal>"-P"</literal> (uppercase "P")
1169 to force the Profile Manager to start. Unchecking the <literal>"Don't ask at startup"</literal>
1170 option will make this the default.</para>
1171 <para>Once you have opened the Profile Manager you can create additional
1172 profiles, one for each workstation you wish to register. You may need to install
1173 SSL exceptions for each profile.</para>
1174 <para>When building any of the targets <option>win-client</option>,
1175 <option>win-updates-client</option>, or <option>updates-client</option>, you can
1176 specify <option>NSIS_EXTRAOPTS=-DPROFILES</option> to add an option
1177 <guimenuitem>"Evergreen Staff Client Profile Manager"</guimenuitem> to the
1179 <para>As the <systemitem class="username">opensrf</systemitem> user,
1180 execute the following commands:</para>
1182 <prompt># as the opensrf user</prompt>
1183 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
1184 <userinput>make NSIS_EXTRAOPTS=-DPROFILES win-client</userinput>
1188 <title> Multiple Staff Clients</title>
1189 <para>It may be confusing if you are not careful, but you can log in to
1190 multiple Evergreen servers at the same time, or a single Evergreen server
1191 multiple times. In either case you will need to create an additional profile for
1192 each additional server or workstation you want to log in as (see the previous
1193 tip in <xref linkend="staffclientinstallation-othertips"/>).</para>
1194 <para>Once you have created the profiles, run
1195 <application>XULrunner</application> with the option <option>-no-remote</option>
1196 (in addition to <option>"-profilemanger"</option> or <option>"-P"</option> if
1197 neeeded). Instead of <application>XULrunner</application> opening a new login
1198 window on your existing session it will start a new session instead, which can
1199 then be logged in to a different server or workstation ID.</para>
1203 <section xml:id="staffclientinstallation-running-staffclient">
1204 <title>Running the Staff Client</title>
1206 <primary>staff client</primary>
1207 <secondary>running</secondary>
1208 <tertiary>linux</tertiary>
1210 <para>You can run the Staff Client on a Linux system by using the
1211 <application>XULrunner</application> application (installed automatically and by default
1212 with <application>Firefox</application> <literal>Version 3.0</literal> and later on
1213 <systemitem class="osname">Ubuntu</systemitem> and
1214 <systemitem class="osname">Debian</systemitem> distributions).</para>
1215 <para>For example, if the source files for the Evergreen installation are in the directory
1216 <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2/</filename> you can start the
1217 Staff Client as shown in the following example:</para>
1219 <prompt># as the opensrf user</prompt>
1220 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client/build</userinput>
1221 <userinput>xulrunner application.ini</userinput>
1223 <section xml:id="staffclientinstallation-workstationnames">
1224 <title>Assigning Workstation Names</title>
1226 <primary>staff client</primary>
1227 <secondary>assigning workstation names</secondary>
1229 <para>The Staff Client must be assigned to a library and given a unique name before it
1230 will connect fully to the Evergreen server. The only restriction is that the workstation's
1231 name must be unique within the assigned library. Make sure to select a workstation name
1232 that you will remember later, and reflects the role, purpose, and/or location of a
1233 particular computer. These names will come up later in statistical reporting, and can also
1234 be handy when troubleshooting.</para>
1237 <phrase>Example of unconfigured Staff Client</phrase>
1240 <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-1.png" format="PNG" scalefit="1" width="70%"/>
1243 <para>In order to assign a workstation a name, a user with appropriate
1244 permissions must login to the Staff Client. In PINES, the local system
1245 administrator (OPSM) has the ability to assign workstation names in their
1246 library system. Library managers (LIBM's) have the ability within their
1247 branch. To assign a workstation a name, login to the system. You will be
1248 prompted to assign the workstation a library and a name:</para>
1251 <phrase>Example of configured Staff Client</phrase>
1254 <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-2.png" format="PNG" scalefit="1" width="70%"/>
1257 <para>Select the library this workstation physically operates in from the drop
1258 down menu. In this example, we have selected "MGRL-MA". Type in a friendly name
1259 for the workstation. In this example, we are installing the Staff Client on the
1260 director's personal system, and have named it as such. Then click
1261 <guibutton>'Register'</guibutton>.</para>
1262 <para>Once you have registered your workstation
1263 with the server, your screen will look like this:</para>
1266 <phrase>Example of registered Staff Client</phrase>
1269 <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-3.png" format="PNG" scalefit="1" width="70%"/>
1272 <para>You are now ready to log into the Staff Client for the first time. Type in
1273 your password again, and click <guibutton>'Login'</guibutton>.</para>
1275 <section xml:id="staffclientinstallation-proxy">
1276 <title>Running the Staff Client Over An <systemitem class="protocal">SSH</systemitem> Tunnel</title>
1278 <primary>staff client</primary>
1279 <secondary>running through an SSH tunnel</secondary>
1281 <para>The Staff Client can use an <systemitem class="protocal">SSH</systemitem>
1282 tunnel as a <systemitem class="protocal">SOCKS 5</systemitem> proxy.</para>
1284 <title>Configuring a Proxy for the Staff Client</title>
1285 <para>There are several reasons for sending network traffic for the Staff Client through
1286 an <systemitem class="protocal">SSH</systemitem> proxy:</para>
1289 <para>Firewalls may prevent you from reaching the server. This may happen when you
1290 are connecting the Staff Client to a test server that should not be available
1291 generally, or it may be the result of network design priorities other than ease of
1295 <para>You may wish to improve security where Staff Client traffic may be
1296 susceptible to network eavesdropping. This is especially true when wireless is
1297 otherwise the best option for connecting a staff machine to the network.</para>
1302 <title>Setting Up an <systemitem class="protocal">SSH</systemitem> Tunnel</title>
1303 <para>You will need a server that allows you to log in via <systemitem class="protocal">SSH</systemitem> and has network access to the Evergreen server
1304 you want to reach. You will use your username and password for that
1305 <systemitem class="protocal">SSH</systemitem> server to set up a tunnel.</para>
1306 <para>For <systemitem class="osname">Windows</systemitem> users, one good solution
1307 is the open-source utility
1308 <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty/">PuTTY</ulink>
1309 a free <systemitem class="protocal">telnet/SSH</systemitem> client. When setting
1310 up a <application>PuTTY</application> session:</para>
1313 <phrase>Setting up an <systemitem class="protocal">SSH</systemitem>
1314 tunnel in <application>PuTTY</application></phrase>
1317 <imagedata fileref="../media/staffclientinstallation-proxy-putty.png" format="PNG" scalefit="1" width="70%"/>
1321 <listitem>Use the menu on the left to go to Connection > SSH > Tunnels.</listitem>
1322 <listitem>Enter ''9999'' in the "Source port".</listitem>
1323 <listitem>Choose "Dynamic". Do not enter anything in the Destination text entry box.</listitem>
1324 <listitem>Click <guibutton>'Add'</guibutton>; "D9999" will now appear in the "Forwarded
1325 ports" list.</listitem>
1326 <listitem>Use the menu on the left to go back to "Session", and enter the host name of the
1327 <systemitem class="protocal">SSH</systemitem> server.</listitem>
1328 <listitem>A window will open up so that you can enter your username and password. Once you
1329 are logged in, the tunnel is open.</listitem>
1331 <para>See <ulink url="http://inside.mines.edu/~gmurray/HowTo/sshNotes.html">How to set up
1332 <systemitem class="protocal">SSH</systemitem> (for the beginner)</ulink> for information on
1333 setting up <systemitem class="protocal">SSH</systemitem> for other client operating
1337 <title>Configuring the Staff Client to Use the <systemitem class="protocal">SSH</systemitem> Tunnel</title>
1338 <para>In order to tell the Staff Client that all traffic should be sent through the
1339 <systemitem class="protocal">SSH</systemitem> tunnel just configured, you must edit the
1340 file <filename>C:\Program Files\Evergreen Staff Client\greprefs\all.js</filename>.
1341 Search this file for the word <literal>socks</literal> to find the appropriate section
1342 for the following changes.</para>
1345 <phrase>The SOCKS section of "all.js" before changes</phrase>
1348 <imagedata fileref="../media/staffclientinstallation-proxy-socks-1.png" format="PNG" scalefit="1" width="70%"/>
1351 <para>Make the following changes:</para>
1353 <listitem>Change the value of <literal>network.proxy.socks</literal> from
1354 <literal>""</literal> to <literal>localhost</literal>.</listitem>
1355 <listitem>Change the value of <literal>network.proxy.socks_port</literal> from
1356 <literal>0</literal> to <literal>9999</literal>.</listitem>
1360 <phrase>The SOCKS section of "all.js" after changes</phrase>
1363 <imagedata fileref="../media/staffclientinstallation-proxy-socks-2.png" format="PNG" scalefit="1" width="70%"/>
1366 <para>If everything is working correctly, you should now be able to run the Staff Client
1367 and all its data will be sent encrypted through the
1368 <systemitem class="protocal">SSH</systemitem> tunnel you have just configured.</para>
projects / working / Evergreen.git / blob