/usr/share/doc/refdb/refdb-manual/ch04s08.html is in refdb-doc 1.0.2-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Finishing the RefDB installation</title><link rel="stylesheet" type="text/css" href="manual.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="RefDB handbook" /><link rel="up" href="ch04.html" title="Chapter 4. Installation" /><link rel="prev" href="ch04s07.html" title="Other operating systems" /><link rel="next" href="ch04s09.html" title="Testing your installation" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Finishing the RefDB installation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s07.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Installation</th><td width="20%" align="right"> <a accesskey="n" href="ch04s09.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sect1-set-up-database"></a>Finishing the RefDB installation</h2></div></div></div><p>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.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp67605488"></a>Using the interactive setup script</h3></div></div></div><p>The interactive script <a class="link" href="re09.html" title="refdb-init"><span class="command"><strong>refdb-init</strong></span></a> 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 <a class="link" href="ch04s08.html#sect2-manual-setup" title="Manual setup">manual installation</a>.</p><p>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 <a class="link" href="ch04s08.html#sect3-catalog-files" title="The SGML/XML support files">SGML catalog file</a>.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect2-manual-setup"></a>Manual setup</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="idp67611280"></a>Configuration files</h4></div></div></div><p>Now is the time to create the global configuration files described in the <a class="link" href="ch04s03.html#sect1-mystery-init-files" title="The mystery of the configuration files">configuration file</a> section. Create these files in <code class="filename">/usr/local/etc/refdb</code> (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.</p><p>The <code class="filename">refdbdrc</code> configuration file can be copied from one of the templates <code class="filename">refdbdrc.mysql.example</code>, <code class="filename">refdbdrc.pgsql.example</code>, <code class="filename">refdbdrc.sqlite.example</code>, or <code class="filename">refdbdrc.sqlite3.example</code> according to your choice of the database engine.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="idp67617600"></a>Configuring your database server</h4></div></div></div><p>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.</p><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="idp67618928"></a>MySQL</h5></div></div></div><p>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 <span class="command"><strong>mysqld</strong></span> command-line option <code class="option">--default-character-set=charset</code>, or add a "default-character-set=charset" entry to a suitable MySQL configuration file. A list of available encodings is usually installed as <code class="filename">/usr/local/share/mysql/charsets/Index</code>. In MySQL versions 4.1 and later each database (in fact, each table) may have one of various character encodings.</p><p>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 <code class="option">--skip_networking</code> option from the MySQL start script or from the appropriate MySQL configuration file.</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="idp67623760"></a>PostgreSQL</h5></div></div></div><p>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 <span class="command"><strong>postmaster</strong></span> with the <code class="option">-i</code> command line option to switch on TCP/IP support.</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="idp67626544"></a>SQLite</h5></div></div></div><p>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.</p><p>SQLite version 3.0 and higher uses UTF-8 as the default encoding which is just fine for the purposes of RefDB.</p></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="idp67628912"></a>Creating the databases</h4></div></div></div><p>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 <span class="command"><strong>refdbd</strong></span> handle the installation, but for special needs there is also a description how to set up the databases using the database engine clients.</p><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="idp67630880"></a>MySQL</h5></div></div></div><p>As mentioned above, the recommended way to create or update the main database is to run the following command from your root account:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>refdbd -a -u username -w password</code></strong>
</pre><p>Specify the username and password of your database administrator account.</p><p>If the default setup described above does not suit your needs, please use the following procedure instead to set up the main database.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If <code class="filename">mysqld</code> (the MySQL database server) is installed on a remote box or if the security settings require it, you may have to use the <code class="option">-h <em class="replaceable"><code>hostname</code></em></code> and/or the <code class="option">-u <em class="replaceable"><code>username</code></em></code>/<code class="option">-p <em class="replaceable"><code>password</code></em></code> options to run the <code class="filename">mysql</code> client as shown below (most fresh MySQL installations use "root" with no password as the default database administrator). <code class="filename">mysqld</code> needs to be up and running and you need the appropriate permissions, of course. See the <span class="application">MySQL</span> documentation for further details.</p></div><p>Instead of using <span class="command"><strong>refdbd</strong></span>, you can also use the hard way and create the main database using your database engine client:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>In a command line window, run the following command to create the database "refdb":</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>mysql -u root -e "CREATE DATABASE refdb"</code></strong>
</pre></li><li class="listitem"><p>Then create the tables and fill in the data. For MySQL older than 4.1, run:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>mysql -u root refdb < /usr/local/share/refdb/sql/refdb.dump.mysql</code></strong>
</pre><p>For MySQL 4.1 and later, run this instead:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>mysql -u root refdb < /usr/local/share/refdb/sql/refdb.dump.mysql41</code></strong>
</pre><p>Adapt the path to the script accordingly if you configured RefDB to put the data directory somewhere else.</p><p>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:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>sed 's/MyISAM/InnoDB/' < /usr/local/share/refdb/sql/refdb.X.dump.mysql41|mysql -u root refdb</code></strong>
</pre><p>Use the highest dump file number 'X' shipped with your current RefDB version. See the <a class="ulink" href="http://www.mysql.com" target="_top">MySQL documentation</a> for further information about the table engines available with MySQL.</p></li></ul></div></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="idp67657024"></a>PostgreSQL</h5></div></div></div><p>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 <span class="command"><strong>refdbd</strong></span> create the main database:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>refdbd -a -u username -w password</code></strong>
</pre><p>Specify the username and password of your database administrator account.</p><p>If the default setup described above does not suit your needs, please use the following procedure instead to set up the main database.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Your PostgreSQL administrator accound may not have the privileges to write to the PID file. In that case, add something like <code class="option">-P /var/tmp/refdbd.pid</code> to the command line mentioned above. If <code class="filename">postmaster</code> (the PostgreSQL database server) is installed on a remote box or if the security settings require it, you may have to use the <code class="option">-h <em class="replaceable"><code>hostname</code></em></code> and/or the <code class="option">-U <em class="replaceable"><code>username</code></em></code> options to run the <code class="filename">psql</code> 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 <span class="command"><strong>su root</strong></span>, then <span class="command"><strong>su postgres</strong></span>). <code class="filename">postmaster</code> needs to be up and running and you need the appropriate permissions, of course. See the <span class="application">PostgreSQL</span> documentation for further details.</p></div><p>Instead of using <span class="command"><strong>refdbd</strong></span>, you can also create the main database using your database engine client:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>In a command line window, run the command:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>createdb -U pgsql -E UNICODE refdb</code></strong>
</pre><p>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.</p></li><li class="listitem"><p>Then run this command:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>psql -U pgsql refdb < /usr/local/share/refdb/sql/refdb.X.dump.pgsql</code></strong>
</pre><p>Use the highest dump file number 'X' shipped with your current RefDB version. 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.</p></li><li class="listitem"><p>Access control works through user groups. To be able to access the main database, create a RefDB user group like this:</p><pre class="screen">
<code class="prompt">~$ </code><strong class="userinput"><code>psql -U pgsql refdb -c "CREATE GROUP refdbuser"</code></strong>
<code class="prompt">~$ </code><strong class="userinput"><code>psql -U pgsql refdb -c "GRANT SELECT ON CITSTYLE, POSITIONS, REFSTYLE, SEPARATORS, t_journal_words, t_meta TO GROUP refdbuser"</code></strong>
</pre></li></ul></div></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="idp67683504"></a>SQLite</h5></div></div></div><p>Run the following command from your root account to let <span class="command"><strong>refdbd</strong></span> create the main database:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>refdbd -a</code></strong>
</pre><p>If the default setup described above does not suit your needs, please use the following procedure instead to set up the main database.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The default database directory is <code class="filename">/usr/local/var/lib/refdb/db</code>. 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 <code class="varname">dbpath</code> variable in <code class="filename">refdbdrc</code> and modify the following instructions accordingly.</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>cd /usr/local/var/lib/refdb/db</code></strong>
</pre></li><li class="listitem"><p>Run the following command to create the database and load the data:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>sqlite refdb < /usr/local/share/refdb/sql/refdb.X.dump.sqlite</code></strong>
</pre><p>Use the highest dump file number 'X' shipped with your current RefDB version.</p></li></ul></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="sect3-catalog-files"></a>The SGML/XML support files</h4></div></div></div><p>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 <code class="filename">/usr/local/share/refdb</code>) and its subdirectories, but you should spend a little time to integrate them into your SGML system.</p><p>To this end, add the catalog file <code class="filename">/usr/local/share/refdb/refdb.cat</code> to your <code class="envar">SGML_CATALOG_FILES</code> environment variable. This is a master catalog with CATALOG directives for all catalog files supplied by RefDB.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="idp67702128"></a>The shell scripts</h4></div></div></div><p>The RefDB shell scripts and Perl scripts were installed in <code class="filename">/usr/local/bin</code> 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 <span class="quote">“<span class="quote">user-customizable section</span>”</span> at the top of each script.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If you want to use a Java XSL processor with the <code class="filename">refdbxml</code> script, you'll have to check the value of <code class="varname">CLASSPATH</code> in the script. The value must match the actual location of your <code class="filename">.jar</code> files and the current versions you've installed.</p></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s07.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s09.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Other operating systems </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Testing your installation</td></tr></table></div></body></html>
|