This step is necessary for all platforms. You have to create some databases for RefDB to start with and you should make the RefDB SGML/XML support files known to your system. In most cases you will prefer to use a script provided with RefDB which performs all things required for a first-time installation. If you need more precise control, you'll also find instructions below how to set up RefDB manually.
The interactive script refdb-init must be run with root permission as it tries to fiddle with a couple of files that a regular user should not have write permission for. After starting the script, it will collect a few answers from you about your intended setup. It will also perform a couple of sanity checks. After this stage is completed, you will be asked to positively confirm whether or not your system should be modified. Therefore it is safe to dry-run this script in order to decide whether you prefer the script over the manual installation.
The script creates the main database, the refdbd and refdba configuration files, loads the available styles, creates a reference database and a database user account. All that is left to do manually is to take care of the SGML catalog file.
Now is the time to create the global configuration files described in the configuration file section. Create these files in /usr/local/etc/refdb (or whatever you chose during configuration). It is recommended to copy and modify the commented example configuration files in the same directory. These files are installed with the suffix ".example" to avoid overwriting existing configuration files. All required paths are automatically configured during the installation, so these files are a good starting point for your local modifications.
The refdbdrc configuration file can be copied from one of the templates refdbdrc.mysql.example, refdbdrc.pgsql.example, refdbdrc.sqlite.example, or refdbdrc.sqlite3.example according to your choice of the database engine.
The default installation of all supported database engines should be just fine for running RefDB. However, in some cases a little extra work is needed.
The MySQL engine earlier than version 4.1 supports only one character encoding per server instance. The default encoding is ISO-8859-1, aka Latin-1. If you prefer a different encoding, you have to configure the server at startup. Either use the mysqld command-line option --default-character-set=charset, or add a "default-character-set=charset" entry to a suitable MySQL configuration file. A list of available encodings is usually installed as /usr/local/share/mysql/charsets/Index. In MySQL versions 4.1 and later each database (in fact, each table) may have one of various character encodings.
For security reasons many default installation allow only local connections. If refdbd has to connect to the database server from a different box, make sure to remove the --skip_networking option from the MySQL start script or from the appropriate MySQL configuration file.
Most default installations of this database server allow only local Unix sockets connections due to security concerns. However, the refdbd application server will always talk to the database server via a TCP/IP connection. Please make sure to start postmaster with the -i command line option to switch on TCP/IP support.
The embedded database engine SQLite (versions 2.x) supports two character encodings as a compile-time option: ISO-8859-1 (Latin-1) and UTF-8. The former is the default if you don't use any configure options and if you use prebuilt binaries. If you need Unicode support, you'll have to recompile SQLite using the proper configure switch.
SQLite version 3.0 and higher uses UTF-8 as the default encoding which is just fine for the purposes of RefDB.
The RefDB database contains common information that is shared by all reference databases. The following sections explain the database engine-specific steps. In all cases you have two options: The recommended way is to let refdbd handle the installation, but for special needs there is also a description how to set up the databases using the database engine clients.
As mentioned above, the recommended way to create or update the main database is to run the following command from your root account:
~$refdbd -a -u username -w password
Specify the username and password of your database administrator account.
If the default setup described above does not suit your needs, please use the following procedure instead to set up the main database.
If mysqld (the MySQL database server) is installed on a remote box or if the security settings require it, you may have to use the -h and/or the hostname-u /username-p options to run the passwordmysql client as shown below (most fresh MySQL installations use "root" with no password as the default database administrator). mysqld needs to be up and running and you need the appropriate permissions, of course. See the MySQL documentation for further details.
Instead of using refdbd, you can also use the hard way and create the main database using your database engine client:
In a command line window, run the following command to create the database "refdb":
~$mysql -u root -e "CREATE DATABASE refdb"
Then create the tables and fill in the data. For MySQL older than 4.1, run:
~$mysql -u root refdb < /usr/local/share/refdb/sql/refdb.dump.mysql
For MySQL 4.1 and later, run this instead:
~$mysql -u root refdb < /usr/local/share/refdb/sql/refdb.dump.mysql41
Adapt the path to the script accordingly if you configured RefDB to put the data directory somewhere else.
The above command will create the tables using the MyISAM engine. This is the fastest of the supported engines, but it does not support transactions. If you prefer to use the InnoDB engine instead, use this command:
~$sed 's/MyISAM/InnoDB/' < /usr/local/share/refdb/sql/refdb.2.dump.mysql41|mysql -u root refdb
See the MySQL documentation for further information about the table engines available with MySQL.
You must run the following command either from your root account, or from a special database administrator account (depending on your local PostgreSQL installation). Run this command to let refdbd create the main database:
~$refdbd -a -u username -w password
Specify the username and password of your database administrator account.
If the default setup described above does not suit your needs, please use the following procedure instead to set up the main database.
If postmaster (the PostgreSQL database server) is installed on a remote box or if the security settings require it, you may have to use the -h and/or the hostname-U options to run the usernamepsql client as shown below (most fresh PostgreSQL installations on Unix-style systems use "pgsql" with no password as the default database administrator. The Cygwin port of PostgreSQL uses the name of whoever installed the package, usually "Administrator". On Debian you need to be logged in as user "postgres": first su root, then su postgres). postmaster needs to be up and running and you need the appropriate permissions, of course. See the PostgreSQL documentation for further details.
Instead of using refdbd, you can also create the main database using your database engine client:
In a command line window, run the command:
~$createdb -U pgsql -E UNICODE refdb
The data that you will import in the following steps are UTF-8 data. If you wish to use a different encoding, convert the dump file and adapt the above command accordingly.
Then run this command:
~$psql -U pgsql refdb < /usr/local/share/refdb/sql/refdb.2.dump.pgsql
Adapt the path to the script accordingly if you configured RefDB to put the data directory somewhere else. This SQL script will generate the necessary table definitions and fill in a few values. PostgreSQL will notice you that it is going to truncate a few identifier names. It is safe to ignore these messages.
Access control works through user groups. To be able to access the main database, create a RefDB user group like this:
~$psql -U pgsql refdb -c "CREATE GROUP refdbuser"~$psql -U pgsql refdb -c "GRANT SELECT ON CITSTYLE, POSITIONS, REFSTYLE, SEPARATORS, t_journal_words, t_meta TO GROUP refdbuser"
Run the following command from your root account to let refdbd create the main database:
~$refdbd -a
If the default setup described above does not suit your needs, please use the following procedure instead to set up the main database.
The default database directory is /usr/local/var/lib/refdb/db. RefDB will look here unless you selected a different data directory when configuring the application. If you want to keep your databases somewhere else, use the dbpath variable in refdbdrc and modify the following instructions accordingly.
~$cd /usr/local/var/lib/refdb/db
Run the following command to create the database and load the data:
~$sqlite refdb < /usr/local/share/refdb/sql/refdb.2.dump.sqlite
The RefDB package comes with a few additional scripts and stylesheets for the creation of bibliographies. These files are installed in the package data directory (usually /usr/local/share/refdb) and its subdirectories, but you should spend a little time to integrate them into your SGML system.
To this end, add the catalog file /usr/local/share/refdb/refdb.cat to your SGML_CATALOG_FILES environment variable. This is a master catalog with CATALOG directives for all catalog files supplied by RefDB.
The RefDB shell scripts and Perl scripts were installed in /usr/local/bin unless you chose a different install root during configure. As RefDB attempts to insert the correct settings during the build process, it should not be necessary to manually customize these scripts. If you still want to fiddle with the settings, the variables are clearly marked within a “user-customizable section” at the top of each script.
If you want to use a Java XSL processor with the refdbxml script, you'll have to check the value of CLASSPATH in the script. The value must match the actual location of your .jar files and the current versions you've installed.