Installation of Evergreen Staff Client SoftwareThis section describes installation of the Evergreen Staff Client software.Installing the Staff Clientstaff clientinstallingInstalling a Pre-Built Staff ClientA 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 Windowsstaff clientinstallingWindowsIn 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 installerClick '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 timeFirst, 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 Mac OSstaff clientinstallingMac OSThis 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.0A 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 OSClick '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 installationRunning directly using XULrunnerstaff clientXULRunnerYou must install an appropriate version of XULrunner
to match the Evergreen version. See the following table for the recommended version of
XULrunner:
Evergreen / XULrunner DependenciesEvergreen VersionXULRunner VersionEvergreen 1.6.x.xXULrunner 1.9.x.xEvergreen 1.4.x.xXULrunner 1.8.0.4 or XULrunner 1.8.0.3Evergreen 1.2.x.xXULrunner 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_ClientThe command should exit quietly and will create the folder
/Applications/OpenILS,
containing a launcher named open_ils_staff_client.(OPTIONAL) Removing previously installed XULRunner versionsXULRunnerremoving previous versionsIf 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.xulrunnerIt 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 XULrunner BundledAn APP file is basically a folder. Start with a folder stucture like this:
Evergreen.app
__Contents
____Frameworks
____Resources
____MacOSCreate 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/MacOSCreate a new file in the folder
Evergreen.app/Contents/Info.plist
containing the following data (adjust for your version of
Evergreen):CFBundleExecutablexulrunnerCFBundleGetInfoStringOpenILS open_ils_staff_client rel_1_6_1_6CFBundleInfoDictionaryVersion6.0CFBundleNameEvergreen Staff ClientCFBundlePackageTypeAPPLCFBundleShortVersionStringrel_1_6_1_6CFBundleVersionrel_1_6_1_6.rel_1_6_1_6NSAppleScriptEnabledCFBundleTypeIconFileEvergreen.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-binCopy
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 LinuxQuick Upgrade of the Staff ClientA 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.iniBuilding the Staff Client on the Serverstaff clientbuilding on the serverA 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_IDBuilding the Staff Client on a Client MachineThis 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).PrerequisitesBoth 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 xulrunnerDownload the Source CodeDetermine which version is neededFor 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 CodeAs 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 ClientIn 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' installRun the Staff ClientAs 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 ShortcutsThe 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_DIRECTORYTest 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.iniIf there were no problems, then finish the cleanup by
removing the original download directory as shown:
# as the opensrf user:
rm -r -f ~/DOWNLOAD_DIRECTORYFinally, the command:
# as the opensrf user:
xulrunner ~/STAGING_DIRECTORY/staff_client/build/application.iniwill 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:
DesktopStartMenuK-MenuUsing Wine to Install on Linuxstaff clientusing wine to install on LinuxThe 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 wineVisit 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.exeIf 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 ClientA 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:WineProgram FilesEvergreen Staff ClientEvergreen Staff Client,
or else launch the Staff Client from the new desktop shortcut.Building the Staff Clientstaff clientbuildingYou 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 STAFF_CLIENT_BUILD_IDDuring 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 installYou 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 STAFF_CLIENT_VERSIONDuring 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 installYou 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 STAFF_CLIENT_STAMP_IDDuring 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 installYou 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 buildAdvanced Build Optionsstaff clientbuildingadvanced build optionsIn 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 OptionsKeywordDescriptionclientsRuns "make win-client", "make linux-client", and "make
generic-client" individuallyclient_dirBuilds a client directory from the build directory, without
doing a rebuild. The same as "copy everything but
server/".client_appPrerequisite "client_dir"; removes "install.rdf" from
client directory so an APP bundle can't be installed as an
extensionclient_extPrerequisite "client_dir"; remove "application.ini",
"autoupdate.js", "standalone_xul_app.js" from client directory so
an extension won't break FirefoxextensionPrerequisite "client_ext"; rewritten to use "client_ext"generic-clientPrerequisite "client_app"; makes an XPI file suitable for
use with "xulrunner --install-app""win-xulrunnerPrerequisite "client_app"; adds Windows xulrunner to client buildlinux-xulrunnerPrerequisite "client_app"; adds Linux xulrunner to client buildwin-clientPrerequisite "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-clientPrerequisite "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 BuildYou 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 devbuildCompressed JavascriptYou 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-javascriptYou 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-javascriptAutomatic Update HostYou 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 installYou 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 buildFor more information on Automatic Updates, see
.Installing and Activating a Manually Built Staff ClientThe 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 ClientOnce 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 ClientThis 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-clientThe output file evergreen_staff_client.xpi will be created.Packaging a Windows ClientThis 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 ClientIDI_APPICONTray icon32512Default 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-clientThe output file evergreen_staff_client_setup.exe will be created.Packaging a Linux ClientThis 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-clientThe output file evergreen_staff_client.tar.bz2 will be created.Packaging a Firefox ExtensionThis 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 extensionThe output file evergreen.xpi will be created.Staff Client Automatic Updatesstaff clientautomatic updatesIt 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, orIt 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 HostYou 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
makeDuring 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 buildBuilding Updatesstaff clientautomatic updatesbuildingSimilar 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_clientCommand to build all updates at once:
# as the opensrf user:
make updatescommands to build updates individually:
# as the opensrf user:
make generic-updates
make win-updates
make linux-updates
make extension-updatesBuilding updates with clientsstaff clientautomatic updatesbuilding with clientsTo 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-clientTo 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-clientActivating the Update Serverstaff clientautomatic updatesactivating the update serverThis 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.rdfOther tipsMultiple workstations on one installMultiple 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 ClientsIt 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 Clientstaff clientrunninglinuxYou can run the Staff Client on a Linux system by using the
XULrunner application (installed automatically and by default
with FirefoxVersion 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.iniAssigning Workstation Namesstaff clientassigning workstation namesThe 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 ClientIn 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 ClientSelect 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 ClientYou 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 SSH Tunnelstaff clientrunning through an SSH tunnelYou 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 SSH TunnelYou 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 PuTTYUsing the menu on the left, find the section:ConnectionSSHTunnelsIn 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 SSH TunnelIn 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 changesMake 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 changesIf 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 InterfaceLike 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 windowThe "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
CtrlT
on the keyboard or selecting:
FileNew Tab
from the menu.Close a tab by pressing
CtrlW on the keyboard or selecting
FileClose Tab
from the menu.Switch tabs by pressing
CtrlTab
on the keyboard or selecting the tab in the tab bar.