Installing the O-and-A Search on Your Web Site

The Ordinary and Armorial of the SCA is a web-based searchable database of the names and armory registered by the SCA College of Arms over the last five decades.

At its core, the O&A consists of a 125,000-line pipe-delimited text file named “oanda.db” which typically contains a line for each registered item. (Although note that in some cases a name and associated armory are bundled together into a single line, and other times updates result in there being a couple of lines that document a single registration.)

Generally speaking, nearly everyone interacts with this data via the O&A web site, maintained by the SCA’s Morsulus Herald, but in theory you could just read through that text file to find relevant records, or utilize one of the small number of third-party applications which transform the oanda.db file into an e-book or import it into a third-party database engine.

The software that powers the O&A web site is open-source, and packaged in a way that makes it easy to install, as long as you have a machine that meets these requirements:

• Unix-like operating system.
• Perl 5.
• A web server with CGI support.

There are two main elements to the O&A software:

• A set of HTML pages and CGI scripts that constitute the user interface of the web site.
• A long-lived server-side process called “the database server” which reads the oanda.db file and listens to a local port, then forks off child processes to respond to queries.

The CGI scripts do not access the oanda.db data directly; instead they send requests to the database server using a simple text protocol, and format the results they receive from it into HTML responses to send back to the browser.

If you’d like to run your own copy of this software, follow the below procedure:

1. Configure your web server to host another site, or allocate a subdirectory within one of your existing web sites, and record the following information:
   • Hostname
   • URL for the web site (without a trailing slash)
   • Path to web document root directory (without a trailing slash)
   • Path to log directory
2. In a terminal window, log in to the web server, and cd to the web document root directory.
3. Download the installation script and the database and category files.
   • curl -O http://oanda.sca.org/config.web
   • curl -O http://oanda.sca.org/oanda.db
   • curl -O http://oanda.sca.org/my.cat
4. Run the installation script.
   • perl config.web
5. The installation script will prompt you for a number of configuration parameters required for setup. For most of them you can just press return to accept the default, but in a number of places you will need to paste in one of the configuration values you recorded earlier.
   • Accept the defaults for the Perl path and the numeric codes for networking constants.
   • For the hostname, enter the web hostname from above.
   • Accept the default for the server port.
   • For the document root path, enter the path from above.
   • As the local directory for O&A web pages, enter the document root path again, omitting the suggested /heraldry/OandA, ending, unless you want to install in a subdirectory.
   • For the URL, enter the new site’s web address, omitting the suggested :80 ending.
   • Accept the defaults for the location of the database file, ordinary, and CGI scripts.
   • Enter the document root path followed by /common.pl as the install-path for common Perl code.
   • Accept the defaults for the database server hostname, port, and install path.
6. When you’ve completed the configuration procedure, the script will unpack various HTML files and CGI scripts and install them according to the choices you’ve specified.

The configuration values you entered are written to a file named .configweb and re-used as the defaults if you run the script again, so if you encounter an error and need to tweak any of the values, you can re-run the script and just press return repeatedly until you arrive at the value you want to change.

That procedure will have created all of the HTML pages and CGI scripts, and will have output a new file named configdb, which must be run to set up the database server.

1. Run the installation script.
   • perl configdb
2. The installation script will prompt you for a number of configuration parameters required for setup. For some of them you can just press return to accept the default, but in a number of places you will need to paste in one of the configuration values you recorded earlier.
   • Accept the defaults for the Perl path and the numeric codes for networking constants.
   • For the path to the category file, enter the document root path followed by /my.cat.
   • For the path to the database file, enter the document root path followed by /oanda.db.
   • For the path to the server script, enter the document root path followed by /oanda_server.pl.
   • For the log file path, enter the log directory path followed by /dbserver.log
3. When you’ve completed the configuration procedure, record the suggested command used to start the database process, and press return when the script offers to start it for you.

As with the first setup script, the configuration values you entered are written to a file named .configdb and re-used as the defaults if you run the script again.

You should now be able to visit your web site and have a working O&A interface, just like the one at oanda.sca.org.

In order to ensure that the database process starts up when your server reboots, you can put a copy of the server-start command into /etc/rc or whatever system your server uses to manage startup scripts.

For convenience, I set up a pair of shell scripts to start and stop the database process:

• cat > ./dbserver-start.sh
  #!/bin/csh
  nice <YOUR-WEB-PATH>/oanda_server.pl >>& <YOUR-LOG-PATH>/dbserver.log &

• cat > ./dbserver-stop.sh
  #!/bin/csh
  killall oanda_server.pl

With those in place, you can fetch the latest copy of the O&A data from the SCA.org server by running the following:

• ./dbserver-stop.sh
• curl -O http://oanda.sca.org/oanda.db
• curl -O http://oanda.sca.org/my.cat
• ./dbserver-start.sh

To monitor the activity of the database process, run tail -f against the log file.