Thanks for trying OneBook! This file describes the software and hardware environment which OneBook requires to run, and presents the steps you should take to install it. Hardware and Software Requirements Due to the fact that OneBook relies on software which is available for a variety of platforms and architectures, the number of configurations on which it will run is probably quite large. However, we as developers have not had the time or resources to test the system on more than a handful of the theoretically compatible configurations, and so the following requirements are based on an environment in which it is known to run successfully. Hardware Requirements As with any server application, the processing power, network bandwidth, and other hardware resources available to OneBook will directly influence its performance under load. We suggest the following minimum hardware specification under which OneBook will perform satisfactorily: Resource Minimum Required Performance or Capacity --------------------------------------------------------------------------- Processor 600MHz Intel Pentium III or equivalent Main Memory 256MB RAM Network Connection T1 (1.544Mbps) Software Requirements OneBook is known to run under recent versions of Microsoft Windows and Linux, and will probably run under many other operating systems. However, this document assumes installation under Red Hat Linux 7.2. Additional software requirements follow. Resource Required Implementation --------------------------------------------------------------------------- Operating System Red Hat Linux 7.2 JSP Server Apache Tomcat 3.2 or higher JRE Sun Java 2 Standard Edition 1.3 or higher Database MySQL 3.23 or higher JDBC Driver MM.MySQL 2.0.7 or higher Loading the Distribution If your server satisfies the above requirements, you are ready to install OneBook. The distribution is available as a JAR (Java Archive) file, the contents of which must be extracted before the application can be run. Feel free to extract the contents of the JAR file to any directory on your server such that it is readable by Tomcat. It will occupy approximately 3 MB when uncompressed, including the source code. For example, if the package is located at /mnt/cdrom/onebook.jar and you wish to install the application in /home/user/webapps/, you would type the following in the shell: $ cd /home/user/webapps $ jar xf /mnt/cdrom/onebook.jar The above jar command will unpack the application and source files into directory tree with onebook/ as its root. For the remainder of the document, we will refer to this root directory as $ONEBOOK_HOME. Thus, in the above example, $ONEBOOK_HOME is equivalent to /home/user/webapps/onebook/. Installing the Software Since the executables for OneBook consist of platform-independent Java .class files, these executables come pre-built, and do not need to be built again unless the source code is changed. However, there are a few steps you must take before the application is ready to run on your system. Preparing the Database As indicated previously, OneBook uses MySQL as its database application. In order to make this work on your system it is necessary to take the following steps: 1.Create a new MySQL user named onebook using the $ONEBOOK_HOME/sql/database_permissions.sql script as follows: $ mysql u root < $ONEBOOK_HOME/sql/database_permissions.sql 2.Create and seed the database using the following commands (replacing $ONEBOOK_HOME with the location of the unpacked distribution on your system): $ cd $ONEBOOK_HOME $ make new Configuring Tomcat Once the database has been prepared, you must tell Tomcat about the OneBook application. To do this, add the following line to the application properties section of your $TOMCAT_HOME/conf/server.xml file (where $TOMCAT_HOME indicates the base directory of your Tomcat installation): This will make OneBook the root context under Tomcat. Thus, if the name of your server is onebook.watsamatta.edu, the URL for accessing OneBook (using the default Tomcat port 8080) will be http://onebook.watsamatta.edu:8080/ See the Tomcat documentation for more information about using the server.xml file to configure an application. You must restart Tomcat before changes to server.xml take effect. Final Setup Before you begin using OneBook, you may want to change the password of the MySQL user you created when preparing the database (the default is the empty string .) In addition to changing the password according to the MySQL documentation, you will need to edit the .onebook/properties file which was automatically generated in your home directory (/home/bob if your user name is bob, or /root if you are the superuser) when you seeded the database. The .onebook/properties file defines a number of settings which influence how OneBook runs, but the only one we are interested in for now is the DatabasePassword property. To change the password for the onebook MySQL user created earlier, do the following: 1. Ensure that .onebook/properties is readable by only you and the process under which Tomcat runs. 2. Edit .onebook/properties so that the DatabasePassword property is set to the desired password. 3. Change the password for the onebook using the appropriate MySQL GRANT commands. Congratulations! You have successfully installed OneBook on your server. To begin using the system, point you web browser to the URL of your server (using port 8080 under a default Tomcat installation) and log in as admin with a password of admin. Be sure to change that password to something more secure via the Browser interface before exposing the system to the rest of the world.