From edc2f2fb36498b275e49114145a1030c8cf2a658 Mon Sep 17 00:00:00 2001 From: Kyujung Lim Date: Mon, 22 Aug 2011 16:58:28 -0400 Subject: [PATCH] Added staffclientinstallation.xml with old 1.6 content for now --- 2.0/admin/staffclientinstallation.xml | 1537 +++++++++++++++++++++++++++++++++ 1 file changed, 1537 insertions(+) create mode 100644 2.0/admin/staffclientinstallation.xml diff --git a/2.0/admin/staffclientinstallation.xml b/2.0/admin/staffclientinstallation.xml new file mode 100644 index 0000000000..fc3ad5b12f --- /dev/null +++ b/2.0/admin/staffclientinstallation.xml @@ -0,0 +1,1537 @@ + + + + Installation of Evergreen Staff Client Software + + This section describes installation of the Evergreen Staff Client software. + + +
+ Installing the Staff Client + + staff client + installing + +
+ Installing a Pre-Built Staff Client + A pre-built Staff Client is available for Windows, + Mac or Linux systems. Installing the Staff Client in + each of these environments is described in the following sections. +
+ Installing on <systemitem class="osname">Windows</systemitem> + + staff client + installing + Windows + + In this section we describe the process of installing the Staff Client on the + Microsoft Windows operating system. + Visit the downloads section of the Evergreen website at + http://www.evergreen-ils.org/downloads.php + and find the standard Microsoft Windows Installer + that contains the current version of the Staff Client. Download the Installer, then run + it. A screen that looks similar to this should appear: + + + Running the Staff Client installer + + + + + + Click 'Next' to continue through the guided install + process. The Install Wizard will ask you to agree to the end-user license, ask you where + to install the software, ask about where to place icons, and then will automatically + install the software on your workstation. + When you run the Staff Client for the first time, a screen similar to this should + appear: + + + Running the Staff Client for the first time + + + + + + First, add the name of your Evergreen server to the field + Hostname in the Server + section. For example, the PINES demo system is + http://demo.gapines.org. + After adding the server name, click 'Re-Test Server'. + Because this is the initial run of the Staff Client, you will see a warning in the + upper-right saying: Not yet configured for the specified + server. The first thing you must do to the Staff Client on every workstation + is to assign it a workstation name. This is covered in + . + Users must have the REGISTER_WORKSTATION permission and be assigned the appropriate working location(s) in order to + register a workstation. + To add working locations to a user’s account: + + + Retrieve the user through a patron search and select OtherUser Permission + Editor and select the boxes for the locations necessary. + Save the user record. + + Making modifications to Working Locations while changing permission settings does not work – when this + workflow is performed, permission changes will not be applied to the database. + + + + Alternately, from the Admin menu, select User Permission Editor and retrieve the user by + barcode. + Make changes to working locations as described above. + + +
+
+ Installing on <systemitem class="osname">Mac OS</systemitem> + + staff client + installing + Mac OS + + This section describes Mac OS + packages and related versions of XULrunner that can + be used to run the Staff Client in a Mac OS + environment. + + Evergreen Version 1.2.3.0 + + + A Mac OS package that + contains an early version of the Staff Client (version 1.2.3.0) for use + with XULrunner is available. You can find + current releases of XULrunner here: + + http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases . + Download and install the latest version. You can find further information + about XULrunner here: + + https://developer.mozilla.org/en/xulrunner. + Note that later versions of XULrunner + (e.g., version 1.9.2.13) have replaced version 1.8.0.4, which has known + security holes and is not recommended for applications that deal with + public web content. + + + A Mac OS + Installation package for Staff Client version 1.2.3.0 is + available from Evergreen Indiana. Download and install it from + here: + + evergreen_osx_staff_client_1_2_3.zip . + + + + To upgrade to a more recent version of the Staff Client, you can + copy the build directory from a + working Windows installation of + the desired version of the Staff Client to your + Mac. + The required files may be located in a directory like this on the + Windows machine: + C:\Program Files\Evergreen Staff Client\build. + Copy these files to the Resources + folder within the Open-ILS package in your + Applications directory on the Mac, + overwriting files with the same names. + + Drag the application's icon to your toolbar for easier + access. + + When you run the Staff Client installer, a screen will appear that looks + similar to this: + + + Running the Staff Client installer for + Mac OS + + + + + + Click 'Continue', accept the license, then finish the + installation. The application will be located at the destination you selected + during installation. You will then be able to drag the application into your + toolbar for easier access. + + + Finishing the installation + + + + + + + + Running directly using <application>XULrunner</application> + + staff client + XULRunner + + You must install an appropriate version of XULrunner + to match the Evergreen version. See the following table for the recommended version of + XULrunner: + + + Evergreen / <application>XULrunner</application> Dependencies + + + + + + Evergreen Version + XULRunner Version + + + + + Evergreen 1.6.x.x + XULrunner 1.9.x.x + + + Evergreen 1.4.x.x + XULrunner 1.8.0.4 or XULrunner 1.8.0.3 + + + Evergreen 1.2.x.x + XULrunner 1.8.0.4 or XULrunner 1.8.0.3 + + + +
+ If you have issues removing previously installed + XULrunner versions see + + for further information. + The Staff Client data from the directory + ./staff_client/build must be placed + somewhere on the machine (e.g. + ~/Desktop/Evergreen_Staff_Client). + Remember to call XULrunner with the full path to the + binary, followed by the install command and the path to the client data: + + + /Library/Frameworks/XUL.framework/xulrunner-bin --install-app ~/Desktop/Evergreen_Staff_Client + + The command should exit quietly and will create the folder + /Applications/OpenILS, + containing a launcher named open_ils_staff_client. + + + (OPTIONAL) Removing previously installed XULRunner versions + + XULRunner + removing previous versions + + If you already have a newer version of + XULrunner installed, per the release notes, + you will need to remove the entire directory + /Library/Frameworks/XUL.framework + before downgrading. + In addition, you may also need to remove the previous file + /Library/Receipts/xulrunner-ver-mak.pkg . + If file /Library/Receipts/xulrunner-ver-mak.pkg does + not exist (possibly in newer Mac OS + releases), you need to flush the file receiptdb. + If you install a newer version of XULrunner + over a previous (older) install, the older install is not removed but the + symlinks are changed to the newer one. + + + (OPTIONAL) Flush Receiptdb file: + First, get the package identifier, then purge/forget the build that was + initially installed: + + + sudo pkgutil --pkgs > /tmp/pkgs.txt + sudo pkgutil --forget org.mozilla.xulrunner + + It may not be necessary to edit the file + /Library/Receipts/InstallHistory.plist after deleting the + folder XUL.framework. See + + http://lists.apple.com/archives/Installer-dev/2009/Jul/msg00008.html + for more information. + + + Creating an APP file: Staff Client and <application>XULrunner</application> Bundled + An APP file is basically a folder. Start with a folder stucture like this: + + + Evergreen.app + __Contents + ____Frameworks + ____Resources + ____MacOS + + Create an APP folder structure with the following commands: + + + mkdir -p Evergreen.app/Contents/Frameworks + mkdir -p Evergreen.app/Contents/Resources + mkdir -p Evergreen.app/Contents/MacOS + + + + Create a new file in the folder + Evergreen.app/Contents/Info.plist + containing the following data (adjust for your version of + Evergreen): + + + + + CFBundleExecutable + xulrunner + CFBundleGetInfoString + OpenILS open_ils_staff_client rel_1_6_1_6 + CFBundleInfoDictionaryVersion + 6.0 + CFBundleName + Evergreen Staff Client + CFBundlePackageType + APPL + CFBundleShortVersionString + rel_1_6_1_6 + CFBundleVersion + rel_1_6_1_6.rel_1_6_1_6 + NSAppleScriptEnabled + + CFBundleTypeIconFile + Evergreen.icns + + +]]> + + Download and install an appropriate + Mac OS package of + XULrunner from the Mozilla website + + https://developer.mozilla.org/en/xulrunner (see + for recommendations). + + Make a copy of the folder + /Library/Frameworks/XUL.Framework + inside your APP file. It should look something like this: + + + Evergreen.app/ + __Contents/ + ____Frameworks/ + ______XUL.Framework/ + ______Versions/ + ________Current -> 1.9.1.3 (symlink) + ________1.9.1.3/ + ______XUL -> Versions/Current/XUL + ______libxpcom.dylib -> Versions/Current/libxpcom.dylib + ______xulrunner-bin -> Versions/Current/xulrunner-bin + + + Copy + XUL.Framework/Versions/Current/xulrunner into the + folder Evergreen.app/MacOS + (do not symlink; copy the file). + + Make Evergreen.app/Resources the root + of your Evergreen application files like this: + + + Evergreen.app/ + __Contents/ + ____Resources/ + ______BUILD_ID + ______application.ini + ______chrome/ + ______components/ + ______etc. + + + Put a Mac + format icon file named Evergreen.icns in + Resources. + + +
+
+ Installing on Linux + + Quick Upgrade of the Staff Client + A Linux Staff Client is automatically built on the server as part of the + normal make install process for Evergreen server-side + software. To upgrade the Staff Client on a remote Linux workstation with a new + version, just copy the directory tree containing the Staff Client from your + server to the remote workstation. + Execute the following commands, replacing USER, + WORKSTATION, and SOME_PATH with + appropriate values: + + + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + scp -r ./build USER@WORKSTATION:/SOME_PATH/ + + You should test the newly copied Staff Client on the remote workstation. + Log into the workstation and execute the following command: + + + xulrunner /SOME_PATH/build/application.ini + + + + Building the Staff Client on the Server + + staff client + building on the server + + A Linux Staff Client is automatically built on the server as part of the + normal make install process for Evergreen server-side + software. See for details of + the build process. + In order to install a compatible Staff Client on another Linux system, you + can copy the appropriate files from the Staff Client build directory on your + server to the new Linux system. You could manually build the Staff Client on the + new system, but you must ensure that the BUILD_ID you chose on + the server matches the BUILD_ID for each Staff Client you use on + other systems. + If you wish to use a pre-packaged Windows + version on some systems, you may want to choose the BUILD_ID on + both server and other versions to match that of the + Windows Staff Client. To determine which + BUILD_ID was used for existing Staff Client installations, + execute each Staff Client and click the 'About this Client' + button. + If you are allowed to make changes on the Evergreen server, another option + is to create a symbolic link. In order for a copy of the Staff Client and server + to work together, the BUILD_ID must match the name of the + directory containing the server components of the Staff Client, or the name of a + symbolic link to that directory. As the + root user, make the changes as follows: + + + # as the root user: + cd /openils/var/web/xul + ln -s SERVER_BUILD_ID/ CLIENT_BUILD_ID + + + + Building the Staff Client on a Client Machine + This section is directed toward end-users who wish to use Linux rather than + Windows for client machines, but have limited + Linux experience. You can build the Staff Client on a Linux system without installing the + Evergreen Server component. This is a relatively simple process compared to server + installation, but does require some command-line work. The following instructions are + for building Staff Client version 1.2.1.4 on + Kubuntu 7.10; modify them as needed for + other distributions (the instructions should work as-is for + Ubuntu or + Ubuntu derivatives). + + + Prerequisites + Both subversion and + XULrunner are required to build the Staff + Client. As the root user, + use apt-get to install packages for + subversion and + XULrunner. You can also use + synaptic, the graphical user interface for + apt-get. For subversion, + select the latest version; for XULrunner, + select version 1.8.1.4-2ubuntu5. + + + # as the root user: + sudo apt-get install subversion + sudo apt-get install xulrunner + + + + Download the Source Code + + + Determine which version is needed + For most end-users, a specific version is required + to communicate properly with the Evergreen server. Check + with your system administrator, IT person, or HelpDesk to + determine which Staff Client versions are + supported. + Next, you need to determine which + tag to use when downloading the + source code. Tags are markers in the source code to create + a snapshot of the code as it existed at a certain time; + tags usually point to tested and stable code, or at least + a community-recognized release version. + To determine which tag to use, browse to + + http://svn.open-ils.org/trac/ILS/browser. + Look in the Visit drop-down box; see + the list of Branches and, further + down, a list of Tags. You may have + to do some guesswork, but it is fairly straightforward to + determine which tag to use. If the server is version + 1.6.1.6, you will want to use the tag that looks most + appropriate. For example, as you look through the tag + list, notice the tag named 'rel_1_6_1_6'. This is the tag + you need; make a note of it for the next step. + + + Download the Code + As the + opensrf + user, open a terminal (command-line prompt) and navigate + to the directory in which you wish to download the Staff + Client. Use the following commands to download the proper + version of the source code by tag name: + + + # as the opensrf user: + cd /DOWNLOAD/DIRECTORY + svn co rel_1_6_1_6/ + + Remember to change "rel_1_6_1_6" to the appropriate + tag for your installation. + + + + + Build the Staff Client + In the following example, navigate to the directory in + which the source code was downloaded, then navigate to the + proper subdirectory and run the "make" utility to actually build + the Staff Client. Remember to check with your system + administrator about which Staff Client BUILD_ID + to use. The server checks the Staff Client + BUILD_ID against itself to determine whether or + not a connecting client is supported. For instance, for the + PINES installation (version 1.6.1.6) the supported + BUILD_ID is "rel_1_6_1_6". Modify the following + commands accordingly. + As the opensrf + user, run the following commands to build the Staff Client: + + + # as the opensrf user: + wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.6.tar.gz + tar xfz Evergreen-ILS-1.6.1.6.tar.gz + cd /home/opensrf/Evergreen-ILS-1.6.1.6 + ./configure --prefix=/openils --sysconfdir=/openils/conf + cd ./Open-ILS/xul/staff_client/ + make STAFF_CLIENT_BUILD_ID='rel_1_6_1_6' install + + + + Run the Staff Client + As the opensrf + user, navigate to the build/ + subdirectory and run the following command: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client/build + xulrunner application.ini + + + + (OPTIONAL) Clean Up / Create Shortcuts + The source code download included many files that are + needed to build the Staff Client but are not necessary to run + it. You may wish to remove them to save space, or to create a + clean staging directory containing the + finished Staff Client that can then be copied to other + machines. To do this, execute the following commands (remember + to replace DOWNLOAD_DIRECTORY and + STAGING_DIRECTORY with the appropriate + paths): + + + # as the opensrf user: + mkdir ~/STAGING_DIRECTORY + cd ~/DOWNLOAD_DIRECTORY/Open-ILS/xul/ + cp -r staff_client ~/STAGING_DIRECTORY + + Test the Staff Client to verify that all necessary files + were copied to the staging directory: + + + # as the opensrf user: + cd ~/STAGING_DIRECTORY/staff_client/build + xulrunner application.ini + + If there were no problems, then finish the cleanup by + removing the original download directory as shown: + + + # as the opensrf user: + rm -r -f ~/DOWNLOAD_DIRECTORY + + Finally, the command: + + + # as the opensrf user: + xulrunner ~/STAGING_DIRECTORY/staff_client/build/application.ini + + will now run the Staff Client. You may wish to create a + shortcut for the Staff Client. To do so, use the previous + command as the target for the shortcut: + + Desktop + StartMenu + K-Menu + + + + + + Using Wine to Install on Linux + + staff client + using wine to install on Linux + + The Linux application Wine is another + alternative if you wish to install the packaged + Windows versions rather than manually + building the Staff Client. Wine is a Linux + application that allows users to directly run + Windows executables, and is a simple + way for casual Linux users to use the Staff Client. You can find more information + about Wine at + + http://www.winehq.org/site/docs/wineusr-guide/getting-wine. + As the root user, use + apt-get to install the package for Wine. + You can also use synaptic, the graphical user interface. + + + Install wine: + + + # as the root user: + sudo apt-get install wine + + + + Visit the downloads section of the Evergreen website at + + http://www.evergreen-ils.org/downloads.php and find the + Microsoft Windows Installer + that contains the desired version of the Staff Client. Download + the installer and place it in a temporary directory. + + + As the opensrf + user, navigate to the temporary directory where you downloaded + the Windows installer + file, then execute it with the wine + application (remember to replace VERSION with + the release number of the Staff Client you downloaded): + + + # as the opensrf user: + cd /TEMP_DIRECTORY + wine evergreen-setup-rel_VERSION.exe + + If this step fails, you may need to configure + Wine first to properly emulate + Windows XP. To do so, + type winecfg from the command line; in the + Applications tab of the window that pops up, + select Default Settings and choose + Windows XP from the drop-down menu, then + click 'Apply'. + + + Launch the Staff Client + A new entry for the Staff Client should now appear + somewhere in the All Applications menu of + your Linux desktop. You may also find a new desktop shortcut for + the Staff Client. To launch the Staff Client, visit the + All Applications menu on your desktop and + find the section similar to: + + + Wine + Program Files + Evergreen Staff Client + Evergreen Staff Client + , + + or else launch the Staff Client from the new desktop shortcut. + + + +
+
+
+ Building the Staff Client + + staff client + building + + You can also manually build the Staff Client by using the make + utility in the Staff Client source directory (e.g., the directory + /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + for the current Evergreen version). There are a number of possible options to manually + build special versions of the Staff Client on a Linux system. Following is a list of + variables that you can pass to make to influence the manual build + process: + + + Build Variable <envar>STAFF_CLIENT_BUILD_ID</envar> + During the normal make install Evergreen server-side + software build process, the variable defaults to an automatically generated + date/time string, but you can also override the value of BUILD_ID. + You could use the following commands during the normal install process: + + + # as the root user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6 + make STAFF_CLIENT_BUILD_ID=1_6_1_6 install + + You can also manually build the Staff Client in the Staff Client + source directory with a different BUILD_ID. + As the opensrf user, + execute the following commands to build the Staff Client (remember to replace + NEW_VERSION with an appropriate value): + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make STAFF_CLIENT_BUILD_ID=NEW_VERSION build + + + + + Build Variable <envar>STAFF_CLIENT_VERSION</envar> + During the normal make install Evergreen server-side + software build process, the variable is pulled automatically from a README file + in the Evergreen source root. The variable defaults to + 0trunk.revision, where the value of "revision" is + automatically generated. You can override the value of VERSION + similarly to the BUILD_ID. + You could use the following commands during the normal install process: + + + # as the root user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6 + make STAFF_CLIENT_VERSION=0mytest.200 install + + You can also manually build the Staff Client in the Staff Client + source directory with a different VERSION. + If you plan to make extensions update automatically, the + VERSION needs to conform to the format recommended in + + Toolkit Version Format and newer versions need to be "higher" than older + versions. + As the opensrf user, + execute the following commands to build the Staff Client: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make STAFF_CLIENT_VERSION=0mytest.200 build + + + + + Build Variable <envar>STAFF_CLIENT_STAMP_ID</envar> + During the normal make install Evergreen + server-side software build process, the variable is generated from + STAFF_CLIENT_VERSION. You may want to have multiple versions + of the Staff Client with different stamps, possibly for different uses or + client-side customizations. You can override the value of + STAMP_ID similarly to the BUILD_ID. + You could use the following commands during the normal install process: + + + # as the root user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6 + make STAFF_CLIENT_STAMP_ID=my_test_stamp install + + You can also manually build the Staff Client in the Staff Client + source directory with a different STAMP_ID. + As the opensrf user, + execute the following commands to build the Staff Client: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make STAFF_CLIENT_STAMP_ID=my_test_stamp build + + +
+
+ Advanced Build Options + + staff client + building + advanced build options + + In addition to the basic options listed above, there are a number of advanced + options for building the Staff Client. Most are target names for the + make utility and require that you build the Staff Client from the + staff_client directory. See the following table for a list of + possible make target keywords: + + Keywords For Advanced Build Options + + + + + + + Keyword + Description + + + + + clients + Runs "make win-client", "make linux-client", and "make + generic-client" individually + + + client_dir + Builds a client directory from the build directory, without + doing a rebuild. The same as "copy everything but + server/". + + + client_app + Prerequisite "client_dir"; removes "install.rdf" from + client directory so an APP bundle can't be installed as an + extension + + + client_ext + Prerequisite "client_dir"; remove "application.ini", + "autoupdate.js", "standalone_xul_app.js" from client directory so + an extension won't break Firefox + + + extension + Prerequisite "client_ext"; rewritten to use "client_ext" + + + generic-client + Prerequisite "client_app"; makes an XPI file suitable for + use with "xulrunner --install-app"" + + + win-xulrunner + Prerequisite "client_app"; adds Windows xulrunner to client build + + + linux-xulrunner + Prerequisite "client_app"; adds Linux xulrunner to client build + + + win-client + Prerequisite "win-xulrunner"; builds "setup exe" (requires + that "nsis" package be installed, will add options for automatic + update if configured and developer options if client build was a + "make devbuild") + + + linux-client + Prerequisite "linux_xulrunner"; builds a "tar.bz2" bundle + of the Linux client + + + [generic-|win-|linux-|extension-]updates[-client] + Calls external/make_updates.sh to build full and partial + updates generic/win/linux/extension prefix limit to that + distribution; Adding builds clients and + copies them to a subdirectory of the + updates directory as well; + doesn't exist. + + + +
+ Following are descriptions of other special build options: + + Developer Build + You can create a so-called developer build + of the Staff Client by substituting for + when running make from the + staff_client directory. The build will contain an + extra configuration file that enables some developer options. + As the opensrf user, run + the following commands from the Staff Client source directory: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make devbuild + + + + Compressed Javascript + You can execute the Google Closure Compiler + utility to automatically review and compress Javascript code after the build + process completes, by substituting for + when running make. + For more information on the Google Closure Compiler, see + + http://code.google.com/closure/compiler. + As the opensrf user, run + the following commands from the Staff Client source directory: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make compress-javascript + + You can also combine Javascript review and compression, and also perform a + developer build. + As the opensrf user, run + the following make command from the Staff Client source directory + (the order of options is important): + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make devbuild compress-javascript + + + + Automatic Update Host + You can override the host used to check for automatic Staff Client updates + by specifying the option. + You could use the following commands during the normal install process: + + + # as the root user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6 + make AUTOUPDATE_HOST=localhost install + + You can manually build the Staff Client in the Staff Client + source directory and set to enable automatic + update checking. + As the opensrf user, + execute the following commands to build the Staff Client: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make AUTOUPDATE_HOST=localhost build + + For more information on Automatic Updates, see + . + +
+
+ Installing and Activating a Manually Built Staff Client + The Staff Client is automatically built, installed and activated as part of the + normal make process for Evergreen + server-side software. However, if you manually build the Staff Client from the + staff_client directory, then you need to take additional steps to + properly install and activate it. You also have the option of installing the Staff + Client on the same machine it was built on, or on a different machine. + Assuming you have already built the Staff Client, and that your installation is + in the directory /openils/var/web/xul, as the + opensrf user execute the following + commands: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + mkdir -p "/openils/var/web/xul/$(cat build/BUILD_ID)" + cp -R build/server "/openils/var/web/xul/$(cat build/BUILD_ID)" + +
+
+ Packaging the Staff Client + Once you have built the Staff Client, you can create several forms of special client + packages by using a modified make command in the staff_client + directory. + + Packaging a Generic Client + This build creates a Staff Client packaged as an XPI file suitable for use with + the parameter of XULrunner. + It requires that you already have the zip utility + installed on your system. + As the opensrf user, execute + the following commands: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make generic-client + + The output file evergreen_staff_client.xpi will be created. + + + Packaging a <systemitem class="osname">Windows</systemitem> Client + This build creates a Staff Client packaged as a + Windows executable. It requires that + you already have the unzip utility installed on + your system. It also requires that you install + NSIS (Nullsoft Scriptable Install System), + a professional open source utility package used to create + Windows installers (the + "makensis" utility is installed as part of the + "nsis" package). You should use Version 2.45 or + later. + If you wish for the Staff Client to have a link icon/tray icon by + default, you may wish to provide a pre-modified + xulrunner-stub.exe. Place it in the Staff Client + source directory and make will automatically use it instead + of the one that comes with the downloaded XULrunner + release. The version of xulrunner-stub.exe need not + match exactly. + You can also use a tool such as + Resource Hacker + to embed icons. Resource Hacker is an open-source + utility used to modify resources within 32-bit + Windows executables. + Some useful icon ID strings include the following: + + + Icon IDs for Packaging a Windows Client + + + + + + IDI_APPICON + Tray icon + + + 32512 + Default window icon + + + +
+ As the opensrf user + execute the following commands: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make win-client + + The output file evergreen_staff_client_setup.exe will be created. + + + Packaging a Linux Client + This build creates a Staff Client packaged as a compressed + tar archive file with XULrunner + already bundled with it. It requires that you already have the + bzip2 utility installed on your system. + As the opensrf user, + execute the following commands: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make linux-client + + The output file evergreen_staff_client.tar.bz2 will be created. + + + Packaging a <application>Firefox</application> Extension + This build creates a Staff Client packaged as a Firefox + extension. It requires that you already have the zip + utility installed on your system. + As the opensrf user, + execute the following commands: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make extension + + The output file evergreen.xpi will be created. + +
+
+ Staff Client Automatic Updates + + staff client + automatic updates + + It is possible to set up support for automatic Staff Client updates, either during + the normal Evergreen server-side build process, or by manually building the Staff Client + with certain special options. + + Automatic update server certificate requirements are more strict than + normal server requirements. Firefox and + XULrunner will both ignore any automatic update + server that is not validated by a trusted certificate authority. Servers with + exceptions added to force the Staff Client to accept them WILL NOT + WORK. + In addition, automatic updates have special requirements for the file + update.rdf: + + It must be served from an SSL server, or + It must be signed with the + https://developer.mozilla.org/en/McCoy tool. + + You can pre-install the signing key into the file + install.rdf directly, or install it into a copy as + install.mccoy.rdf. If the latter exists it will be copied + into the build instead of the original file + install.rdf. + + + Autoupdate Host + You can manually set the name of the automatic update host. If you do + not set the name then, by default, the Staff Client will not include an + automatic update preference. You can set the autoupdate host name as + follows: + + + At configuration time during the normal make install + process for Evergreen server-side software. + You can do this when you first configure the Evergreen server-side + software (see ). + As the opensrf user, execute + the following commands: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6 + ./configure --prefix=/openils --sysconfdir=/openils/conf --with-updateshost=hostname + make + + + + During a manual Staff Client build process. + You can override the variable + AUTOUPDATE_HOST=hostname and manually build the + Staff Client from the staff_client + directory (see + for details). If you specify only a bare hostname (for example, + example.com) then + the Staff Client will automatically use the secure URL + https://example.com. + If you wish to use a non-https URL, then you must explicitly + specify the full URL (for example, + http://example.com). + As the opensrf user, + execute the following commands to build the Staff Client (remember to + replace SOME_URL with an appropriate value): + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make AUTOUPDATE_HOST=http://SOME_URL build + + + + + + Building Updates + + staff client + automatic updates + building + + Similar to building clients, you can use the targets + , , + , and + individually with make to build the update files for the + Staff Client. To build all the targets at once, simply use the target + . + A full update will be built for each specified target (or for all if you + use the target ). For all but extensions any previous + full updates (archived by default in the directory + /openils/var/updates/archives) will be + used to make partial updates. Partial updates tend to be much smaller and will + thus download more quickly, but if something goes wrong with a partial update + the full update will be used as a fallback. Extensions do not currently support + partial updates. + As the opensrf user, change + directory to the Staff Client source directory, then execute the following + commands: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + + Command to build all updates at once: + + + # as the opensrf user: + make updates + + commands to build updates individually: + + + # as the opensrf user: + make generic-updates + make win-updates + make linux-updates + make extension-updates + + + + Building updates with clients + + staff client + automatic updates + building with clients + + To save time and effort you can build updates and manual download + clients at the same time by adding the phrase "-client" to each + target name (for example, you could specify to build + all the targets at once, or you could specify + to build updates individually). This process will not work for the option + . + The clients will be installed alongside the updates and listed on the + manualupdate.html page, instead of being left in the + staff_client directory. + As the opensrf user, execute + one of the following commands: + To build all updates at once: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make updates-client + + To build updates individually: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make generic-updates-client + make win-updates-client + make linux-updates-client + + + + Activating the Update Server + + staff client + automatic updates + activating the update server + + This section reviews scripts associated with the update server, and + requires some final adjustments to file permissions. + The Apache example configuration creates an updates + directory that, by default, points to the directory + /openils/var/updates/pub. This + directory contains one HTML file and several specially-named script files. + The updatedetails.html file is the fallback web + page for the update details. The check script is used for + XULrunner updates. The + update.rdf script is used for extension updates. + The manualupdate.html file checks for clients to provide + download links when automatic updates have failed and uses the download script + to force a download of the generic client XPI (compared to + Firefox trying to install it as an + extension). + To change the permissions for the scripts + check, download, + manualupdate.html, and + update.rdf, as the root user execute the following + commands: + + + # as the root user: + cd /openils/var/updates/pub + chmod +x check download manualupdate.html update.rdf + + +
+
+ Other tips + + Multiple workstations on one install + Multiple workstation registrations for the same server can be accomplished + with a single Staff Client install by using multiple profiles. When running + XULrunner you can specify the option + "-profilemanager" or "-P" (uppercase "P") + to force the Profile Manager to start. Unchecking the "Don't ask at startup" + option will make this the default. + Once you have opened the Profile Manager you can create additional + profiles, one for each workstation you wish to register. You may need to install + SSL exceptions for each profile. + When building any of the targets , + , or , you can + specify to add an option + "Evergreen Staff Client Profile Manager" to the + start menu. + As the opensrf user, + execute the following commands: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client + make NSIS_EXTRAOPTS=-DPROFILES win-client + + + + Multiple Staff Clients + It may be confusing if you are not careful, but you can log in to + multiple Evergreen servers at the same time, or a single Evergreen server + multiple times. In either case you will need to create an additional profile for + each additional server or workstation you want to log in as (see the previous + tip in ). + Once you have created the profiles, run + XULrunner with the option + (in addition to or if + needed). Instead of XULrunner opening a new login + window on your existing session it will start a new session instead, which can + then be logged in to a different server or workstation ID. + +
+
+
+ Running the Staff Client + + staff client + running + linux + + You can run the Staff Client on a Linux system by using the + XULrunner application (installed automatically and by default + with Firefox Version 3.0 and later on + Ubuntu and + Debian distributions). + For example, if the source files for the Evergreen installation are in the directory + /home/opensrf/Evergreen-ILS-1.6.1.6/ you can start the + Staff Client as shown in the following example: + + + # as the opensrf user: + cd /home/opensrf/Evergreen-ILS-1.6.1.6/Open-ILS/xul/staff_client/build + xulrunner application.ini + +
+ Assigning Workstation Names + + staff client + assigning workstation names + + The Staff Client must be assigned to a library and given a unique name before it + will connect fully to the Evergreen server. The only restriction is that the workstation's + name must be unique within the assigned library. Make sure to select a workstation name + that you will remember later, one that reflects the role, purpose, and/or location of a + particular computer. These names will come up later in statistical reporting, and can also + be handy when troubleshooting. + + + Example of unconfigured Staff Client + + + + + + In order to assign a workstation a name, a user with appropriate + permissions must login to the Staff Client. In PINES, the local system + administrator (OPSM) has the ability to assign workstation names in their + library system. Library managers (LIBM's) have the ability within their + branch. To assign a workstation a name, login to the system. You will be + prompted to assign the workstation a library and a name: + + + Example of configured Staff Client + + + + + + Select the library this workstation physically operates in from the drop + down menu. In this example, we have selected "MGRL-MA". Type in a friendly name + for the workstation. In this example, we are installing the Staff Client on the + director's personal system, and have named it as such. Then click + 'Register'. + Once you have registered your workstation + with the server, your screen will look like this: + + + Example of registered Staff Client + + + + + + You are now ready to log into the Staff Client for the first time. Type in + your password again, and click 'Login'. +
+
+ Running the Staff Client Over An <systemitem class="protocal">SSH</systemitem> Tunnel + + staff client + running through an SSH tunnel + + You can configure the Staff Client to communicate with the Evergreen server over + an SSH tunnel using a SOCKS 5 proxy + server. There are several reasons for sending network traffic for the Staff Client + through an SSH proxy: + + + Firewalls may prevent you from reaching the Evergreen + server. This may happen when you are connecting the Staff + Client to a test server that should not be available + generally, or it may be the result of network design + priorities other than ease of use. + + + You may wish to improve security in situations where + Staff Client traffic may be susceptible to network + eavesdropping. This is especially true when staff machines + connect via wireless links to the network. + + +
+ Setting Up an <systemitem class="protocal">SSH</systemitem> Tunnel + You will need a server that allows you to log in via + SSH and has network access to the + Evergreen server you want to reach. You will use your username and password + for that SSH server to set up a + tunnel. + For Windows users, one good + solution is the open-source utility + PuTTY, + a free telnet/SSH client. + Following are instructions for setting up an SSH + session using the PuTTY utility: + + + Setting up an SSH + tunnel in PuTTY + + + + + + + + Using the menu on the left, find the section: + + + Connection + SSH + Tunnels + + + + + In the section on the right labeled "Source + port", enter 9999. + + + Set the checkbox "Dynamic". Do not + enter anything in the "Destination" text + entry box. + + + Click 'Add' and notice that + "D9999" now appears in the section + labeled "Forwarded ports". + + + Use the menu on the left, find the + "Session" section, then enter the host name + of the SSH + server. + + + A pop-up window will open to allow you to enter your + username and password. Once you are logged in, the tunnel is + open. + + + See How to set up + SSH (for the beginner) for information on + setting up SSH for other client operating + systems. +
+
+ Configuring the Staff Client to Use the <systemitem class="protocal">SSH</systemitem> Tunnel + In order to tell the Staff Client that all traffic should be sent + through the SSH tunnel just configured, + you must find edit the file all.js, usually located at + C:\Program Files\Evergreen Staff Client\greprefs\all.js + on a Windows system. + Search this file for the word socks to find the appropriate + section for the following changes. + + + The SOCKS section of "all.js" before changes + + + + + + Make the following changes: + + + Change the value of network.proxy.socks + from "" to localhost. + + + Change the value of network.proxy.socks_port + from 0 to 9999. + + + + + The SOCKS section of "all.js" after changes + + + + + + If everything is working correctly, you should now be able to run + the Staff Client and all its data will be sent encrypted through the + SSH tunnel you have just configured. +
+
+
+ Navigating a Tabbed Interface + Like many popular current web browsers and other applications, the Staff Client + uses a "tabbed" interface. Tabs allow you to have several pages open at the same time + in a single window. This is easier to manage on your computer screen than multiple + windows, since you can easily switch between tabs in the same window. + + + Tabs in the Staff Client window + + + + + + The "tabs" appear below the menu bar in the Staff Client with a descriptive + title. Simply select a tab to bring it to the front and view the page displayed in the + tab. You can use tabs to have access to multiple things all at the same time: patron + records and searches, bibliographic records and searches, circulation or cataloging + interfaces - anything at all in the Staff Client. + + Create a new tab by pressing + + Ctrl + T + + on the keyboard or selecting: + + File + New Tab + + from the menu. + Close a tab by pressing + + Ctrl + W + on the keyboard or selecting + + File + Close Tab + + from the menu. + Switch tabs by pressing + + Ctrl + Tab + + on the keyboard or selecting the tab in the tab bar. + +
+
+ -- 2.11.0