HERMES is copyright 2003, Sheridan Libraries of the Johns Hopkins University. HERMES Installation Instructions These instructions are still a work in progress. Huge sections are missing! What actually is here hasn't even really been proofread. Beware! ------------------------------------------------------------------------- You need to already have: A Relational Database Management System (RDBMS) that supports transactions, subselects, and multibyte characters. HERMES was developed on PostgreSQL (v. 7.3), and these instructions will give more-or-less step-by-step instructions for a PostgreSQL installation. If you want to use a different RDBMS, feel free, but you're mostly on your own. See the section on Database Creation in the instructions below. ColdFusion MX with appropriate connectivity to your RDBMS of choice. An LDAP directory you can point to for staff authorization. HERMES could be modified to use alternative authorization methods, but that hasn't yet been done. ------------------------------------------------------------------------- Summary of Installation Unzip and untar this package. You appear to have already done that in order to be reading these instructions. Good job! Put all the files that end up in your [unpack_dir]/cf_code directory into a single directory in your ColdFusion MX web hierarchy. Your public interface will be at: http://your.domain.edu/your_hermes_path/index.cfm and your administrative interface at: http://your.domain.edu/your_hermes_path/administration.cfm Create the hermes database--see the Database Creation section later in these instructions. Make it so that your coldfusion application can talk to your database. [those instructions aren't written yet, but that's a more or less straightforward ColdFusion administration function, so hopefully you already know how to do it]. Edit Application.cfm so you can get into the administrative module and enter a few key things so you can start using it. See the "Getting Started with the Administrative Interface the Very First Time" instructions below. Keep entering set-up data. [no instructions for that yet.] Enter e-resource and license metadata. [no instructions yet.] Use the system. [Instructions? Not yet.] ------------------------------------------------------------------------- Database Creation The first thing you need to do is decide if you want to use--or at least start with--the JHU HERMES subjects and the work that JHU catalogers have done so far mapping LCSH and MESH to those HERMES subject headings. The advantages of choosing to load our data: You get a pre-designed subject scheme, which you can start using right away. If you plan to load records from your catalog into HERMES, you get to take advantage of all the work the JHU cataloging department has done mapping subject headings to our HERMES subjects. The disadvantages of choosing to load our data: You get a pre-designed subject scheme, which you may not like or which may not represent your collection or institution very well. The initial HERMES database with JHU's subject mapping is much larger, and perhaps larger than you would need, especially if you do not expect to load records with subject headings into HERMES. JHU subject data is included in the [unpack_dir]/database/hermes_template database file, so if you want to load the JHU subject data, use that file for the following instructions. You will be unsurprised to learn that JHU's subjects are excluded in the [unpack_dir]/database/hermes_template_no_subjects file, so that, of course, is the file to use if you want to create your own subject scheme from scratch. If you're NOT using PostgreSQL: The database files hermes_template and hermes_template_no_subjects are PostgreSQL dumps of the hermes database schema and the contents of selected tables. This database dump includes SQL commands for table and index creation and SQL commands for data insertion. So, the file should be, at least to some degree, portable to other RDBMSs. You will need to edit the hermes_template some to remove or change PostgreSQL-specific terminology (see below), but *mostly* it *should* work. Cheers. A couple of PostgreSQL specifics in the hermes_template file: Every line that begins with a backslash is a PostgreSQL psql command, and would need to be replaced with the appropriate syntax for your RDBMS. CREATE SEQUENCE is a PostgreSQL language extension. It is used to create auto-incrementing ID fields. Many other RDBMSs have similar local extensions, and you'll need to arrange to use the one appropriate to you. If you're using PostgreSQL: The default PostgreSQL installation doesn't include multibyte support. You (probably) need multibyte support, as you may have records with international characters, so you need to build PostgreSQL with the specific instruction to --enable-multibyte. Once you have a multibyte-enables PostgreSQL db up and running. . . . Create a PostgreSQL user named 'hermes'. Use the postgresql createuser shell command, or use the CREATE USER sql command within psql. The hermes user need not have the ability to create users or databases. You'll probably want to give the hermes user a password as well. Create a hermes_template database based using the commands in the included [unpack_dir]/database/hermes_template file. From the UNIX command line: psql -f [unpack_dir]/database/hermes_template You can redirect the output of the above command to a file if you wish (or to /dev/null if you don't want to see it or save it). Assuming the above worked, you should now have a hermes_template database in PostgreSQL. Don't edit the new database; instead, use hermes_template as a template for future database creation--this will allow you to create a production database and any number of test and development versions easily, all based on the same template, with key system tables already populated. To create a version of the database for actual use, use psql to log into PostgreSQL as the postgres (root) user, and issue a command like: create database [name_of_new_db] with owner=hermes template=hermes_template; ------------------------------------------------------------------------- Creating a ColdFusion DataSource ------------------------------------------------------------------------- Getting Started with the Administrative Interface the Very First Time When you first install the hermes database and the ColdFusion code, you don't have any users in your database, so you can't log on to the system as an authorized user. So, you need to edit the Application.cfm file to sneak in, and while you're at it, you also need to make a few other changes. Using your favorite editor, edit the Application.cfm file. Starting at about line 30, there's a section of code--a bunch of cfset session.userstruct assignments--currently commented out. Uncomment them. That will allow you (or anyone!) to log into your new hermes installation as a superuser. Also, you need to enter the normal and SSL URLs for your hermes implementation (at about line 17). If you don't have a secure http connection you can use to encrypt your usernames/passwords, you ought to set one up. But if you're Bad and you don't care about the security of your LDAP passwords, you could just use the same unsecure URL for both the standardurl and secureurl values. If you're not using PostgreSQL, you may have to change the application.sqllike value on about line 40. (PostgreSQL's 'like' operator is case sensitive, so if you want a case-insensitive comparison--which you do--you have to use PostgreSQL's special 'ilike' operator). If you are running multiple versions of HERMES, you'll need to give each one a unique application name (line 4) and a unique name for your verity collection (line 43). The name of your verity collection needs to match the one you set up in the ColdFusion administrator, of course. Save the Application.cfm file with those changes. You can visit your administration page: http://your.domain.edu/your_hermes_path/administration.cfm You should see the default administration header, and the Superuser tasks, probably followed by a ColdFusion error message. That's okay. You're just in here to make a few changes so that you can log out and log back in for real. You need to do three things: First, create a Library (all users must be associated with a library). From the Superuser menu, choose "Administer the Library Lookup Table." Enter the name of your library, and press Insert. Now return to the administration screen, and go to "Administer the LDAP Settings." Enter the appropriate values for your LDAP Server, Distinguished Name, Username String Field, and Unique Username suffix string. You can ignore the cert7.db part, but you'll want to put in an appropriate logon message. Then press Update. What's that you say? You don't have an LDAP directory to point to? Well, that's a Problem, as so far we haven't written an alternative authorization scheme, and at JHU we have little motivation to do so. Maybe you could write one. Finally, create a superuser account for yourself. Return to the administration screen and select the first option, User Administration. Enter your LDAP username and other details, and make yourself a "Superuser" (while you can use the multi-select box to assign yourself all roles, you don't need to, as the supersuer gets all rights anyway). Insert the record. Now *don't* go back to the administration screen, but instead log out at the bottom of the 'User inserted!' screen. Edit the Application.cfm file again, and comment out that 'cfset session.userstruct' section that you uncommented a few minutes ago. Save the file, and in your web browser return to http://your.domain.edu/your_hermes_path/administration.cfm You should now be prompted to log in with your LDAP username and password, and assuming you are successful you'll be presented with the administration screen, this time without the error message. Congratulations! You may now add new users, or do whatever else you wish to continue with HERMES setup. ------------------------------------------------------------------------- More instructions to come. . . . Questions now? Write to: Nathan D.M. Robertson nate@jhu.edu