Extract the Virtual Library binary distribution

If you are building the Virtual Library from source, follow the build instructions and then locate the files referenced below in the /target directory. The instructions below assume that you are working with the binary distribution and $VLIBRARY_HOME is the top-level directory of the unpacked distribution.

Download and install Tomcat and Derby

Tomcat

1. Download tomcat 5.5
2. Set it up
   Tomcat 5.5 is configured with minimal logging by default. It is a good idea to configure logging.
3. Hereafter, let $TOMCAT_HOME refer to the full path to where tomcat is installed (e.g. /home/joe-user/apache-tomcat-5.5.20). It is not required to define this as an environment variable, but if you do so, the commands below will work as presented.

1. Download derby 10.4
2. Set it up. The only critical thing here is Setting up the Java environment.
3. Hereafter, let $DERBY_HOME refer to the full path to where Derby is installed (e.g. /home/joe-user/db-derby-10.4.1.3-bin). You will create this as an environment variable as part of Derby setup.

This example assumes that you are going to create tables directly in a default user schema in Derby, rather than using schemas. This is the default setup for the VL.

1. Start the Derby server in "Network Server Mode:"
   $DERBY_HOME/bin/startNetworkServer
2. Run the vlibrary schema creation script:
   $ ij
   ij version 10.2
   ij> connect 'jdbc:derby://localhost:1527/VLIBRARY;create=true';
   ij> run 'path-to-derbymake/derbymake_wo_schema.sql';
   (where path-to-derbymake is the full path to the Derby database creation script. This will be $VLIBRARY_HOME/sql.)
   ij> exit;
3. Set up authentication for the database and create the application user. These instructions create a user named "app" with password "apppass." For a real (i.e., non-test) deployment, these should be changed. Other places where these values appear and would need to be changed are tomcat's server.xml (see below) and vlibrary's database.properties, which gets deployed to the vlibrary web app's WEB-INF/classes directory.
   --   Create a file named derby.properties, containing the following entries and place that file in the same directory where VLIBRARY was created (if you took the defaults when setting up derby, this will be $USER_HOME):
   derby.connection.requireAuthentication=true
   derby.authentication.provider=BUILTIN
   derby.user.app=apppass
   --   Restart the derby network server:
   $DERBY_HOME/bin/stopNetworkServer
   $DERBY_HOME/bin/startNetworkServer
   (Keep the server running from this point forward. For a more robust setup, the server should be started using an init script for the server node.)
   --   Run ij again, connecting with the app password and set up access for VLIBRARY:
   $ ij
   ij> connect 'jdbc:derby://localhost:1527/VLIBRARY;user=app;password=apppass';
   ij> CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.database.defaultAccessMode', 'noAccess');
   Statement executed.
   ij> CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.database.fullAccessUsers','app');
   Statement executed.
   ij> exit;
   --   Verify that the app user can connect and execute queries
   $ ij
   ij> connect 'jdbc:derby://localhost:1527/VLIBRARY;user=app;password=apppass';
   ij> SELECT * FROM READER;
   (should succeed, but show empty table)
   ij> exit;

Tomcat configuration

Tomcat needs to have the vlibrary web app installed and its security realm set up. Since the security realm uses the Derby database for authentication, Tomcat also needs to have the derby client jar available at the server level.

1. Copy the derby client jar to tomcat's /server/lib directory:
   cp $DERBY_HOME/lib/derbyclient.jar $TOMCAT_HOME/server/lib/
2. Edit the file $TOMCAT_HOME/conf/server.xml
   Find, uncomment and edit the section below as indicated:
   <!-- Replace the above Realm with one of the following to get a Realm
   stored in a database and accessed via JDBC -->
   <Realm className="org.apache.catalina.realm.JDBCRealm"
   driverName="org.apache.derby.jdbc.ClientDriver"
   connectionURL="jdbc:derby://localhost:1527/VLIBRARY"
   connectionName="app" connectionPassword="apppass"
   userTable="reader" userNameCol="uid" userCredCol="passwd" digest="MD5"
   userRoleTable="user_x_role" roleNameCol="role"
   CredentialHandler
   className="org.apache.catalina.realm.MessageDigestCredentialHandler"
   algorithm="MD5"/>
   /\Realm
3. Copy the vlibrary web app war file to tomcat's /webapp directory:
   cp $VLIBRARY_HOME/vlibrary.war $TOMCAT_HOME/webapps
4. Start tomcat:
   $TOMCAT_HOME/bin/startup.sh (startup.bat on Windows)
   (like the Derby server, for a robust setup, tomcat should be started in an init script.)
5. Either create the directory /var/log/vlibrary or edit the file $TOMCAT_HOME/webapps/vlibrary/WEB-INF/classes/log4j.properties so that
   log4j.appender.logfile.File=/var/log/vlibrary/vlibrary.log
   points to a valid file path (the .log file need not exist, but the path has to be valid).

Startup and admin user creation

1. Hit the vlibrary servlet. Assuming tomcat is running on localhost, listening on port 8080, per default config, point your browser at http://localhost:8080/vlibrary/
2. Click the "Edit Your Profile" link. You will be redirected to the login page. Click the link labelled "click here to register." Fill in and submit the form, supplying data for an administrative user. Verify that the registration was successful by logging in after registration and selecting "Edit Your Profile." Cancel the form, which should display the data that you entered and then logoff.
3. Make the user you just created an administrator. Since only administrators can make users administrators, this has to be bootstrapped by hacking the database directly. Once you have created one administrative user, that user can make other users administrators through the "Manage Users" menu item that appears for administrators.
   $ ij
   ij> connect 'jdbc:derby://localhost:1527/VLIBRARY;user=app;password=apppass';
   ij> INSERT INTO USER_X_ROLE VALUES ('clarisse','administrator');
   (replace 'clarisse' with the user id of the user you created in step 2.)
   ij> exit;
   Now log back in to the vlibrary as the user you just "promoted" to administrator. You should see the "Manage Readers" submenu. You are now open for business!

Mail client configuration

The Virtual Library needs to connect to a running mail (SMTP) server in order to send notifications messages on book actions (new, checked-in, checked-out, etc). You will need to know the IP address or hostname and the port of the SMTP server, and, if required, the username and password required by the server. If in doubt, consult your system admin. The Virtual Library comes preconfigured for an SMTP server running on the "localhost", port 25, no username and password. If that is not correct for your system, you will need to change the specific configuration files.

The VL client client mail configuration is located in WEB-INF/classes/mailsender.properties. The structure of the file is:

mailsender.host=put here the IP address of hostname of the SMTP server, something like smtp.mydomain.com or 192.xxx.xxx.xxx
mailsender.port=put here the port on which the SMTP server accepts requests, default 25
mailsender.username=user name/id for accessing the SMTP server, if required, default blank (empty)
mailsender.password=user password for accessing the SMTP server, if required, default blank (empty)

Configuring administrative email addresses

Virtual Library installations rely on system admins for basic setting, configuration and reporting of any user errors. Users can and are encouraged to report VL errors, for example the Main Menu page contains a link to the email address of the system admin. In order to set up that email address, the following entry in the WEB-INF/classes/AppicationResources.properties file will need to be modified:

email.support.address=put here the email address, something like your_admin@your_domain.com

In addition, email notifications on book transactions are sent by the Virtual Library to readers from an administrative email address. Users can also send emails to that address for transactions inquiries. To set this email address, the following entry in the WEB-INF/classes/AppicationResources.properties file will need to be modified:

email.admin.address=put here the email address, something like your_admin@your_domain.com

You will need to reload the Virtual Library servlet for this and / or the mail client configuration changes to take effect.