User Tools

Site Tools


Table of Contents
User Comments

Installing and Running the Staff Client

Installing On Windows

The staff client is available for download from the downloads section on the Open-ILS website at Download the staff client installer, and run it. A screen will appear that looks similar to this:

Click the Next button 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 install the software on your workstation.

When you run the staff client for the first time, a screen similar to this will appear:

First, configure the server you would like to connect to in the Server section. After selecting a server, click the Re-Test Server button.

Because this is the initial run of the staff client, the Workstation section in the upper-right states: Not yet configured for the specified server. The first thing that must be done to every workstation is to assign it a workstation name. This is covered in the Workstation Names section of the documentation.

Installing On Mac

Evergreen Indiana Pkg file [Evergreen v1.2.3.0]

  1. Download and install the Version of XULRunner for Mac. Note, later versions may not work correctly.
  2. Download and install the Mac Installation package for the 1_2_3_0 Version Staff Client from HERE.
  3. 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 into the "Resources" folder within the Open-ILS package in your Applications directory on the Mac, overwriting files with the same names.
  4. Drag the application's icon into your toolbar for easier access.

When you run the staff client installer, a screen will appear that looks similar to this:

FIXME Bad Image Link

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.

FIXME Bad Image Link

Running directly using XULRunner

Install recommended XULRunner Version

Evergreen 1.2.x.x - XULRunner or XULRunner

Evergreen 1.4.x.x - XULRunner or XULRunner

Evergreen 1.6.x.x - XULRunner 1.9

*Note: If you have issues removing previously installed XULRunner versions see after this entry.

The staff client data from the ./staff_client/build directory must be placed somewhere on the machine (e.g. ~/Desktop/Evergreen_Staff_Client). FIXME Need to clarify "./staff_client/build directory"

XULRunner must be called via 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

This command should exit quietly.

A folder named OpenILS under /Applications, with a launcher named open_ils_staff_client, will be created.

Removing previously installed XULRunner versions

If you already have a newer version installed, per the release notes, you'll need to remove the entire /Library/Frameworks/XUL.framework directory before downgrading.

In addition, you may also need to remove the previous xulrunner-ver-mak.pkg file from /Library/Receipts/

If there is no xulrunner-ver-mak.pkg file in /Library/Receipts/ (possibly in newer OSX releases) we need flush receiptdb file.

*Note: If we install a newer version over a previous (older) install the older one is not removed but the symlinks get changed to the newer one.

Flush Receiptdb file:

First we get the package identifier:

 sudo pkgutil --pkgs > /tmp/pkgs.txt

Since I wanted to purge/forget the build that was initially installed:

 sudo pkgutil --forget org.mozilla.xulrunner

Note: At first I thought after deleting the folder XUL.framework I had to also edit InstallHistory.plist in /Library/Receipts but that does not seem necessary.

Creating an APP file - Evergreen Staff Client & XULRunner Bundled

  1. An app file is basically a folder. Start with a folder stucture like this:
    • Contents
      • Frameworks
      • Resources
      • MacOS


  mkdir -p
  mkdir -p
  mkdir -p
  1. Create a new file in with the following (adjust for your version of Evergreen)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">
        <string>OpenILS open_ils_staff_client rel_1_6_0_0</string>
        <string>Evergreen Staff Client</string>
  1. Download and install an appropriate Mac OS package of XULRunner from the Mozilla website (See above for recommendations)
  2. Make a copy of /Library/Frameworks/XUL.Framework inside your app file, it should look something like this:
      • Contents/
        • Frameworks/
          • XUL.Framework/
            • Versions/
              • Current -> (symlink)
            • XUL -> Versions/Current/XUL
            • libxpcom.dylib -> Versions/Current/libxpcom.dylib
            • xulrunner-bin -> Versions/Current/xulrunner-bin
  3. copy XUL.Framework/Versions/Current/xulrunner into (do not symlink, copy the file)
  4. Make the root of your Evergreen application files like this:
      • Contents/
        • Resources/
          • BUILD_ID
          • application.ini
          • chrome/
          • components/
          • etc.
  5. Put a Mac format icon file named Evergreen.icns in Resources


  1. download and install WineBottler:
  2. open the application "WineBottler"
  3. select "Create Custom Prefixes"
  4. select the desired windows installer as your "Install File"
  5. set the "Runtime arguments" to "build/application.ini"
  6. click "Install" – you will now see the Evergreen Windows Installer
  7. when you get to the end UNCHECK the option to "run Evergreen now" and complete the installation
  8. WineBottler should then pop up a dialog for you to select an executable – select xulrunner.exe

Installing On Linux

Quick Upgrade of the Staff Client

A Linux staff client is built on the server as part of the initial installation of Evergreen. To upgrade the client copy the folder containing the new client on to your workstation from the server.

cd ~/ILS/Open-ILS/xul/staff_client
scp -r build user@client.linux.machine:~/eg-client-x.x.x.x/

It can be run from the build directory by:

xulrunner ~/eg-client-x.x.x.x/build/application.ini

Building the Staff Client on the Server

A Linux staff client is built on the server as part of the initial installation of Evergreen, using the following steps:

cd ~/ILS/Open-ILS/xul/staff_client
mkdir /openils/var/web/xul/
mkdir /openils/var/web/xul/12345/
cd build/
cp -R server/ /openils/var/web/xul/12345/

It can be run from the build directory by:

xulrunner application.ini

In order to install a compatible staff client on another Linux machine, you can copy the applicable files from the server to that Linux machine, or even build it from scratch on that machine. Just be sure the Build ID you chose on the server (12345 in this example) matches the Build ID for each staff client you use on other machines.

If you will be using a pre-packaged Windows version on some computers as well, you may want to choose your Build ID on both server and other versions to match that of the Windows staff client. You can determine what Build ID has been used for existing installations of the staff client by clicking the "About this Client" button.

An alternative option if you have access to make changes to the Evergreen server is to create a symbolic link. In order for a copy of the staff client and server to work together, the Build ID (shown when you click "About this Client") of the client, 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.

cd /openils/var/web/xul
sudo ln -s server_build_id/ client_build_id

Building the Staff Client on a Client Machine

This section is more toward an end-user who may wish to use Linux rather than Windows for client machines, but has limited Linux experience. The Staff Client can be built on Linux without installing the Evergreen Server component; this is a relatively simple process, compared to server installation, though does require some command-line work. The following directions are for building Staff Client version on Kubuntu 7.10, so you may need to modify them for other distributions (these instructions should work as-is for Ubuntu or Ubuntu derivatives).

1: Prerequisites

  • subversion client
  • xulrunner

Using apt-get to acquire these:

sudo apt-get install subversion
sudo apt-get install xulrunner

Synaptic can also be used; search for subversion and select the latest version, and search for xulrunner and select version

2: Download the Source Code

2a: 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 admin, IT person, or HelpDesk to determine which Staff Client versions are supported.

Next, you'll 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;a=summary. The summary page includes a list of tags and branches. Depending on whether a release was made before or after the project moved to Git, select either the Git tag or the branch converted from an SVN release tag (e.g., tags/rel_1_2_1_4.)

2b: Download the Source Code.

Now, open a terminal (command-line prompt) and navigate to the directory in which you wish to download the staff client. Navigate to the desired directory and use the following command to download the proper version of the source code by tag:

git clone git://
git checkout -b tmp_branch origin/rel_1_2_1 # or git checkout rel_1_2_1

Note that you'll want to change "rel_1_2_1_4" to the appropriate tag for your installation.

3: Build the Staff Client.

Evergreen 1.2.x

From the command line, navigate to the directory in which you downloaded the source code. Then, navigate to the proper subdirectory:

cd Open-ILS/xul/staff_client

Now, we'll run the "make" script to actually build the Staff Client files. Be sure to check wtih your sysadmin 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 the PINES installation at, the supported build id is "rel_1_2_1_4". Modify the following command accordingly:

make STAFF_CLIENT_BUILD_ID='rel_1_2_1_4'
Evergreen 1.4.x

The 1.4 series of Evergreen has complicated the build process for staff clients a bit. If you downloaded a .tar.gz (tarball) of Evergreen, then your steps will resemble:

FIXME – Need instructions for getting certain Javascript files from OpenSRF, preferably without actually installing OpenSRF.

tar xfz Evergreen-ILS-
cd Evergreen-ILS-
./configure --prefix=/openils --sysconfdir=/openils/conf
cd Open-ILS/xul/staff_client/
make STAFF_CLIENT_BUILD_ID='rel_1_4_0_4' install

If you're installing from a Subversion checkout:

git clone git://
git checkout rel_1_4_0_4
./   # If you downloaded a .tar.gz of Evergreen, you may skip this step
./configure --prefix=/openils --sysconfdir=/openils/conf
cd Open-ILS/xul/staff_client/
make STAFF_CLIENT_BUILD_ID='rel_1_4_0_4' install

4: Run the Staff Client (from the command line).

Navigate to the 'build' subdirectory, then run the following command:

xulrunner application.ini

Make sure you run this from 'build\', not from 'staff_client\'.

5: Cleaning Up/Creating Shortcuts (Optional)

The source code download included many files that are needed to build the Staff Client, but not necessary to run it. You may wish to remove them to save space, or to create a directory containing the built staff client that can be copied to other machines.\ To do this, first create the directory where you wish to place your 'finished' staff client:

 mkdir ~/<Destination Directory> 

Then, copy the 'staff_client' directory to it:

cd ~/<Download Directory>/Open-ILS/xul/
cp -r staff_client ~/<Destination Directory>

Test to verify that all the necessary files were moved to the destination directory:

cd ~/<Destination Directory>/staff_client/build
xulrunner application.ini

The Staff Client should run properly. Now remove the original download directory and all sub directories:

rm -r -f ~/<Download Directory>

Almost done! Now, the command

xulrunner ~/<Destination Directory>/staff_client/build/application.ini

will run the Staff Client. You may wish to create Desktop/Start Menu/K-Menu shortcuts for the Staff Client. To do so, use the previous command as the target.

Using Wine to Install On Linux

Wine is also an alternative for those who want to install the packaged Windows versions rather than building the Staff Client manually. Wine is application that allows Linux users to run Windows executables, and is a simple way for casual Linux users to use the Evergreen Staff Client.

1: Install Wine (using apt-get):

   command-prompt:~/sudo apt-get install wine

Here is more information about installing Wine:

2) Download the proper EG Staff Client installer from the website and put it in a directory you like:

command-prompt:~/cd directory/of/choice

3) In the GUI, navigate to the file where you downloaded the setup file and run it; this will install the SC. If this fails, you may need to configure Wine first to 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 and click "Apply".

4) To launch the Evergreen Staff Client, go to the All Applications menu, select "Wine->Program Files->Evergreen Staff Client->Evergreen Staff Client", or launch from the desktop shortcut.

Running the Staff Client with an SSH Tunnel as a SOCKS 5 Proxy

The Evergreen Staff Client can use an SSH tunnel as a SOCKS 5 proxy. For more details, see configuring_a_proxy_for_the_staff_client.

evergreen-user/installing_and_running_the_staff_client.txt · Last modified: 2022/02/10 13:34 (external edit)

© 2008-2022 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a U.S. 501(c)3 non-profit organization.