This virtual image was built on OpenSRF trunk and Evergreen trunk as of 2011-03-19. It was built using VirtualBox OSE 4.0.4 and exported into the Open Virtualization Format (OVA). Use in VMWare products will require the VMWare OVF Tool: see http://www.vmware.com/appliances/getting-started/learn/ovf.html

The underlying operating system is Debian Squeeze (6.0) using the debian-backports PostgreSQL 9.0 packages.

This image is intended to help developers quickly get their hands on a running system; for that reason, it has been loaded with 500 authority records, 50 bibliographic records, a small sample of call numbers and copies, and a regular patron account (demo / demo123).

It has also been set up with Python support in both OpenSRF and Evergreen, which requires that nameserver 127.0.0.1 be added to /etc/resolv.conf. If you see a dnspython error when starting or stopping the OpenSRF services, it is most likely due to either the dnsmasq service not running or the nameserver entry having disappeared from /etc/resolv.conf.

Accounts

All accounts are expressed as user name / password.

  • UNIX accounts

    • root / evergreen

    • evergreen / evergreen

    • opensrf / evergreen

  • Database account

    • evergreen / evergreen

  • Evergreen accounts

    • admin / open-ils

    • demo / demo123 (barcode = 1234)

Starting Evergreen

When the virtual image boots up, it does not automatically start Evergreen. Start it as follows, beginning as the root user:

su -                        # become the root user (password: "evergreen")
vim /etc/resolv.conf        # add "nameserver 127.0.0.1" to the list
su - opensrf                # become the opensrf user
osrf_ctl.sh -l -a start_all # starts all Evergreen services
exit                        # become the root user
/etc/init.d/apache2 restart # restart the Apache server
ps aux | grep open-ils      # list the running OpenSRF processes
Note
 If the last command shows there are no running OpenSRF processes, or if running osrf_ctl.sh -l -a start_all resulted in a set of messages such as * opensrf.settings is already running then the server was probably shut down uncleanly, and you will need to recover from that situation. Specifically, if a corresponding osrf_ctl.sh -l -a stop_all command was not issued before shutting down the virtual image, then old process ID (PID) files will fool the osrf_ctl.sh script into thinking that OpenSRF processes are running, when they actually are not.

Recovering from an unclean shutdown of the server

To recover from this situation, perform the following steps, beginning as the root user:

su -                                # become the root user
su - opensrf                        # become the opensrf user
osrf_ctl.sh -l -a stop_all          # stop all Evergreen services
rm -f /openils/var/run/opensrf/*pid # delete old PID files

Then re-run the steps for starting Evergreen, including restarting the Apache server.

Stopping Evergreen

Before shutting down the server, you should first shut down Evergreen cleanly to prevent problems the next time that you try to start Evergreen. To shut down Evergreen cleanly, perform the following steps, beginning as the root user:

su -                                # become the root user
su - opensrf                        # become the opensrf user
osrf_ctl.sh -l -a stop_all          # stop all Evergreen services

Desktop environment

This machine has been configured to run with a graphical desktop. If you give the virtual machine 1.5 GB of RAM, you should be able to run the desktop at the same time as Evergreen.

The desktop includes a web browser (IceWeasel, Debian’s repackaged version of Firefox) and XULRunner 1.9. Once you start the desktop and Evergreen, you can connect to Evergreen using the built-in staff client with the following commands:

cd /home/evergreen/Evergreen-trunk/Open-ILS
xulrunner-1.9-1 xul/staff_client/build/application.ini

Connect to host name localhost using the admin / open-ils account and begin populating the data in your image.

Note
 As this image uses a self-signed SSL certificate, XULRunner will refuse to connect to the host until you click the Add SSL Exception button below the Hostname text field.

Network connections

This machine was configured with a NAT connection on the first Ethernet adapter (eth0) and a host-only connection on the second Ethernet adapter (eth1).

As the virtual machines tend to map virtual devices to real MAC addresses on their host, you might need to clear that mapping before making a connection. As root, run:

rm /etc/udev/rules.d/70-persistent-net.rules
reboot

The machine will normally connect to your network via DHCP, but you can try to manually create a network connection by running the following command as root:

dhclient eth0 # for a NAT connection

Host connections

The default configuration includes a host-only connection on the second Ethernet adapter (eth1).

To create the host network connection, run the following command as root:

dhclient eth1 # for a host connection

To connect to your virtual machine from your host machine, create the host connection and check the IP address of eth1 using the ifconfig command:

/sbin/ifconfig eth1

The IP address will be listed in the inet_addr stanza as something like:

inet addr:192.168.56.101

Network connections for external staff clients

While you can use the IP address to access the OPAC, the staff client needs a hostname to connect to Evergreen. For the built-in staff client in the Linux graphical desktop, you can just use localhost. But for external staff clients, if your network does not assign a real hostname to the IP address for the virtual image, you may need to alter the hosts file on your client workstations to provide an alias for the IP address.

On Linux, the hosts file can be found in /etc/hosts

On Windows, the hosts file can be found in C:\WINDOWS\System32\drivers\etc\hosts

External staff clients

You can connect a staff client to the virtual image by getting your host-based connection running (see previous section). Once you have a host-based connection running, you can use a Windows staff client to connect to the virtual image from a Windows machine. Contact the developers on the #evergreen IRC channel on Freenode for more information.