NAME

ROADS v1 to v2 migration - A HOW-TO Guide

DESCRIPTION

ROADS v2 is a major revision of the ROADS software that provides improvements in performance and functionality in a number of areas. Many of the potential users of ROADS v2 will already be running one of the older ROADS v1 releases. This document aims to explain how to go about upgrading from ROADS v1 to ROADS v2 in the most painless and safest way possible.

INSTALLATION

The basic method of updating from one major release of ROADS to another is to place the new version in a separate installation on the machine, copy over your existing data, configure the new release to run it's WHOIS++ daemon on a different port and access its web pages via different URLs temporarily, reindex your templates, test that the new search scripts and admin tools work and configure them to your taste. Once you're satisfied that the new release is working and configured the way you want it, you can simply reconfigure the new WHOIS++ daemon to run on your normal WHOIS++ port, shutdown the old WHOIS++ daemon, start the new WHOIS++ daemon and then reconfigure your http daemon to point to the new ROADS CGI scripts instead of those from the old release. If done carefully, users should be able to be serviced almost continuously, with only a very small break whilst the WHOIS++ servers are switched over.

One thing that is not advisable is to attempt to use different components from different ROADS major releases together at the same time. Configuration file settings can change between major releases and we can't guarantee backward compatibility. Having said that, your existing configuration settings should provide a good start for configuring your new ROADS installation.

The first thing to do is to acquire the latest ROADS v2 distribution from http://www.roads.lut.ac.uk/ . Uncompress and untar this distribution into a new directory. For the sake of this document we'll refer to this directory as NEWROADS. We'll call the installation directory for the old version of ROADS OLDROADS.

Next make a copy of your existing template source directory. To do this, assuming that your existing templates are in OLDROADS/source, use the following commands:

mv NEWROADS/source NEWROADS/source.orig =item mkdir NEWROADS/source =item cp -r OLDROADS/source NEWROADS/source

Next you can run the Configure script in the NEWROADS directory. This should look very similar to the one used to configure ROADS v1 but we've tried to streamline its operation a little. Many of the default values are likely to be correct for your new installation but there are some that we'll need to modify:

WWW path to ROADS executables directory on HTTP server?: Set this to ROADSv2/cgi-bin
What is the Web path to the ROADS HTML documents directory?: Set this to ROADSv2
WWW path to admin executables directory?: Set this to ROADSv2/admin-cgi
What port number is your WWW server running on?: You may need to alter this if you run your HTTP daemon on a non-standard port or if you plan to run up a second daemon to test this ROADS v2 installation with (see below).
What port number will your WHOIS++ server be listening on?: Set this to a port that you are currently not using on the machine. In this document we'll call this NEWPORT.

There maybe some other options that you wish to change based on your local situation - all the Configure options are documented in the ROADS v2 technical documentation or by using perldoc on the Configure program.

Now a web server will need to be configured to point to where the new ROADS v2 CGI scripts and HTML documents will live. There is the choice of either running a completely new instance of the web server or making the current web server map the new ROADS v2 CGI scripts and HTML documents into its document space at additional, new temporary locations. The former method is known to work with older HTTP daemons such as the CERN 3.0 server whilst the second method is more amenable to modern servers such as Apache as it reduces the number of processes that have to be running on your machine. The actual details of how this configuration is done will depend on the actual HTTP daemon in use; please refer to its documentation for details of how to configure it. You might also want to configure the server to protect at least the ROADSv2/admin-cgi directory from access outside of a known set of administators.

The installation can now be finished by using your web browser to access http://your.server.edu/ROADSv2/admin-cgi/admincentre.pl and then index your records and start your WHOIS++ server. If the admincentre.pl doesn't work check your web server is configured correctly, that the script is executable by the user that the web server is running as and that the path you supplied to the Perl interpreter in the Configure script is correct. As a last check that your initial installation is working, try contacting your WHOIS++ daemon. Do this using http://your.server.edu/ROADSv2/cgi-bin/search.pl CGI script and check that you can retrieve a known record from your database. If you have problems check the above problem list, plus ensure that the new WHOIS++ server is running and you can contact it. You can check the last part by telneting to your server machine using the port you specified for the WHOIS++ daemon. If its up and running you should get a welcome message and you can then type in a query directly. If problems persist refer to the ROADS v2 technical documentation or contact roads-liaison@bris.ac.uk.

CONFIGURING AND CUSTOMISING

Now that you have a working ROADS v2 installation using your existing data, you can start to reconfigure and customise the installation. Many of the configuration files are similar between ROADS v1 and ROADS v2 but as there are some changes it is worth making modifications by hand to the distributed defaults based on the values in your original installation rather than simply copying your existing configuration files over.

Configuration files to check for customisations are:

NEWROADS/config/outlines/: This directory contains the outlines of the template types you can use, along with configutation options for the web based template editor. If you've added new templates or modified existing template outlines in v1, you'll want to transfer the changes over now.
NEWROADS/config/mktemp-views/: This directory contains the editing views for the web based template editor. If you've any local editing views you'll need to add these in here (making sure that the attributes in these files match up with the associated files in the above outlines directory).
NEWROADS/config/class-map
NEWROADS/config/subject-listing: These two are used to control the generation of subject listings. If you've configured subject listings in ROADS v1 you'll need to transfer the settings over here. Note that you can have multiple class mapping files and they don't need to be called class-map as that can be specified in the subject-listing configuration file or on the command lines of bin/addsl.pl and bin/cullsl.pl
NEWROADS/config/whats-new: This directory contains the configuration files for the bin/addwn.pl and bin/cullwn.pl programs. These will need to be updated if you have changed the defaults in ROADS v1. Note that in ROADS v2 there is a Mailshot configuration file that might be suitable for making whats-new mailshots to regular users (though you'll need to create your own mailing lists and associated software).
NEWROADS/config/languages: This file contains a list of the language codes and character sets and the associated relative path from NEWROADS/config/ to the directory holding all the script directories that contain the HTML documents and fragments in the appropriate language and character set. You should be able to tranlate any settings that you have used in ROADS v1 more or less directly because although the multilingual support in ROADS v2 has been considerably improved, this file has the same format.
NEWROADS/config/multilingual/: This directory contains a directory for each language supported (shipped only with a full set of UK-English) which in turn contains subdirectories for each of the ROADS CGI scripts that in turn contain the HTML documents and fragments return by the scripts. These will almost certainly need to modified to give the site the look and feel you desire. Some simple HTML documents can be transfered almost unchanged from ROADS v1 but pay attention to the documents used by cgi-bin/search.pl, admin-cgi/admincentre.pl, admin-cgi/admin.pl and admin-cgi/mktemp.pl as these scripts have lots of new options available.
NEWROADS/config/admin-restrict
NEWROADS/config/search-restrict: These two files specify the attributes in templates that can be searched and returned to either administrators or normal users. The defaults are probably sane for most installations but if you modified your v1 restrictions, added new template types or modified existing template outlines you might wish to check these.
NEWROADS/config/authority/: This directory contains sub-directories for various template types which themselves contain files named after attributes in that template. These files contain the authority lists for use with the web based template editor. If you have installed authority files in ROADS v1 you'll need to transfer these over to here.
NEWROADS/config/databases: If you make use of virtual databases within a single ROADS installation, you'll need to modify this file. The format is the same as in ROADS v1.
NEWROADS/config/protocols: This file lists protocols that should be waylaid rather than returned directly to the user. It tells ROADS what the protocol scheme name is and the HTML file to use. For most installations the defaults should be fairly sane but if you have lots of records using strange protocols that most web browsers can not handle by default you might want to add them in here.
NEWROADS/config/stopattr
NEWROADS/config/stoplist: These two files specify the list of attributes in templates not to index or search on and the list of stopwords that are also ignored. If these have been modified in ROADS v1, you might want to transfer the settings across to the new installation.

MOVING TO V2

Once you think you've got the configuration to your taste and checked all the search and administration programs that you use are working and look OK, its time to move over from ROADS v1 to ROADS v2. The first thing to do is to make sure that any templates that have been added to your existing installation are copied into the NEWROADS/source directory and the database is reindexed.

Now shut down the new WHOIS++ server from the http://your.server.edu/ROADSv2/admin-cgi/admincentre.pl and then tweak the NEWROADS/config/databases to point to the port that the existing ROADS v1 server is running on.

Next stop the existing ROADS v1 WHOIS++ server from your existing admincentre.pl and then quickly restart the new WHOIS++ server from http://your.server.edu/ROADSv2/admin-cgi/admincentre.pl. This is the point when most users will notice a service distruption so this should be done during your server's normal at risk maintanence period.

At this point your end users will see the data from your new WHOIS++ server via the old ROADS v1 HTML forms and CGI scripts. The last thing to do to transfer to ROADS v2 is to reconfigure your HTTP daemon to point to NEWROADS/htdocs, NEWROADS/cgi-bin and NEWROADS/admin-cgi using the web document space paths that you have been using for the ROADS v1 installation. Once again how you do this will depend upon the HTTP daemon that you use and you should consult your daemon's documentation.

You should now find that you have a working ROADS v2 installation in production service in place of your previous ROADS v1 installattion. If space is an issue you might want to backup the old ROADS v1 installation to offline storage and then delete the old installation. You may also want to review the ROADS v2 technical documentation to find out what new features are available in ROADS v2 to improve services to end users and make administrators lives easier.