Add registering workstation warning regarding working locations provided by Jennifer...
[working/Evergreen.git] / 1.6 / admin / staffclientinstallation.xml
1 <?xml version="1.0" encoding="UTF-8"?>\r
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">\r
3         <info>\r
4                 <title>Installation of Evergreen Staff Client Software</title>\r
5                 <abstract>\r
6                         <para>This section describes installation of the Evergreen Staff Client software.</para>\r
7                 </abstract>\r
8         </info>\r
9         <section xml:id="staffclientinstallation-installing-staffclient">\r
10                 <title>Installing the Staff Client</title>\r
11                 <indexterm>\r
12                         <primary>staff client</primary>\r
13                         <secondary>installing</secondary>\r
14                 </indexterm>\r
15                 <section xml:id="staffclientinstallation-installing-prebuilt">\r
16                         <title>Installing a Pre-Built Staff Client</title>\r
17                         <para>A pre-built Staff Client is available for <systemitem class="osname">Windows</systemitem>,\r
18                         <systemitem class="osname">Mac</systemitem> or Linux systems. Installing the Staff Client in\r
19                         each of these environments is described in the following sections.</para>\r
20                         <section xml:id="staffclientinstallation-installing-windows">\r
21                                 <title>Installing on <systemitem class="osname">Windows</systemitem></title>\r
22                                 <indexterm>\r
23                                         <primary>staff client</primary>\r
24                                         <secondary>installing</secondary>\r
25                                         <tertiary>Windows</tertiary>\r
26                                 </indexterm>\r
27                                 <para>In this section we describe the process of installing the Staff Client on the\r
28                                 <systemitem class="osname">Microsoft Windows</systemitem> operating system.</para>\r
29                                 <para>Visit the downloads section of the Evergreen website at\r
30                                 <ulink url="http://www.evergreen-ils.org/downloads.php">http://www.evergreen-ils.org/downloads.php</ulink>\r
31                                 and find the standard <systemitem class="osname">Microsoft Windows</systemitem> Installer\r
32                                 that contains the current version of the Staff Client. Download the Installer, then run\r
33                                 it. A screen that looks similar to this should appear:</para>\r
34                                 <mediaobject>\r
35                                         <alt>\r
36                                                 <phrase>Running the Staff Client installer</phrase>\r
37                                         </alt>\r
38                                         <imageobject>\r
39                                                 <imagedata fileref="../media/staffclientinstallation-staffclient-1.png" format="PNG" scalefit="1" width="60%"/>\r
40                                         </imageobject>\r
41                                 </mediaobject>\r
42                                 <para>Click <guibutton>'Next'</guibutton> to continue through the guided install\r
43                                 process. The Install Wizard will ask you to agree to the end-user license, ask you where\r
44                                 to install the software, ask about where to place icons, and then will automatically\r
45                                 install the software on your workstation.</para>\r
46                                 <para>When you run the Staff Client for the first time, a screen similar to this should\r
47                                 appear:</para>\r
48                                 <mediaobject>\r
49                                         <alt>\r
50                                                 <phrase>Running the Staff Client for the first time</phrase>\r
51                                         </alt>\r
52                                         <imageobject>\r
53                                                 <imagedata fileref="../media/staffclientinstallation-staffclient-2.png" format="PNG" scalefit="1" width="60%"/>\r
54                                         </imageobject>\r
55                                 </mediaobject>\r
56                                 <para>First, add the name of your Evergreen server to the field \r
57                                 <emphasis role="bold">Hostname</emphasis> in the <emphasis role="bold">Server</emphasis>\r
58                                 section. For example, the PINES demo system is \r
59                                 <ulink url="http://demo.gapines.org">http://demo.gapines.org</ulink>. \r
60                                 After adding the server name, click <guibutton>'Re-Test Server'</guibutton>.</para>\r
61                                 <para>Because this is the initial run of the Staff Client, you will see a warning in the\r
62                                 upper-right saying: <emphasis role="bold">Not yet configured for the specified\r
63                                 server</emphasis>. The first thing you must do to the Staff Client on every workstation\r
64                                 is to assign it a workstation name. This is covered in \r
65                                 <xref linkend="staffclientinstallation-workstationnames"/>.</para>\r
66                                         <note><para>Users must have the <literal>REGISTER_WORKSTATION</literal> permission and be assigned the appropriate working location(s) in order to \r
67                                         register a workstation.</para></note> \r
68                                         <para>To add working locations to a user’s account:</para>\r
69                                         <orderedlist>\r
70                                                 <listitem>\r
71                                                         <para>Retrieve the user through a patron search and select <menuchoice><guimenu>Other</guimenu><guimenuitem>User Permission \r
72                                                         Editor</guimenuitem></menuchoice> and select the boxes for the locations necessary.</para> \r
73                                                         <para>Save the user record.</para>\r
74                                                         <note>\r
75                                                                 <para>Making modifications to <guilabel>Working Locations</guilabel> while changing permission settings does not work – when this \r
76                                                                 workflow is performed, permission changes will not be applied to the database.</para>\r
77                                                         </note>\r
78                                                 </listitem>\r
79                                                 <listitem>\r
80                                                         <para>Alternately, from the <guimenu>Admin</guimenu> menu, select <guimenuitem>User Permission Editor</guimenuitem> and retrieve the user by \r
81                                                         barcode.</para>  \r
82                                                         <para>Make changes to working locations as described above.</para>\r
83                                                 </listitem>\r
84                                         </orderedlist>\r
85                         </section>\r
86                         <section xml:id="staffclientinstallation-installing-macos">\r
87                                 <title>Installing on <systemitem class="osname">Mac OS</systemitem></title>\r
88                                 <indexterm>\r
89                                         <primary>staff client</primary>\r
90                                         <secondary>installing</secondary>\r
91                                         <tertiary>Mac OS</tertiary>\r
92                                 </indexterm>\r
93                                 <para>This section describes <systemitem class="osname">Mac OS</systemitem>\r
94                                 packages and related versions of <application>XULrunner</application> that can\r
95                                 be used to run the Staff Client in a <systemitem class="osname">Mac OS</systemitem>\r
96                                 environment.</para>\r
97                                 <simplesect>\r
98                                         <title>Evergreen Version 1.2.3.0</title>\r
99                                         <orderedlist>\r
100                                                 <listitem>\r
101                                                         <para>A <systemitem class="osname">Mac OS</systemitem> package that\r
102                                                         contains an early version of the Staff Client (version 1.2.3.0) for use\r
103                                                         with <application>XULrunner</application> is available. You can find\r
104                                                         current releases of <application>XULrunner</application> here:\r
105                                                         <ulink url="http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases">\r
106                                                         http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases</ulink> .\r
107                                                         Download and install the latest version. You can find further information \r
108                                                         about <application>XULrunner</application> here: \r
109                                                         <ulink url="https://developer.mozilla.org/en/xulrunner">\r
110                                                         https://developer.mozilla.org/en/xulrunner</ulink>.</para>\r
111                                                         <para>Note that later versions of <application>XULrunner</application>\r
112                                                         (e.g., version 1.9.2.13) have replaced version 1.8.0.4, which has known\r
113                                                         security holes and is not recommended for applications that deal with\r
114                                                         public web content.</para>\r
115                                                 </listitem>\r
116                                                 <listitem>\r
117                                                         <para>A <systemitem class="osname">Mac OS</systemitem>\r
118                                                         Installation package for Staff Client version 1.2.3.0 is\r
119                                                         available from Evergreen Indiana. Download and install it from\r
120                                                         here:\r
121                                                         <ulink url="http://evergreen.lib.in.us/opac/extras/files/evergreen_osx_staff_client_1_2_3.zip">\r
122                                                         evergreen_osx_staff_client_1_2_3.zip</ulink> .\r
123                                                         </para>\r
124                                                 </listitem>\r
125                                                 <listitem>\r
126                                                         <para>To upgrade to a more recent version of the Staff Client, you can\r
127                                                         copy the <filename class="directory">build</filename> directory from a\r
128                                                         working <systemitem class="osname">Windows</systemitem> installation of\r
129                                                         the desired version of the Staff Client to your \r
130                                                         <systemitem class="osname">Mac</systemitem>. \r
131                                                         The required files may be located in a directory like this on the\r
132                                                         <systemitem class="osname">Windows</systemitem> machine: \r
133                                                         <filename class="directory">C:\Program Files\Evergreen Staff Client\build</filename>.\r
134                                                         Copy these files to the <filename class="directory">Resources</filename>\r
135                                                         folder within the <package>Open-ILS</package> package in your \r
136                                                         <filename class="directory">Applications</filename> directory on the Mac,\r
137                                                         overwriting files with the same names.</para>\r
138                                                 </listitem>\r
139                                                 <listitem>Drag the application's icon to your toolbar for easier\r
140                                                 access.</listitem>\r
141                                         </orderedlist>\r
142                                         <para>When you run the Staff Client installer, a screen will appear that looks\r
143                                         similar to this:</para>\r
144                                         <mediaobject>\r
145                                                 <alt>\r
146                                                         <phrase>Running the Staff Client installer for \r
147                                                         <systemitem class="osname">Mac OS</systemitem></phrase>\r
148                                                 </alt>\r
149                                                 <imageobject>\r
150                                                         <imagedata fileref="../media/staffclientinstallation-staffclient-3.png" format="PNG" scalefit="1" width="20%"/>\r
151                                                 </imageobject>\r
152                                         </mediaobject>\r
153                                         <para>Click <guibutton>'Continue'</guibutton>, accept the license, then finish the\r
154                                         installation. The application will be located at the destination you selected\r
155                                         during installation. You will then be able to drag the application into your\r
156                                         toolbar for easier access.</para>\r
157                                         <mediaobject>\r
158                                                 <alt>\r
159                                                         <phrase>Finishing the installation</phrase>\r
160                                                 </alt>\r
161                                                 <imageobject>\r
162                                                         <imagedata fileref="../media/staffclientinstallation-staffclient-4.png" format="PNG" scalefit="1" width="20%"/>\r
163                                                 </imageobject>\r
164                                         </mediaobject>\r
165                                 </simplesect>\r
166                                 <simplesect>\r
167                                         <title>Running directly using <application>XULrunner</application></title>\r
168                                         <indexterm>\r
169                                                 <primary>staff client</primary>\r
170                                                 <secondary>XULRunner</secondary>\r
171                                         </indexterm>\r
172                                         <para>You must install an appropriate version of <application>XULrunner</application> \r
173                                         to match the Evergreen version. See the following table for the recommended version of\r
174                                         <application>XULrunner</application>:</para>\r
175                                         <table xml:id="staffclientinstallation-table-1">\r
176                                                 <?dbfo keep-together="always" ?>\r
177                                                 <title>Evergreen / <application>XULrunner</application> Dependencies</title>\r
178                                                 <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
179                                                         <colspec colname="evergreen_version" colnum="1" colwidth="1.0*"/>\r
180                                                         <colspec colname="xulrunner_version" colnum="2" colwidth="1.0*"/>\r
181                                                         <thead>\r
182                                                                 <row>\r
183                                                                         <entry>Evergreen Version</entry>\r
184                                                                         <entry>XULRunner Version</entry>\r
185                                                                 </row>\r
186                                                         </thead>\r
187                                                         <tbody>\r
188                                                                 <row>\r
189                                                                         <entry>Evergreen 1.6.x.x</entry>\r
190                                                                         <entry>XULrunner 1.9.x.x</entry>\r
191                                                                 </row>\r
192                                                                 <row>\r
193                                                                         <entry>Evergreen 1.4.x.x</entry>\r
194                                                                         <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry>\r
195                                                                 </row>\r
196                                                                 <row>\r
197                                                                         <entry>Evergreen 1.2.x.x</entry>\r
198                                                                         <entry>XULrunner 1.8.0.4 or XULrunner 1.8.0.3</entry>\r
199                                                                 </row>\r
200                                                         </tbody>\r
201                                                 </tgroup>\r
202                                         </table>\r
203                                         <note>If you have issues removing previously installed\r
204                                         <application>XULrunner</application> versions see \r
205                                         <xref linkend="staffclientinstallation-remove-xulrunner"/>\r
206                                         for further information.</note>\r
207                                         <para>The Staff Client data from the directory \r
208                                         <filename class="directory">./staff_client/build</filename> must be placed\r
209                                         somewhere on the machine (e.g. \r
210                                         <filename class="directory">~/Desktop/Evergreen_Staff_Client</filename>).</para>\r
211                                         <para>Remember to call <application>XULrunner</application> with the full path to the\r
212                                         binary, followed by the install command and the path to the client data:</para>\r
213 <screen>\r
214         <userinput>\r
215         /Library/Frameworks/XUL.framework/xulrunner-bin --install-app ~/Desktop/Evergreen_Staff_Client</userinput>\r
216 </screen>\r
217                                         <para>The command should exit quietly and will create the folder \r
218                                         <filename class="directory">/Applications/OpenILS</filename>,\r
219                                         containing a launcher named <application>open_ils_staff_client</application>.</para>\r
220                                 </simplesect>\r
221                                 <simplesect xml:id="staffclientinstallation-remove-xulrunner">\r
222                                         <title>(OPTIONAL) Removing previously installed XULRunner versions</title>\r
223                                         <indexterm>\r
224                                                 <primary>XULRunner</primary>\r
225                                                 <secondary>removing previous versions</secondary>\r
226                                         </indexterm>\r
227                                         <para>If you already have a newer version of\r
228                                         <application>XULrunner</application> installed, per the release notes, \r
229                                         you will need to remove the entire directory \r
230                                         <filename class="directory">/Library/Frameworks/XUL.framework</filename> \r
231                                         before downgrading.</para>\r
232                                         <para>In addition, you may also need to remove the previous file\r
233                                         <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> .</para>\r
234                                         <para>If file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> does\r
235                                         not exist (possibly in newer <systemitem class="osname">Mac OS</systemitem>\r
236                                         releases), you need to flush the file <filename>receiptdb</filename>.</para>\r
237                                         <note>If you install a newer version of <application>XULrunner</application>\r
238                                         over a previous (older) install, the older install is not removed but the\r
239                                         symlinks are changed to the newer one.</note>\r
240                                 </simplesect>\r
241                                 <simplesect>\r
242                                         <title>(OPTIONAL) Flush Receiptdb file:</title>\r
243                                         <para>First, get the package identifier, then purge/forget the build that was\r
244                                         initially installed:</para>\r
245 <screen>\r
246         <userinput>\r
247         sudo pkgutil --pkgs > /tmp/pkgs.txt\r
248         sudo pkgutil --forget org.mozilla.xulrunner</userinput>\r
249 </screen>\r
250                                         <note>It may not be necessary to edit the file\r
251                                         <filename>/Library/Receipts/InstallHistory.plist</filename> after deleting the\r
252                                         folder <filename class="directory">XUL.framework</filename>. See\r
253                                         <ulink url="http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html">\r
254                                         http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html</ulink> \r
255                                         for more information.</note>\r
256                                 </simplesect>\r
257                                 <simplesect>\r
258                                         <title>Creating an APP file: Staff Client and <application>XULrunner</application> Bundled</title>\r
259                                         <para>An APP file is basically a folder. Start with a folder stucture like this:</para>\r
260 <screen>\r
261         <prompt>\r
262         Evergreen.app\r
263         __Contents\r
264         ____Frameworks\r
265         ____Resources\r
266         ____MacOS</prompt>\r
267 </screen>\r
268                                         <para>Create an APP folder structure with the following commands:</para>\r
269 <screen>\r
270         <userinput>\r
271         mkdir -p Evergreen.app/Contents/Frameworks\r
272         mkdir -p Evergreen.app/Contents/Resources\r
273         mkdir -p Evergreen.app/Contents/MacOS</userinput>\r
274 </screen>\r
275                                         <orderedlist>\r
276                                                 <listitem>\r
277                                                         <para>Create a new file in the folder\r
278                                                         <filename class="directory">Evergreen.app/Contents/Info.plist</filename>\r
279                                                         containing the following data (adjust for your version of\r
280                                                         Evergreen):</para>\r
281                                                         <programlisting language="xml"><![CDATA[\r
282 <?xml version="1.0" encoding="UTF-8"?>\r
283 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\r
284 <plist version="1.0">\r
285 <dict>\r
286         <key>CFBundleExecutable</key>\r
287         <string>xulrunner</string>\r
288         <key>CFBundleGetInfoString</key>\r
289         <string>OpenILS open_ils_staff_client rel_1_6_1_6</string>\r
290         <key>CFBundleInfoDictionaryVersion</key>\r
291         <string>6.0</string>\r
292         <key>CFBundleName</key>\r
293         <string>Evergreen Staff Client</string>\r
294         <key>CFBundlePackageType</key>\r
295         <string>APPL</string>\r
296         <key>CFBundleShortVersionString</key>\r
297         <string>rel_1_6_1_6</string>\r
298         <key>CFBundleVersion</key>\r
299         <string>rel_1_6_1_6.rel_1_6_1_6</string>\r
300         <key>NSAppleScriptEnabled</key>\r
301         <true/>\r
302         <key>CFBundleTypeIconFile</key>\r
303         <string>Evergreen.icns</string>\r
304 </dict>\r
305 </plist>\r
306 ]]></programlisting>\r
307                                                 </listitem>\r
308                                                 <listitem>Download and install an appropriate \r
309                                                 <systemitem class="osname">Mac OS</systemitem> package of \r
310                                                 <application>XULrunner</application> from the Mozilla website\r
311                                                 <ulink url="https://developer.mozilla.org/en/xulrunner">\r
312                                                 https://developer.mozilla.org/en/xulrunner</ulink> (see \r
313                                                 <xref linkend="staffclientinstallation-table-1"/> for recommendations).</listitem>\r
314                                                 <listitem>\r
315                                                         <para>Make a copy of the folder\r
316                                                         <filename class="directory">/Library/Frameworks/XUL.Framework</filename>\r
317                                                         inside your APP file. It should look something like this:</para>\r
318 <screen>\r
319         <prompt>\r
320         Evergreen.app/\r
321         __Contents/\r
322         ____Frameworks/\r
323         ______XUL.Framework/\r
324         ______Versions/\r
325         ________Current -> 1.9.1.3 (symlink)\r
326         ________1.9.1.3/\r
327         ______XUL -> Versions/Current/XUL\r
328         ______libxpcom.dylib -> Versions/Current/libxpcom.dylib\r
329         ______xulrunner-bin -> Versions/Current/xulrunner-bin</prompt>\r
330 </screen>\r
331                                                 </listitem>\r
332                                                 <listitem>Copy\r
333                                                 <filename>XUL.Framework/Versions/Current/xulrunner</filename> into the\r
334                                                 folder <filename class="directory">Evergreen.app/MacOS</filename>\r
335                                                 (do not symlink; copy the file).</listitem>\r
336                                                 <listitem>\r
337                                                         <para>Make <filename>Evergreen.app/Resources</filename> the root\r
338                                                         of your Evergreen application files like this:</para>\r
339 <screen>\r
340         <prompt>\r
341         Evergreen.app/\r
342         __Contents/\r
343         ____Resources/\r
344         ______BUILD_ID\r
345         ______application.ini\r
346         ______chrome/\r
347         ______components/\r
348         ______etc.</prompt>\r
349 </screen>\r
350                                                 </listitem>\r
351                                                 <listitem>Put a <systemitem class="osname">Mac</systemitem> \r
352                                                 format icon file named <filename>Evergreen.icns</filename> in \r
353                                                 <filename class="resources">Resources</filename>.</listitem>\r
354                                         </orderedlist>\r
355                                 </simplesect>\r
356                         </section>\r
357                         <section xml:id="staffclientinstallation-installing-linux">\r
358                                 <title>Installing on Linux</title>\r
359                                 <simplesect>\r
360                                         <title>Quick Upgrade of the Staff Client</title>\r
361                                         <para>A Linux Staff Client is automatically built on the server as part of the\r
362                                         normal <emphasis>make install</emphasis> process for Evergreen server-side\r
363                                         software. To upgrade the Staff Client on a remote Linux workstation with a new\r
364                                         version, just copy the directory tree containing the Staff Client from your\r
365                                         server to the remote workstation.</para>\r
366                                         <para>Execute the following commands, replacing <literal>USER</literal>,\r
367                                         <literal>WORKSTATION</literal>, and <literal>SOME_PATH</literal> with\r
368                                         appropriate values:</para>\r
369 <screen>\r
370         <userinput>\r
371         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
372         scp -r ./build USER@WORKSTATION:/SOME_PATH/</userinput>\r
373 </screen>\r
374                                         <para>You should test the newly copied Staff Client on the remote workstation.\r
375                                         Log into the workstation and execute the following command:</para>\r
376 <screen>\r
377         <userinput>\r
378         xulrunner /SOME_PATH/build/application.ini</userinput>\r
379 </screen>\r
380                                 </simplesect>\r
381                                 <simplesect>\r
382                                         <title>Building the Staff Client on the Server</title>\r
383                                         <indexterm>\r
384                                                 <primary>staff client</primary>\r
385                                                 <secondary>building on the server</secondary>\r
386                                         </indexterm>\r
387                                         <para>A Linux Staff Client is automatically built on the server as part of the\r
388                                         normal <emphasis>make install</emphasis> process for Evergreen server-side\r
389                                         software. See <xref linkend="serversideinstallation-compile"/> for details of\r
390                                         the build process.</para>\r
391                                         <para>In order to install a compatible Staff Client on another Linux system, you\r
392                                         can copy the appropriate files from the Staff Client build directory on your\r
393                                         server to the new Linux system. You could manually build the Staff Client on the\r
394                                         new system, but you must ensure that the <envar>BUILD_ID</envar> you chose on\r
395                                         the server matches the <envar>BUILD_ID</envar> for each Staff Client you use on\r
396                                         other systems.</para>\r
397                                         <para>If you wish to use a pre-packaged <systemitem class="osname">Windows</systemitem>\r
398                                         version on some systems, you may want to choose the <envar>BUILD_ID</envar> on\r
399                                         both server and other versions to match that of the \r
400                                         <systemitem class="osname">Windows</systemitem> Staff Client. To determine which\r
401                                         <envar>BUILD_ID</envar> was used for existing Staff Client installations,\r
402                                         execute each Staff Client and click the <guibutton>'About this Client'</guibutton>\r
403                                         button.</para>\r
404                                         <para>If you are allowed to make changes on the Evergreen server, another option\r
405                                         is to create a symbolic link. In order for a copy of the Staff Client and server\r
406                                         to work together, the <envar>BUILD_ID</envar> must match the name of the\r
407                                         directory containing the server components of the Staff Client, or the name of a\r
408                                         symbolic link to that directory. As the \r
409                                         <systemitem class="username">root</systemitem> user, make the changes as follows:</para>\r
410 <screen>\r
411         <userinput>\r
412         # as the root user:\r
413         cd /openils/var/web/xul\r
414         ln -s SERVER_BUILD_ID/ CLIENT_BUILD_ID</userinput>\r
415 </screen>\r
416                                 </simplesect>\r
417                                 <simplesect>\r
418                                         <title>Building the Staff Client on a Client Machine</title>\r
419                                         <para>This section is directed toward end-users who wish to use Linux rather than\r
420                                         <systemitem class="osname">Windows</systemitem> for client machines, but have limited\r
421                                         Linux experience. You can build the Staff Client on a Linux system without installing the\r
422                                         Evergreen Server component. This is a relatively simple process compared to server\r
423                                         installation, but does require some command-line work. The following instructions are \r
424                                         for building Staff Client version 1.2.1.4 on \r
425                                         <systemitem class="osname">Kubuntu 7.10</systemitem>; modify them as needed for\r
426                                         other distributions (the instructions should work as-is for\r
427                                         <systemitem class="osname">Ubuntu</systemitem> or \r
428                                         <systemitem class="osname">Ubuntu</systemitem> derivatives).</para>\r
429                                         <procedure>\r
430                                                 <step>\r
431                                                         <title>Prerequisites</title>\r
432                                                         <para>Both <application>subversion</application> and\r
433                                                         <application>XULrunner</application> are required to build the Staff\r
434                                                         Client. As the <systemitem class="username">root</systemitem> user, \r
435                                                         use <command>apt-get</command> to install packages for\r
436                                                         <application>subversion</application> and\r
437                                                         <application>XULrunner</application>. You can also use\r
438                                                         <command>synaptic</command>, the graphical user interface for\r
439                                                         <command>apt-get</command>. For <application>subversion</application>,\r
440                                                         select the latest version; for <application>XULrunner</application>,\r
441                                                         select version <emphasis>1.8.1.4-2ubuntu5</emphasis>.</para>\r
442 <screen>\r
443         <userinput>\r
444         # as the root user:\r
445         sudo apt-get install subversion\r
446         sudo apt-get install xulrunner</userinput>\r
447 </screen>\r
448                                                 </step>\r
449                                                 <step>\r
450                                                         <title>Download the Source Code</title>\r
451                                                         <itemizedlist>\r
452                                                                 <listitem>\r
453                                                                         <para>Determine which version is needed</para>\r
454                                                                         <para>For most end-users, a specific version is required\r
455                                                                         to communicate properly with the Evergreen server. Check\r
456                                                                         with your system administrator, IT person, or HelpDesk to\r
457                                                                         determine which Staff Client versions are\r
458                                                                         supported.</para>\r
459                                                                         <para>Next, you need to determine which\r
460                                                                         <emphasis>tag</emphasis> to use when downloading the\r
461                                                                         source code. Tags are markers in the source code to create\r
462                                                                         a snapshot of the code as it existed at a certain time;\r
463                                                                         tags usually point to tested and stable code, or at least\r
464                                                                         a community-recognized release version.</para>\r
465                                                                         <para>To determine which tag to use, browse to \r
466                                                                         <ulink url="http://svn.open-ils.org/trac/ILS/browser">\r
467                                                                         http://svn.open-ils.org/trac/ILS/browser</ulink>. \r
468                                                                         Look in the <guilabel>Visit</guilabel> drop-down box; see\r
469                                                                         the list of <guilabel>Branches</guilabel> and, further\r
470                                                                         down, a list of <guilabel>Tags</guilabel>. You may have \r
471                                                                         to do some guesswork, but it is fairly straightforward to\r
472                                                                         determine which tag to use. If the server is version\r
473                                                                         1.6.1.6, you will want to use the tag that looks most\r
474                                                                         appropriate. For example, as you look through the tag\r
475                                                                         list, notice the tag named 'rel_1_6_1_6'. This is the tag\r
476                                                                         you need; make a note of it for the next step.</para>\r
477                                                                 </listitem>\r
478                                                                 <listitem>\r
479                                                                         <para>Download the Code</para>\r
480                                                                         <para>As the\r
481                                                                         <systemitem class="username">opensrf</systemitem> \r
482                                                                         user, open a terminal (command-line prompt) and navigate\r
483                                                                         to the directory in which you wish to download the Staff\r
484                                                                         Client. Use the following commands to download the proper\r
485                                                                         version of the source code by tag name:</para>\r
486 <screen>\r
487         <userinput>\r
488         # as the opensrf user:\r
489         cd /DOWNLOAD/DIRECTORY\r
490         svn co rel_1_6_1_6/</userinput>\r
491 </screen>\r
492                                                                         <para>Remember to change "rel_1_6_1_6" to the appropriate\r
493                                                                         tag for your installation.</para>\r
494                                                                 </listitem>\r
495                                                         </itemizedlist>\r
496                                                 </step>\r
497                                                 <step>\r
498                                                         <title>Build the Staff Client</title>\r
499                                                         <para>In the following example, navigate to the directory in\r
500                                                         which the source code was downloaded, then navigate to the\r
501                                                         proper subdirectory and run the "make" utility to actually build\r
502                                                         the Staff Client. Remember to check with your system\r
503                                                         administrator about which Staff Client <envar>BUILD_ID</envar>\r
504                                                         to use. The server checks the Staff Client\r
505                                                         <envar>BUILD_ID</envar> against itself to determine whether or\r
506                                                         not a connecting client is supported. For instance, for the\r
507                                                         PINES installation (version 1.6.1.6) the supported\r
508                                                         <envar>BUILD_ID</envar> is "rel_1_6_1_6". Modify the following\r
509                                                         commands accordingly.</para>\r
510                                                         <para>As the <systemitem class="username">opensrf</systemitem>\r
511                                                         user, run the following commands to build the Staff Client:</para>\r
512 <screen>\r
513         <userinput>\r
514         # as the opensrf user:\r
515         wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.6.tar.gz\r
516         tar xfz Evergreen-ILS-1.6.1.6.tar.gz\r
517         cd /home/opensrf/Evergreen-ILS-1.6.1.6\r
518         ./configure --prefix=/openils --sysconfdir=/openils/conf\r
519         cd ./Open-ILS/xul/staff_client/\r
520         make STAFF_CLIENT_BUILD_ID='rel_1_6_1_6' install</userinput>\r
521 </screen>\r
522                                                 </step>\r
523                                                 <step>\r
524                                                         <title>Run the Staff Client</title>\r
525                                                         <para>As the <systemitem class="username">opensrf</systemitem> \r
526                                                         user, navigate to the <filename class="directory">build/</filename>\r
527                                                         subdirectory and run the following command:</para>\r
528 <screen>\r
529         <userinput>\r
530         # as the opensrf user:\r
531         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client/build\r
532         xulrunner application.ini</userinput>\r
533 </screen>\r
534                                                 </step>\r
535                                                 <step>\r
536                                                         <title>(OPTIONAL) Clean Up / Create Shortcuts</title>\r
537                                                         <para>The source code download included many files that are\r
538                                                         needed to build the Staff Client but are not necessary to run\r
539                                                         it. You may wish to remove them to save space, or to create a\r
540                                                         clean <literal>staging</literal> directory containing the\r
541                                                         finished Staff Client that can then be copied to other\r
542                                                         machines. To do this, execute the following commands (remember\r
543                                                         to replace <emphasis>DOWNLOAD_DIRECTORY</emphasis> and\r
544                                                         <emphasis>STAGING_DIRECTORY</emphasis> with the appropriate\r
545                                                         paths):</para>\r
546 <screen>\r
547         <userinput>\r
548         # as the opensrf user:\r
549         mkdir ~/STAGING_DIRECTORY\r
550         cd ~/DOWNLOAD_DIRECTORY/Open-ILS/xul/\r
551         cp -r staff_client ~/STAGING_DIRECTORY</userinput>\r
552 </screen>\r
553                                                         <para>Test the Staff Client to verify that all necessary files\r
554                                                         were copied to the staging directory:</para>\r
555 <screen>\r
556         <userinput>\r
557         # as the opensrf user:\r
558         cd ~/STAGING_DIRECTORY/staff_client/build\r
559         xulrunner application.ini</userinput>\r
560 </screen>\r
561                                                         <para>If there were no problems, then finish the cleanup by\r
562                                                         removing the original download directory as shown:</para>\r
563 <screen>\r
564         <userinput>\r
565         # as the opensrf user:\r
566         rm -r -f ~/DOWNLOAD_DIRECTORY</userinput>\r
567 </screen>\r
568                                                         <para>Finally, the command:</para>\r
569 <screen>\r
570         <userinput>\r
571         # as the opensrf user:\r
572         xulrunner ~/STAGING_DIRECTORY/staff_client/build/application.ini</userinput>\r
573 </screen>\r
574                                                         <para>will now run the Staff Client. You may wish to create a\r
575                                                         shortcut for the Staff Client. To do so, use the previous\r
576                                                         command as the target for the shortcut:\r
577                                                         <menuchoice>\r
578                                                                 <guimenu>Desktop</guimenu>\r
579                                                                 <guimenuitem>StartMenu</guimenuitem>\r
580                                                                 <guimenuitem>K-Menu</guimenuitem>\r
581                                                         </menuchoice></para>\r
582                                                 </step>\r
583                                         </procedure>\r
584                                 </simplesect>\r
585                                 <simplesect>\r
586                                         <title>Using Wine to Install on Linux</title>\r
587                                         <indexterm>\r
588                                                 <primary>staff client</primary>\r
589                                                 <secondary>using wine to install on Linux</secondary>\r
590                                         </indexterm>\r
591                                         <para>The Linux application <application>Wine</application> is another\r
592                                         alternative if you wish to install the packaged \r
593                                         <systemitem class="osname">Windows</systemitem> versions rather than manually\r
594                                         building the Staff Client. <application>Wine</application> is a Linux\r
595                                         application that allows users to directly run\r
596                                         <systemitem class="osname">Windows</systemitem> executables, and is a simple \r
597                                         way for casual Linux users to use the Staff Client. You can find more information \r
598                                         about <application>Wine</application> at\r
599                                         <ulink url="http://www.winehq.org/site/docs/wineusr-guide/getting-wine">\r
600                                         http://www.winehq.org/site/docs/wineusr-guide/getting-wine</ulink>.</para>\r
601                                         <para>As the <systemitem class="username">root</systemitem> user, use\r
602                                         <command>apt-get</command> to install the package for <application>Wine</application>. \r
603                                         You can also use <command>synaptic</command>, the graphical user interface.</para>\r
604                                         <orderedlist>\r
605                                                 <listitem>\r
606                                                         <para>Install wine:</para>\r
607 <screen>\r
608         <userinput>\r
609         # as the root user:\r
610         sudo apt-get install wine</userinput>\r
611 </screen>\r
612                                                 </listitem>\r
613                                                 <listitem>\r
614                                                         <para>Visit the downloads section of the Evergreen website at\r
615                                                         <ulink url="http://www.evergreen-ils.org/downloads.php">\r
616                                                         http://www.evergreen-ils.org/downloads.php</ulink> and find the\r
617                                                         <systemitem class="osname">Microsoft Windows</systemitem> Installer\r
618                                                         that contains the desired version of the Staff Client. Download\r
619                                                         the installer and place it in a temporary directory.</para>\r
620                                                 </listitem>\r
621                                                 <listitem>\r
622                                                         <para>As the <systemitem class="username">opensrf</systemitem>\r
623                                                         user, navigate to the temporary directory where you downloaded \r
624                                                         the <systemitem class="osname">Windows</systemitem> installer \r
625                                                         file, then execute it with the <application>wine</application>\r
626                                                         application (remember to replace <emphasis>VERSION</emphasis> with\r
627                                                         the release number of the Staff Client you downloaded):</para>\r
628 <screen>\r
629         <userinput>\r
630         # as the opensrf user:\r
631         cd /TEMP_DIRECTORY\r
632         wine evergreen-setup-rel_VERSION.exe</userinput>\r
633 </screen>\r
634                                                         <para>If this step fails, you may need to configure\r
635                                                         <application>Wine</application> first to properly emulate \r
636                                                         <systemitem class="osname">Windows XP</systemitem>. To do so,\r
637                                                         type <command>winecfg</command> from the command line; in the\r
638                                                         <literal>Applications</literal> tab of the window that pops up,\r
639                                                         select <literal>Default Settings</literal> and choose\r
640                                                         <literal>Windows XP</literal> from the drop-down menu, then\r
641                                                         click <guibutton>'Apply'</guibutton>.</para>\r
642                                                 </listitem>\r
643                                                 <listitem>\r
644                                                         <para>Launch the Staff Client</para>\r
645                                                         <para>A new entry for the Staff Client should now appear\r
646                                                         somewhere in the <literal>All Applications</literal> menu of\r
647                                                         your Linux desktop. You may also find a new desktop shortcut for\r
648                                                         the Staff Client. To launch the Staff Client, visit the\r
649                                                         <literal>All Applications</literal> menu on your desktop and\r
650                                                         find the section similar to:</para>\r
651                                                         <para>\r
652                                                                 <menuchoice>\r
653                                                                         <guimenu>Wine</guimenu>\r
654                                                                         <guimenuitem>Program Files</guimenuitem>\r
655                                                                         <guimenuitem>Evergreen Staff Client</guimenuitem>\r
656                                                                         <guimenuitem>Evergreen Staff Client</guimenuitem>\r
657                                                                 </menuchoice>,\r
658                                                         </para>\r
659                                                         <para>or else launch the Staff Client from the new desktop shortcut.</para>\r
660                                                 </listitem>\r
661                                         </orderedlist>\r
662                                 </simplesect>\r
663                         </section>\r
664                 </section>\r
665                 <section>\r
666                         <title>Building the Staff Client</title>\r
667                         <indexterm>\r
668                                 <primary>staff client</primary>\r
669                                 <secondary>building</secondary>\r
670                         </indexterm>\r
671                         <para>You can also manually build the Staff Client by using the <command>make</command>\r
672                         utility in the Staff Client source directory (e.g., the directory \r
673                         <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client</filename>\r
674                         for the current Evergreen version). There are a number of possible options to manually\r
675                         build special versions of the Staff Client on a Linux system. Following is a list of\r
676                         variables that you can pass to <command>make</command> to influence the manual build\r
677                         process:</para>\r
678                         <simplesect>\r
679                                 <title>\r
680                                         Build Variable <envar>STAFF_CLIENT_BUILD_ID</envar></title>\r
681                                 <para>During the normal <emphasis>make install</emphasis> Evergreen server-side\r
682                                 software build process, the variable defaults to an automatically generated\r
683                                 date/time string, but you can also override the value of <envar>BUILD_ID</envar>.</para>\r
684                                 <para>You could use the following commands during the normal install process:</para>\r
685 <screen>\r
686         <userinput>\r
687         # as the root user:\r
688         cd /home/opensrf/Evergreen-ILS-1.6.1.6\r
689         make STAFF_CLIENT_BUILD_ID=1_6_1_6 install</userinput>\r
690 </screen>\r
691                                 <para>You can also manually build the Staff Client in the Staff Client\r
692                                 source directory with a different <envar>BUILD_ID</envar>.</para>\r
693                                 <para>As the <systemitem class="username">opensrf</systemitem> user,\r
694                                 execute the following commands to build the Staff Client (remember to replace\r
695                                 <emphasis>NEW_VERSION</emphasis> with an appropriate value):</para>\r
696 <screen>\r
697         <userinput>\r
698         # as the opensrf user:\r
699         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
700         make STAFF_CLIENT_BUILD_ID=NEW_VERSION  build</userinput>\r
701 </screen>\r
702                         </simplesect>\r
703                         <simplesect>\r
704                                 <title>\r
705                                         Build Variable <envar>STAFF_CLIENT_VERSION</envar></title>\r
706                                 <para>During the normal <emphasis>make install</emphasis> Evergreen server-side\r
707                                 software build process, the variable is pulled automatically from a README file\r
708                                 in the Evergreen source root. The variable defaults to\r
709                                 <emphasis>0trunk.revision</emphasis>, where the value of "revision" is\r
710                                 automatically generated. You can override the value of <envar>VERSION</envar>\r
711                                 similarly to the <envar>BUILD_ID</envar>.</para>\r
712                                 <para>You could use the following commands during the normal install process:</para>\r
713 <screen>\r
714         <userinput>\r
715         # as the root user:\r
716         cd /home/opensrf/Evergreen-ILS-1.6.1.6\r
717         make STAFF_CLIENT_VERSION=0mytest.200 install</userinput>\r
718 </screen>\r
719                                 <para>You can also manually build the Staff Client in the Staff Client\r
720                                 source directory with a different <envar>VERSION</envar>.</para>\r
721                                 <para>If you plan to make extensions update automatically, the \r
722                                 <envar>VERSION</envar> needs to conform to the format recommended in \r
723                                 <ulink url="https://developer.mozilla.org/en/Toolkit_version_format">\r
724                                 Toolkit Version Format</ulink> and newer versions need to be "higher" than older\r
725                                 versions.</para>\r
726                                 <para>As the <systemitem class="username">opensrf</systemitem> user,\r
727                                 execute the following commands to build the Staff Client:</para>\r
728 <screen>\r
729         <userinput>\r
730         # as the opensrf user:\r
731         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
732         make STAFF_CLIENT_VERSION=0mytest.200  build</userinput>\r
733 </screen>\r
734                         </simplesect>\r
735                         <simplesect>\r
736                                 <title>\r
737                                         Build Variable <envar>STAFF_CLIENT_STAMP_ID</envar></title>\r
738                                 <para>During the normal <emphasis>make install</emphasis> Evergreen\r
739                                 server-side software build process, the variable is generated from\r
740                                 <envar>STAFF_CLIENT_VERSION</envar>. You may want to have multiple versions\r
741                                 of the Staff Client with different stamps, possibly for different uses or\r
742                                 client-side customizations. You can override the value of\r
743                                 <envar>STAMP_ID</envar> similarly to the <envar>BUILD_ID</envar>.</para>\r
744                                 <para>You could use the following commands during the normal install process:</para>\r
745 <screen>\r
746         <userinput>\r
747         # as the root user:\r
748         cd /home/opensrf/Evergreen-ILS-1.6.1.6\r
749         make STAFF_CLIENT_STAMP_ID=my_test_stamp install</userinput>\r
750 </screen>\r
751                                 <para>You can also manually build the Staff Client in the Staff Client\r
752                                 source directory with a different <envar>STAMP_ID</envar>.</para>\r
753                                 <para>As the <systemitem class="username">opensrf</systemitem> user,\r
754                                 execute the following commands to build the Staff Client:</para>\r
755 <screen>\r
756         <userinput>\r
757         # as the opensrf user:\r
758         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
759         make STAFF_CLIENT_STAMP_ID=my_test_stamp  build</userinput>\r
760 </screen>\r
761                         </simplesect>\r
762                 </section>\r
763                 <section>\r
764                         <title>Advanced Build Options</title>\r
765                         <indexterm>\r
766                                 <primary>staff client</primary>\r
767                                 <secondary>building</secondary>\r
768                                 <tertiary>advanced build options</tertiary>\r
769                         </indexterm>\r
770                         <para>In addition to the basic options listed above, there are a number of advanced\r
771                         options for building the Staff Client. Most are target names for the\r
772                         <command>make</command> utility and require that you build the Staff Client from the\r
773                         <literal>staff_client</literal> directory. See the following table for a list of\r
774                         possible <command>make</command> target keywords:</para>\r
775                         <table>\r
776                                 <title>Keywords For Advanced Build Options</title>\r
777                                 <?dbfo keep-together="always" ?>\r
778                                 <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
779                                         <colspec colname="keyword" colnum="1" colwidth="1.0*"/>\r
780                                         <colspec colname="description" colnum="2" colwidth="3.0*"/>\r
781                                         <thead>\r
782                                                 <row>\r
783                                                         <entry>Keyword</entry>\r
784                                                         <entry>Description</entry>\r
785                                                 </row>\r
786                                         </thead>\r
787                                         <tbody>\r
788                                                 <row>\r
789                                                         <entry>clients</entry>\r
790                                                         <entry>Runs "make win-client", "make linux-client", and "make\r
791                                                         generic-client" individually</entry>\r
792                                                 </row>\r
793                                                 <row>\r
794                                                         <entry>client_dir</entry>\r
795                                                         <entry>Builds a client directory from the build directory, without\r
796                                                         doing a rebuild. The same as "copy everything but\r
797                                                         server/".</entry>\r
798                                                 </row>\r
799                                                 <row>\r
800                                                         <entry>client_app</entry>\r
801                                                         <entry>Prerequisite "client_dir"; removes "install.rdf" from\r
802                                                         client directory so an APP bundle can't be installed as an\r
803                                                         extension</entry>\r
804                                                 </row>\r
805                                                 <row>\r
806                                                         <entry>client_ext</entry>\r
807                                                         <entry>Prerequisite "client_dir"; remove "application.ini",\r
808                                                         "autoupdate.js", "standalone_xul_app.js" from client directory so\r
809                                                         an extension won't break Firefox</entry>\r
810                                                 </row>\r
811                                                 <row>\r
812                                                         <entry>extension</entry>\r
813                                                         <entry>Prerequisite "client_ext"; rewritten to use "client_ext"</entry>\r
814                                                 </row>\r
815                                                 <row>\r
816                                                         <entry>generic-client</entry>\r
817                                                         <entry>Prerequisite "client_app"; makes an XPI file suitable for\r
818                                                         use with "xulrunner --install-app""</entry>\r
819                                                 </row>\r
820                                                 <row>\r
821                                                         <entry>win-xulrunner</entry>\r
822                                                         <entry>Prerequisite "client_app"; adds Windows xulrunner to client build</entry>\r
823                                                 </row>\r
824                                                 <row>\r
825                                                         <entry>linux-xulrunner</entry>\r
826                                                         <entry>Prerequisite "client_app"; adds Linux xulrunner to client build</entry>\r
827                                                 </row>\r
828                                                 <row>\r
829                                                         <entry>win-client</entry>\r
830                                                         <entry>Prerequisite "win-xulrunner"; builds "setup exe" (requires\r
831                                                         that "nsis" package be installed, will add options for automatic\r
832                                                         update if configured and developer options if client build was a\r
833                                                         "make devbuild")</entry>\r
834                                                 </row>\r
835                                                 <row>\r
836                                                         <entry>linux-client</entry>\r
837                                                         <entry>Prerequisite "linux_xulrunner"; builds a "tar.bz2" bundle\r
838                                                         of the Linux client</entry>\r
839                                                 </row>\r
840                                                 <row>\r
841                                                         <entry>[generic-|win-|linux-|extension-]updates[-client]</entry>\r
842                                                         <entry>Calls external/make_updates.sh to build full and partial\r
843                                                         updates generic/win/linux/extension prefix limit to that\r
844                                                         distribution; Adding <option>-client</option> builds clients and\r
845                                                         copies them to a subdirectory of the \r
846                                                         <filename class="directory">updates</filename> directory as well;\r
847                                                         <option>extension-updates-client</option> doesn't exist.</entry>\r
848                                                 </row>\r
849                                         </tbody>\r
850                                 </tgroup>\r
851                         </table>\r
852                         <para>Following are descriptions of other special build options:</para>\r
853                         <simplesect>\r
854                                 <title>Developer Build</title>\r
855                                 <para>You can create a so-called <emphasis>developer build</emphasis>\r
856                                 of the Staff Client by substituting <option>devbuild</option> for\r
857                                 <option>build</option> when running <command>make</command> from the\r
858                                 <literal>staff_client</literal> directory. The build will contain an\r
859                                 extra configuration file that enables some developer options.</para>\r
860                                 <para>As the <systemitem class="username">opensrf</systemitem> user, run\r
861                                 the following commands from the Staff Client source directory:</para>\r
862 <screen>\r
863         <userinput>\r
864         # as the opensrf user:\r
865         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
866         make devbuild</userinput>\r
867 </screen>\r
868                         </simplesect>\r
869                         <simplesect>\r
870                                 <title>Compressed Javascript</title>\r
871                                 <para>You can execute the Google <systemitem class="resource">Closure Compiler</systemitem>\r
872                                 utility to automatically review and compress Javascript code after the build\r
873                                 process completes, by substituting <option>compress-javascript</option> for\r
874                                 <option>build</option> when running <command>make</command>.\r
875                                 For more information on the Google Closure Compiler, see \r
876                                 <ulink url="http://code.google.com/closure/compiler/">\r
877                                 http://code.google.com/closure/compiler</ulink>.</para>\r
878                                 <para>As the <systemitem class="username">opensrf</systemitem> user, run\r
879                                 the following commands from the Staff Client source directory:</para>\r
880 <screen>\r
881         <userinput>\r
882         # as the opensrf user:\r
883         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
884         make compress-javascript</userinput>\r
885 </screen>\r
886                                 <para>You can also combine Javascript review and compression, and also perform a\r
887                                 <emphasis>developer build</emphasis>.</para>\r
888                                 <para>As the <systemitem class="username">opensrf</systemitem> user, run \r
889                                 the following <command>make</command> command from the Staff Client source directory\r
890                                 (the order of options is important):</para>\r
891 <screen>\r
892         <userinput>\r
893         # as the opensrf user:\r
894         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
895         make  devbuild  compress-javascript</userinput>\r
896 </screen>\r
897                         </simplesect>\r
898                         <simplesect xml:id="staffclientinstallation-autoupdatehost">\r
899                                 <title>Automatic Update Host</title>\r
900                                 <para>You can override the host used to check for automatic Staff Client updates\r
901                                 by specifying the <option>AUTOUPDATE_HOST</option> option.</para>\r
902                                 <para>You could use the following commands during the normal install process:</para>\r
903 <screen>\r
904         <userinput>\r
905         # as the root user:\r
906         cd /home/opensrf/Evergreen-ILS-1.6.1.6\r
907         make AUTOUPDATE_HOST=localhost install</userinput>\r
908 </screen>\r
909                                 <para>You can manually build the Staff Client in the Staff Client\r
910                                 source directory and set <option>AUTOUPDATE_HOST</option> to enable automatic\r
911                                 update checking.</para>\r
912                                 <para>As the <systemitem class="username">opensrf</systemitem> user,\r
913                                 execute the following commands to build the Staff Client:</para>\r
914 <screen>\r
915         <userinput>\r
916         # as the opensrf user:\r
917         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
918         make AUTOUPDATE_HOST=localhost build</userinput>\r
919 </screen>\r
920                                 <para>For more information on Automatic Updates, see\r
921                                 <xref linkend="staffclientinstallation-autoupdate"/>.</para>\r
922                         </simplesect>\r
923                 </section>\r
924                 <section>\r
925                         <title>Installing and Activating a Manually Built Staff Client</title>\r
926                         <para>The Staff Client is automatically built, installed and activated as part of the\r
927                         normal <command>make<option>install</option></command> process for Evergreen\r
928                         server-side software. However, if you manually build the Staff Client from the\r
929                         <literal>staff_client</literal> directory, then you need to take additional steps to\r
930                         properly install and activate it. You also have the option of installing the Staff\r
931                         Client on the same machine it was built on, or on a different machine.</para>\r
932                         <para>Assuming you have already built the Staff Client, and that your installation is\r
933                         in the directory <filename class="directory">/openils/var/web/xul</filename>, as the\r
934                         <systemitem class="username">opensrf</systemitem> user execute the following\r
935                         commands:</para>\r
936 <screen>\r
937         <userinput>\r
938         # as the opensrf user:\r
939         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
940         mkdir -p "/openils/var/web/xul/$(cat build/BUILD_ID)"\r
941         cp -R build/server "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput>\r
942 </screen>\r
943                 </section>\r
944                 <section>\r
945                         <title>Packaging the Staff Client</title>\r
946                         <para>Once you have built the Staff Client, you can create several forms of special client\r
947                         packages by using a modified <command>make</command> command in the <literal>staff_client</literal>\r
948                         directory.</para>\r
949                         <simplesect>\r
950                                 <title>Packaging a Generic Client</title>\r
951                                 <para>This build creates a Staff Client packaged as an XPI file suitable for use with\r
952                                 the <option>--install-app</option> parameter of <application>XULrunner</application>.\r
953                                 It requires that you already have the <systemitem>zip</systemitem> utility\r
954                                 installed on your system.</para>\r
955                                 <para>As the <systemitem class="username">opensrf</systemitem> user, execute\r
956                                 the following commands:</para>\r
957 <screen>\r
958         <userinput>\r
959         # as the opensrf user:\r
960         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
961         make generic-client</userinput>\r
962 </screen>\r
963                                 <para>The output file <filename>evergreen_staff_client.xpi</filename> will be created.</para>\r
964                         </simplesect>\r
965                         <simplesect>\r
966                                 <title>Packaging a <systemitem class="osname">Windows</systemitem> Client</title>\r
967                                 <para>This build creates a Staff Client packaged as a \r
968                                 <systemitem class="osname">Windows</systemitem> executable. It requires that\r
969                                 you already have the <application>unzip</application> utility installed on\r
970                                 your system. It also requires that you install \r
971                                 <ulink url="http://nsis.sourceforge.net/">NSIS (Nullsoft Scriptable Install System)</ulink>,\r
972                                 a professional open source utility package used to create \r
973                                 <systemitem class="osname">Windows</systemitem> installers (the\r
974                                 <application>"makensis"</application> utility is installed as part of the\r
975                                 <application>"nsis"</application> package). You should use Version 2.45 or\r
976                                 later.</para>\r
977                                 <para>If you wish for the Staff Client to have a link icon/tray icon by\r
978                                 default, you may wish to provide a pre-modified\r
979                                 <application>xulrunner-stub.exe</application>. Place it in the Staff Client\r
980                                 source directory and <command>make</command> will automatically use it instead\r
981                                 of the one that comes with the downloaded <application>XULrunner</application>\r
982                                 release. The version of <application>xulrunner-stub.exe</application> need not\r
983                                 match exactly.</para>\r
984                                 <para>You can also use a tool such as \r
985                                 <ulink url="http://www.angusj.com/resourcehacker/">Resource Hacker</ulink>\r
986                                 to embed icons. <application>Resource Hacker</application> is an open-source\r
987                                 utility used to modify resources within 32-bit\r
988                                 <systemitem class="osname">Windows</systemitem> executables. \r
989                                 Some useful icon ID strings include the following:</para>\r
990                                 <table>\r
991                                         <?dbfo keep-together="always" ?>\r
992                                         <title>Icon IDs for Packaging a Windows Client</title>\r
993                                         <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
994                                                 <colspec colname="keyword" colnum="1" colwidth="1.0*"/>\r
995                                                 <colspec colname="icon" colnum="2" colwidth="1.0*"/>\r
996                                                 <tbody>\r
997                                                         <row>\r
998                                                                 <entry>IDI_APPICON</entry>\r
999                                                                 <entry>Tray icon</entry>\r
1000                                                         </row>\r
1001                                                         <row>\r
1002                                                                 <entry>32512</entry>\r
1003                                                                 <entry>Default window icon</entry>\r
1004                                                         </row>\r
1005                                                 </tbody>\r
1006                                         </tgroup>\r
1007                                 </table>\r
1008                                 <para>As the <systemitem class="username">opensrf</systemitem> user\r
1009                                 execute the following commands:</para>\r
1010 <screen>\r
1011         <userinput>\r
1012         # as the opensrf user:\r
1013         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
1014         make win-client</userinput>\r
1015 </screen>\r
1016                                 <para>The output file <filename>evergreen_staff_client_setup.exe</filename> will be created.</para>\r
1017                         </simplesect>\r
1018                         <simplesect>\r
1019                                 <title>Packaging a Linux Client</title>\r
1020                                 <para>This build creates a Staff Client packaged as a compressed\r
1021                                 <literal>tar</literal> archive file with <application>XULrunner</application>\r
1022                                 already bundled with it. It requires that you already have the\r
1023                                 <application>bzip2</application> utility installed on your system.</para>\r
1024                                 <para>As the <systemitem class="username">opensrf</systemitem> user, \r
1025                                 execute the following commands:</para>\r
1026 <screen>\r
1027         <userinput>\r
1028         # as the opensrf user:\r
1029         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
1030         make linux-client</userinput>\r
1031 </screen>\r
1032                                 <para>The output file <filename>evergreen_staff_client.tar.bz2</filename> will be created.</para>\r
1033                         </simplesect>\r
1034                         <simplesect>\r
1035                                 <title>Packaging a <application>Firefox</application> Extension</title>\r
1036                                 <para>This build creates a Staff Client packaged as a <application>Firefox</application>\r
1037                                 extension. It requires that you already have the <systemitem>zip</systemitem>\r
1038                                 utility installed on your system.</para>\r
1039                                 <para>As the <systemitem class="username">opensrf</systemitem> user,\r
1040                                 execute the following commands:</para>\r
1041 <screen>\r
1042         <userinput>\r
1043         # as the opensrf user:\r
1044         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
1045         make extension</userinput>\r
1046 </screen>\r
1047                                 <para>The output file <filename>evergreen.xpi</filename> will be created.</para>\r
1048                         </simplesect>\r
1049                 </section>\r
1050                 <section xml:id="staffclientinstallation-autoupdate">\r
1051                         <title>Staff Client Automatic Updates</title>\r
1052                         <indexterm>\r
1053                                 <primary>staff client</primary>\r
1054                                 <secondary>automatic updates</secondary>\r
1055                         </indexterm>\r
1056                         <para>It is possible to set up support for automatic Staff Client updates, either during\r
1057                         the normal Evergreen server-side build process, or by manually building the Staff Client\r
1058                         with certain special options.</para>\r
1059                         <warning>\r
1060                                 <para>Automatic update server certificate requirements are more strict than\r
1061                                 normal server requirements. <application>Firefox</application> and\r
1062                                 <application>XULrunner</application> will both ignore any automatic update\r
1063                                 server that is not validated by a trusted certificate authority. Servers with\r
1064                                 exceptions added to force the Staff Client to accept them <emphasis>WILL NOT\r
1065                                 WORK</emphasis>.</para>\r
1066                                 <para>In addition, automatic updates have special requirements for the file\r
1067                                 <filename>update.rdf</filename>:</para>\r
1068                                 <orderedlist>\r
1069                                         <listitem>It must be served from an SSL server, or</listitem>\r
1070                                         <listitem>It must be signed with the  <ulink url="https://developer.mozilla.org/en/McCoy">\r
1071                                         https://developer.mozilla.org/en/McCoy</ulink> tool.</listitem>\r
1072                                 </orderedlist>\r
1073                                 <para>You can pre-install the signing key into the file\r
1074                                 <filename>install.rdf</filename> directly, or install it into a copy as\r
1075                                 <filename>install.mccoy.rdf</filename>. If the latter exists it will be copied\r
1076                                 into the build instead of the original file\r
1077                                 <filename>install.rdf</filename>.</para>\r
1078                         </warning>\r
1079                         <simplesect>\r
1080                                 <title>Autoupdate Host</title>\r
1081                                 <para>You can manually set the name of the automatic update host. If you do\r
1082                                 not set the name then, by default, the Staff Client will not include an\r
1083                                 automatic update preference. You can set the autoupdate host name as\r
1084                                 follows:</para>\r
1085                                 <itemizedlist>\r
1086                                         <listitem>\r
1087                                                 <para>At configuration time during the normal <emphasis>make install</emphasis>\r
1088                                                 process for Evergreen server-side software.</para>\r
1089                                                 <para>You can do this when you first configure the Evergreen server-side \r
1090                                                 software (see <xref linkend="serversideinstallation-configure"/>). \r
1091                                                 As the <systemitem class="username">opensrf</systemitem> user, execute \r
1092                                                 the following commands:</para>\r
1093 <screen>\r
1094         <userinput>\r
1095         # as the opensrf user:\r
1096         cd /home/opensrf/Evergreen-ILS-1.6.1.6\r
1097         ./configure --prefix=/openils --sysconfdir=/openils/conf --with-updateshost=hostname\r
1098         make</userinput>\r
1099 </screen>\r
1100                                         </listitem>\r
1101                                         <listitem>\r
1102                                                 <para>During a manual Staff Client build process.</para>\r
1103                                                 <para>You can override the variable\r
1104                                                 <envar>AUTOUPDATE_HOST=hostname</envar> and manually build the\r
1105                                                 Staff Client from the <literal>staff_client</literal>\r
1106                                                 directory (see <xref linkend="staffclientinstallation-autoupdatehost"/> \r
1107                                                 for details). If you specify only a bare hostname (for example, \r
1108                                                 <systemitem class="domainname">example.com</systemitem>) then\r
1109                                                 the Staff Client will automatically use the secure URL \r
1110                                                 <systemitem class="domainname">https://example.com</systemitem>.\r
1111                                                 If you wish to use a non-https URL, then you must explicitly \r
1112                                                 specify the full URL (for example, \r
1113                                                 <systemitem class="domainname">http://example.com</systemitem>).</para>\r
1114                                                 <para>As the <systemitem class="username">opensrf</systemitem> user,\r
1115                                                 execute the following commands to build the Staff Client (remember to\r
1116                                                 replace <emphasis>SOME_URL</emphasis> with an appropriate value):</para>\r
1117 <screen>\r
1118         <userinput>\r
1119         # as the opensrf user:\r
1120         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
1121         make AUTOUPDATE_HOST=http://SOME_URL build</userinput>\r
1122 </screen>\r
1123                                         </listitem>\r
1124                                 </itemizedlist>\r
1125                         </simplesect>\r
1126                         <simplesect>\r
1127                                 <title>Building Updates</title>\r
1128                                 <indexterm>\r
1129                                         <primary>staff client</primary>\r
1130                                         <secondary>automatic updates</secondary>\r
1131                                         <tertiary>building</tertiary>\r
1132                                 </indexterm>\r
1133                                 <para>Similar to building clients, you can use the targets\r
1134                                 <option>generic-updates</option>, <option>win-updates</option>,\r
1135                                 <option>linux-updates</option>, and <option>extension-updates</option>\r
1136                                 individually with <command>make</command> to build the update files for the\r
1137                                 Staff Client. To build all the targets at once, simply use the target\r
1138                                 <option>updates</option>.</para>\r
1139                                 <para>A full update will be built for each specified target (or for all if you\r
1140                                 use the target <option>updates</option>). For all but extensions any previous\r
1141                                 full updates (archived by default in the directory \r
1142                                 <filename class="directory">/openils/var/updates/archives</filename>) will be\r
1143                                 used to make partial updates. Partial updates tend to be much smaller and will\r
1144                                 thus download more quickly, but if something goes wrong with a partial update\r
1145                                 the full update will be used as a fallback. Extensions do not currently support\r
1146                                 partial updates.</para>\r
1147                                 <para>As the <systemitem class="username">opensrf</systemitem> user, change\r
1148                                 directory to the Staff Client source directory, then execute the following\r
1149                                 commands:</para>\r
1150 <screen>\r
1151         <userinput>\r
1152         # as the opensrf user:\r
1153         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client</userinput>\r
1154 </screen>\r
1155                                 <para>Command to build all updates at once:</para>\r
1156 <screen>\r
1157         <userinput>\r
1158         # as the opensrf user:\r
1159         make updates</userinput>\r
1160 </screen>\r
1161                                 <para>commands to build updates individually:</para>\r
1162 <screen>\r
1163         <userinput>\r
1164         # as the opensrf user:\r
1165         make generic-updates\r
1166         make win-updates\r
1167         make linux-updates\r
1168         make extension-updates</userinput>\r
1169 </screen>\r
1170                         </simplesect>\r
1171                         <simplesect>\r
1172                                 <title>Building updates with clients</title>\r
1173                                 <indexterm>\r
1174                                         <primary>staff client</primary>\r
1175                                         <secondary>automatic updates</secondary>\r
1176                                         <tertiary>building with clients</tertiary>\r
1177                                 </indexterm>\r
1178                                 <para>To save time and effort you can build updates and manual download\r
1179                                 clients at the same time by adding the phrase <literal>"-client"</literal> to each\r
1180                                 target name (for example, you could specify <option>updates-client</option> to build \r
1181                                 all the targets at once, or you could specify <option>win-updates-client</option>\r
1182                                 to build updates individually). This process will not work for the option\r
1183                                 <option>extension-updates</option>.</para>\r
1184                                 <para>The clients will be installed alongside the updates and listed on the\r
1185                                 <filename>manualupdate.html</filename> page, instead of being left in the\r
1186                                 <literal>staff_client</literal> directory.</para>\r
1187                                 <para>As the <systemitem class="username">opensrf</systemitem> user, execute\r
1188                                 one of the following commands:</para>\r
1189                                 <para>To build all updates at once:</para>\r
1190 <screen>\r
1191         <userinput>\r
1192         # as the opensrf user:\r
1193         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
1194         make updates-client</userinput>\r
1195 </screen>\r
1196                                 <para>To build updates individually:</para>\r
1197 <screen>\r
1198         <userinput>\r
1199         # as the opensrf user:\r
1200         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
1201         make generic-updates-client\r
1202         make win-updates-client\r
1203         make linux-updates-client</userinput>\r
1204 </screen>\r
1205                         </simplesect>\r
1206                         <simplesect>\r
1207                                 <title>Activating the Update Server</title>\r
1208                                 <indexterm>\r
1209                                         <primary>staff client</primary>\r
1210                                         <secondary>automatic updates</secondary>\r
1211                                         <tertiary>activating the update server</tertiary>\r
1212                                 </indexterm>\r
1213                                 <para>This section reviews scripts associated with the update server, and\r
1214                                 requires some final adjustments to file permissions.</para>\r
1215                                 <para>The Apache example configuration creates an <literal>updates</literal>\r
1216                                 directory that, by default, points to the directory \r
1217                                 <filename class="directory">/openils/var/updates/pub</filename>. This\r
1218                                 directory contains one HTML file and several specially-named script files.</para>\r
1219                                 <para>The <filename>updatedetails.html</filename> file is the fallback web\r
1220                                 page for the update details. The <filename>check</filename> script is used for\r
1221                                 <application>XULrunner</application> updates. The\r
1222                                 <filename>update.rdf</filename> script is used for extension updates. \r
1223                                 The <filename>manualupdate.html</filename> file checks for clients to provide\r
1224                                 download links when automatic updates have failed and uses the download script\r
1225                                 to force a download of the generic client XPI (compared to\r
1226                                 <application>Firefox</application> trying to install it as an\r
1227                                 extension).</para>\r
1228                                 <para>To change the permissions for the scripts\r
1229                                 <filename>check</filename>, <filename>download</filename>,\r
1230                                 <filename>manualupdate.html</filename>, and\r
1231                                 <filename>update.rdf</filename>, as the root user execute the following\r
1232                                 commands:</para>\r
1233 <screen>\r
1234         <userinput>\r
1235         # as the root user:\r
1236         cd /openils/var/updates/pub\r
1237         chmod +x  check  download  manualupdate.html  update.rdf</userinput>\r
1238 </screen>\r
1239                         </simplesect>\r
1240                 </section>\r
1241                 <section>\r
1242                         <title>Other tips</title>\r
1243                         <simplesect xml:id="staffclientinstallation-othertips">\r
1244                                 <title>Multiple workstations on one install</title>\r
1245                                 <para>Multiple workstation registrations for the same server can be accomplished\r
1246                                 with a single Staff Client install by using multiple profiles. When running\r
1247                                 <application>XULrunner</application> you can specify the option\r
1248                                 <literal>"-profilemanager"</literal> or <literal>"-P"</literal> (uppercase "P")\r
1249                                 to force the Profile Manager to start. Unchecking the <literal>"Don't ask at startup"</literal>\r
1250                                 option will make this the default.</para>\r
1251                                 <para>Once you have opened the Profile Manager you can create additional\r
1252                                 profiles, one for each workstation you wish to register. You may need to install\r
1253                                 SSL exceptions for each profile.</para>\r
1254                                 <para>When building any of the targets <option>win-client</option>,\r
1255                                 <option>win-updates-client</option>, or <option>updates-client</option>, you can\r
1256                                 specify <option>NSIS_EXTRAOPTS=-DPROFILES</option> to add an option\r
1257                                 <guimenuitem>"Evergreen Staff Client Profile Manager"</guimenuitem> to the\r
1258                                 start menu.</para>\r
1259                                 <para>As the <systemitem class="username">opensrf</systemitem> user, \r
1260                                 execute the following commands:</para>\r
1261 <screen>\r
1262         <userinput>\r
1263         # as the opensrf user:\r
1264         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client\r
1265         make NSIS_EXTRAOPTS=-DPROFILES win-client</userinput>\r
1266 </screen>\r
1267                         </simplesect>\r
1268                         <simplesect>\r
1269                                 <title> Multiple Staff Clients</title>\r
1270                                 <para>It may be confusing if you are not careful, but you can log in to\r
1271                                 multiple Evergreen servers at the same time, or a single Evergreen server\r
1272                                 multiple times. In either case you will need to create an additional profile for\r
1273                                 each additional server or workstation you want to log in as (see the previous\r
1274                                 tip in <xref linkend="staffclientinstallation-othertips"/>).</para>\r
1275                                 <para>Once you have created the profiles, run\r
1276                                 <application>XULrunner</application> with the option <option>-no-remote</option>\r
1277                                 (in addition to <option>"-profilemanger"</option> or <option>"-P"</option> if\r
1278                                 needed). Instead of <application>XULrunner</application> opening a new login\r
1279                                 window on your existing session it will start a new session instead, which can\r
1280                                 then be logged in to a different server or workstation ID.</para>\r
1281                         </simplesect>\r
1282                 </section>\r
1283         </section>\r
1284         <section xml:id="staffclientinstallation-running-staffclient">\r
1285                 <title>Running the Staff Client</title>\r
1286                 <indexterm>\r
1287                         <primary>staff client</primary>\r
1288                         <secondary>running</secondary>\r
1289                         <tertiary>linux</tertiary>\r
1290                 </indexterm>\r
1291                 <para>You can run the Staff Client on a Linux system by using the\r
1292                 <application>XULrunner</application> application (installed automatically and by default\r
1293                 with <application>Firefox</application> <literal>Version 3.0</literal> and later on \r
1294                 <systemitem class="osname">Ubuntu</systemitem> and\r
1295                 <systemitem class="osname">Debian</systemitem> distributions).</para>\r
1296                 <para>For example, if the source files for the Evergreen installation are in the directory \r
1297                 <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.6/</filename> you can start the \r
1298                 Staff Client as shown in the following example:</para>\r
1299 <screen>\r
1300         <userinput>\r
1301         # as the opensrf user:\r
1302         cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client/build\r
1303         xulrunner application.ini</userinput>\r
1304 </screen>\r
1305                 <section xml:id="staffclientinstallation-workstationnames">\r
1306                         <title>Assigning Workstation Names</title>\r
1307                         <indexterm>\r
1308                                 <primary>staff client</primary>\r
1309                                 <secondary>assigning workstation names</secondary>\r
1310                         </indexterm>\r
1311                         <para>The Staff Client must be assigned to a library and given a unique name before it\r
1312                         will connect fully to the Evergreen server. The only restriction is that the workstation's\r
1313                         name must be unique within the assigned library. Make sure to select a workstation name\r
1314                         that you will remember later, one that reflects the role, purpose, and/or location of a\r
1315                         particular computer. These names will come up later in statistical reporting, and can also\r
1316                         be handy when troubleshooting.</para>\r
1317                         <mediaobject>\r
1318                                 <alt>\r
1319                                         <phrase>Example of unconfigured Staff Client</phrase>\r
1320                                 </alt>\r
1321                                 <imageobject>\r
1322                                         <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-1.png" format="PNG" scalefit="1" width="60%"/>\r
1323                                 </imageobject>\r
1324                         </mediaobject>\r
1325                         <para>In order to assign a workstation a name, a user with appropriate\r
1326                         permissions must login to the Staff Client. In PINES, the local system\r
1327                         administrator (OPSM) has the ability to assign workstation names in their\r
1328                         library system. Library managers (LIBM's) have the ability within their\r
1329                         branch. To assign a workstation a name, login to the system. You will be\r
1330                         prompted to assign the workstation a library and a name:</para>\r
1331                         <mediaobject>\r
1332                                 <alt>\r
1333                                         <phrase>Example of configured Staff Client</phrase>\r
1334                                 </alt>\r
1335                                 <imageobject>\r
1336                                         <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-2.png" format="PNG" scalefit="1" width="60%"/>\r
1337                                 </imageobject>\r
1338                         </mediaobject>\r
1339                         <para>Select the library this workstation physically operates in from the drop\r
1340                         down menu. In this example, we have selected "MGRL-MA". Type in a friendly name\r
1341                         for the workstation. In this example, we are installing the Staff Client on the\r
1342                         director's personal system, and have named it as such. Then click\r
1343                         <guibutton>'Register'</guibutton>.</para>\r
1344                         <para>Once you have registered your workstation\r
1345                         with the server, your screen will look like this:</para>\r
1346                         <mediaobject>\r
1347                                 <alt>\r
1348                                         <phrase>Example of registered Staff Client</phrase>\r
1349                                 </alt>\r
1350                                 <imageobject>\r
1351                                         <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-3.png" format="PNG" scalefit="1" width="60%"/>\r
1352                                 </imageobject>\r
1353                         </mediaobject>\r
1354                         <para>You are now ready to log into the Staff Client for the first time. Type in\r
1355                         your password again, and click <guibutton>'Login'</guibutton>.</para>\r
1356                 </section>\r
1357                 <section xml:id="staffclientinstallation-proxy">\r
1358                         <title>Running the Staff Client Over An <systemitem class="protocal">SSH</systemitem> Tunnel</title>\r
1359                         <indexterm>\r
1360                                 <primary>staff client</primary>\r
1361                                 <secondary>running through an SSH tunnel</secondary>\r
1362                         </indexterm>\r
1363                         <para>You can configure the Staff Client to communicate with the Evergreen server over\r
1364                         an <systemitem class="protocal">SSH</systemitem> tunnel using a SOCKS 5 proxy\r
1365                         server. There are several reasons for sending network traffic for the Staff Client\r
1366                         through an <systemitem class="protocal">SSH</systemitem> proxy:</para>\r
1367                         <itemizedlist>\r
1368                                 <listitem>\r
1369                                         <para>Firewalls may prevent you from reaching the Evergreen\r
1370                                         server. This may happen when you are connecting the Staff\r
1371                                         Client to a test server that should not be available\r
1372                                         generally, or it may be the result of network design\r
1373                                         priorities other than ease of use.</para>\r
1374                                 </listitem>\r
1375                                 <listitem>\r
1376                                         <para>You may wish to improve security in situations where\r
1377                                         Staff Client traffic may be susceptible to network\r
1378                                         eavesdropping. This is especially true when staff machines\r
1379                                         connect via wireless links to the network.</para>\r
1380                                 </listitem>\r
1381                         </itemizedlist>\r
1382                         <section>\r
1383                                 <title>Setting Up an <systemitem class="protocal">SSH</systemitem> Tunnel</title>\r
1384                                 <para>You will need a server that allows you to log in via \r
1385                                 <systemitem class="protocal">SSH</systemitem> and has network access to the \r
1386                                 Evergreen server you want to reach. You will use your username and password\r
1387                                 for that <systemitem class="protocal">SSH</systemitem> server to set up a\r
1388                                 tunnel.</para>\r
1389                                 <para>For <systemitem class="osname">Windows</systemitem> users, one good\r
1390                                 solution is the open-source utility\r
1391                                 <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty/">PuTTY</ulink>,\r
1392                                 a free <systemitem class="protocal">telnet/SSH</systemitem> client.\r
1393                                 Following are instructions for setting up an <application>SSH</application> \r
1394                                 session using the <application>PuTTY</application> utility:</para>\r
1395                                 <mediaobject>\r
1396                                         <alt>\r
1397                                                 <phrase>Setting up an <systemitem class="protocal">SSH</systemitem>\r
1398                                                 tunnel in <application>PuTTY</application></phrase>\r
1399                                         </alt>\r
1400                                         <imageobject>\r
1401                                                 <imagedata fileref="../media/staffclientinstallation-proxy-putty-1.png" format="PNG" scalefit="1" width="60%"/>\r
1402                                         </imageobject>\r
1403                                 </mediaobject>\r
1404                                 <procedure>\r
1405                                         <step>\r
1406                                                 <para>Using the menu on the left, find the section:</para>\r
1407                                                 <para>\r
1408                                                         <menuchoice>\r
1409                                                                 <guimenu>Connection</guimenu>\r
1410                                                                 <guimenuitem>SSH</guimenuitem>\r
1411                                                                 <guimenuitem>Tunnels</guimenuitem>\r
1412                                                         </menuchoice>\r
1413                                                 </para>\r
1414                                         </step>\r
1415                                         <step>\r
1416                                                 <para>In the section on the right labeled <literal>"Source\r
1417                                                 port"</literal>, enter <literal>9999</literal>.</para>\r
1418                                         </step>\r
1419                                         <step>\r
1420                                                 <para>Set the checkbox <literal>"Dynamic"</literal>. Do not\r
1421                                                 enter anything in the <literal>"Destination"</literal> text\r
1422                                                 entry box.</para>\r
1423                                         </step>\r
1424                                         <step>\r
1425                                                 <para>Click <guibutton>'Add'</guibutton> and notice that\r
1426                                                 <literal>"D9999"</literal> now appears in the section\r
1427                                                 labeled <literal>"Forwarded ports"</literal>.</para>\r
1428                                         </step>\r
1429                                         <step>\r
1430                                                 <para>Use the menu on the left, find the\r
1431                                                 <literal>"Session"</literal> section, then enter the host name\r
1432                                                 of the <systemitem class="protocal">SSH</systemitem>\r
1433                                                 server.</para>\r
1434                                         </step>\r
1435                                         <step>\r
1436                                                 <para>A pop-up window will open to allow you to enter your\r
1437                                                 username and password. Once you are logged in, the tunnel is\r
1438                                                 open.</para>\r
1439                                         </step>\r
1440                                 </procedure>\r
1441                                 <para>See <ulink url="http://inside.mines.edu/~gmurray/HowTo/sshNotes.html">How to set up\r
1442                                 <systemitem class="protocal">SSH</systemitem> (for the beginner)</ulink> for information on\r
1443                                 setting up <systemitem class="protocal">SSH</systemitem> for other client operating\r
1444                                 systems.</para>\r
1445                         </section>\r
1446                         <section>\r
1447                                 <title>Configuring the Staff Client to Use the <systemitem class="protocal">SSH</systemitem> Tunnel</title>\r
1448                                 <para>In order to tell the Staff Client that all traffic should be sent\r
1449                                 through the <systemitem class="protocal">SSH</systemitem> tunnel just configured,\r
1450                                 you must find edit the file <filename>all.js</filename>, usually located at\r
1451                                 <filename>C:\Program Files\Evergreen Staff Client\greprefs\all.js</filename>\r
1452                                  on a  <systemitem class="osname">Windows</systemitem> system.\r
1453                                 Search this file for the word <literal>socks</literal> to find the appropriate\r
1454                                 section for the following changes.</para>\r
1455                                 <mediaobject>\r
1456                                         <alt>\r
1457                                                 <phrase>The SOCKS section of "all.js" before changes</phrase>\r
1458                                         </alt>\r
1459                                         <imageobject>\r
1460                                                 <imagedata fileref="../media/staffclientinstallation-proxy-socks-1.png" format="PNG" scalefit="1" width="70%"/>\r
1461                                         </imageobject>\r
1462                                 </mediaobject>\r
1463                                 <para>Make the following changes:</para>\r
1464                                 <itemizedlist>\r
1465                                         <listitem>\r
1466                                                 <para>Change the value of <literal>network.proxy.socks</literal> \r
1467                                                 from <literal>""</literal> to <literal>localhost</literal>.</para>\r
1468                                         </listitem>\r
1469                                         <listitem>\r
1470                                                 <para>Change the value of <literal>network.proxy.socks_port</literal>\r
1471                                                 from <literal>0</literal> to <literal>9999</literal>.</para>\r
1472                                         </listitem>\r
1473                                 </itemizedlist>\r
1474                                 <mediaobject>\r
1475                                         <alt>\r
1476                                                 <phrase>The SOCKS section of "all.js" after changes</phrase>\r
1477                                         </alt>\r
1478                                         <imageobject>\r
1479                                                 <imagedata fileref="../media/staffclientinstallation-proxy-socks-2.png" format="PNG" scalefit="1" width="70%"/>\r
1480                                         </imageobject>\r
1481                                 </mediaobject>\r
1482                                 <para>If everything is working correctly, you should now be able to run \r
1483                                 the Staff Client and all its data will be sent encrypted through the \r
1484                                 <systemitem class="protocal">SSH</systemitem> tunnel you have just configured.</para>\r
1485                         </section>\r
1486                 </section>\r
1487                 <section>\r
1488                         <title>Navigating a Tabbed Interface</title>\r
1489                         <para>Like many popular current web browsers and other applications, the Staff Client\r
1490                         uses a "tabbed" interface. Tabs allow you to have several pages open at the same time\r
1491                         in a single window. This is easier to manage on your computer screen than multiple\r
1492                         windows, since you can easily switch between tabs in the same window.</para>\r
1493                         <mediaobject>\r
1494                                 <alt>\r
1495                                         <phrase>Tabs in the Staff Client window</phrase>\r
1496                                 </alt>\r
1497                                 <imageobject>\r
1498                                         <imagedata fileref="../media/staffclientinstallation-tabbed-1.png" format="PNG" scalefit="1" width="70%"/>\r
1499                                 </imageobject>\r
1500                         </mediaobject>\r
1501                         <para>The "tabs" appear below the menu bar in the Staff Client with a descriptive\r
1502                         title. Simply select a tab to bring it to the front and view the page displayed in the\r
1503                         tab. You can use tabs to have access to multiple things all at the same time: patron\r
1504                         records and searches, bibliographic records and searches, circulation or cataloging\r
1505                         interfaces - anything at all in the Staff Client.</para>\r
1506                         <itemizedlist>\r
1507                                 <listitem>Create a new tab by pressing\r
1508                                 <keycombo>\r
1509                                         <keycap>Ctrl</keycap>\r
1510                                         <keycap>T</keycap>\r
1511                                 </keycombo>\r
1512                                 on the keyboard or selecting:\r
1513                                 <menuchoice>\r
1514                                         <guimenu>File</guimenu>\r
1515                                         <guimenuitem>New Tab</guimenuitem>\r
1516                                 </menuchoice>\r
1517                                 from the menu.</listitem>\r
1518                                 <listitem>Close a tab by pressing\r
1519                                 <keycombo>\r
1520                                         <keycap>Ctrl</keycap>\r
1521                                         <keycap>W</keycap>\r
1522                                 </keycombo> on the keyboard or selecting\r
1523                                 <menuchoice>\r
1524                                         <guimenu>File</guimenu>\r
1525                                         <guimenuitem>Close Tab</guimenuitem>\r
1526                                 </menuchoice>\r
1527                                 from the menu.</listitem>\r
1528                                 <listitem>Switch tabs by pressing \r
1529                                 <keycombo>\r
1530                                         <keycap>Ctrl</keycap>\r
1531                                         <keycap>Tab</keycap>\r
1532                                 </keycombo>\r
1533                                 on the keyboard or selecting the tab in the tab bar.</listitem>\r
1534                         </itemizedlist>\r
1535                 </section>\r
1536         </section>\r
1537 </chapter>\r