Installation instructions

Copyright (C) 1999 Jukka Zitting <jukka.zitting@iki.fi>
Copyright (C) 2000 The Midgard Project ry
See the end for copying conditions.

These are the installation instructions of the Midgard address
translation and user authentication module. The module is used by
Apache to map URLs to Midgard database records.

This module uses the GNU configure system for configuration and
installation. The configure script locates the Apache apxs tool and
uses it to compile and install the module. You can configure, build,
install and setup mod_midgard by running:

 $ ./configure
 $ make
 # make install
 # make conf

The module needs to find the Midgard library and the apxs tool in
order to compile and install properly. If the configure script is
unable to find them, then you can specify the following options to aid 
the script:

  --with-apache=DIR    Apache source directory.

  --with-apxs=APXS     Full path to apxs

  --with-midgard=DIR   Prefix of the Midgard installation.
                       The header file midgard.h should be in
                       DIR/include, and the library libmidgard in
                       DIR/lib.

  --with-mysql         Installation location of the mysqlclient
                       include file and libraries

  --with-expat         Installation location of the expat
                       include file and libraries

Run "./configure --help" for more information.

If the configure script cannot find the Midgard library even if you're
sure that the library is in place and that you have given the correct
--with-midgard option, then the problem might be caused by a
misconfigured dynamic library loader. On Linux, you can check this by running
the command:

  $ /sbin/ldconfig -p

that prints all the dynamic libraries on the system. Check that this
listing contains BOTH the libmidgard and libmysqlclient libraries. If
not, then you should locate the libraries and add their directory
paths to the file /etc/ld.so.conf. Then you should run the command

  # /sbin/ldconfig

as root to recreate the library cache.

For other platforms, make sure that the location of these libraries is
in your LD_LIBRARY_PATH, and that it is set in the scripts that start
apache.

The module is installed as a dynamically loadable module to the Apache 
server. The installation system automatically adds the required
LoadModule directive to the httpd.conf file. The Midgard root files
"midgard-root.php3" (for php3) and "midgard-root.php" (for php4) are
installed by default in the Apache libexec directory.

** CONFIGURATION DIRECTIVES **

  Syntax:  MidgardEngine [On|Off]
  Example: MidgardEngine On
The MidgardEngine directive turns the Midgard processing on or off
(default). You can selectively enable or disable Midgard processing
in VirtualHost and Location sections.

  Syntax:  MidgardRootfile [full path to rootfile]
  Example: MidgardRootfile /usr/lib/apache/midgard-root.php3
You can use the MidgardRootfile to specify the location of the Midgard
root file (absolute or relative to Apache server root). The default is
libexec/midgard-root.php3, where the default installation puts it.
There should be no need to change this location. The root file does
some initialization and invokes the root template that starts the page
generation process.

  Syntax:  MidgardDatabase [database] [username] [password]
  Example: MidgardDatabase midgard midgard secretpass
You can also use the MidgardDatabase to override the default database
connection attributes defined in the Midgard library (all set to
"midgard"). You can set different databases for different VirtualHosts. If
no databases are defined but MidgardEngine is on, then the default
database defined by the Midgard library is used.

  Syntax:  MidgardBlobDir [directory where the blobs reside]
  Example: MidgardBlobDir /var/www/blobs
Location where the blobs (aka attachments) are stored.

  Syntax:  MidgardDefaultRealm [string]
  Example: MidgardDefaultRealm "my Midgard machine"
Realm string that will be used for user authentication requests for
SG0.

  Syntax:  MidgardParser [encoding]
  Example: MidgardParser russian
The MidgardParser directive sets text formating engine used for internal
text formating and mail message handling. You may select between 'latin1'
and 'russian' values. 'latin1' does conversion of chars using ISO-8859-1 
encoding and converts symbols higher 160 to corresponding HTML entities.
Selecting 'russian' you switch off the conversion described above and
set encoding of mail messages to KOI8-R. Note that Midgard doesn't convert
symbols in mail messages to KOI8-R but expects it from client program.

** HOST CONFIGURATION **
To access the Midgard sites you'll need to set up virtual hosts
for them. You can use either name-, ip- or port-based virtual hosts.
See the Midgard FAQ and Apache documentation for details.

To activate the Midgard admin in the address 'localhost/admin' you
should set up a virtual host like this one:

  # httpd.conf
  <VirtualHost 127.0.0.1>
  ServerName localhost
  # Configure text parser:
  # Change to 'russian' for Russian Midgard
  MidgardParser latin1 
  # Configuration for Russian Midgard - we use mod_charset to automate 
  # re-encoding of page and query's data in respect of client's browser
  <IfModule mod_charset.c>
   # default charset for real or virtual server (selected if all other charset-
   # selections methods fails)
   CharsetDefault koi8-r
   # Default source (on-disk) charset (we keep all content in DB in KOI8-R 
   # encoding). If you want different charset, please re-encode midgard-ru.sql
   # before inserting it into DB too.
   CharsetSourceEnc koi8-r
   # Force mod_charset to do its work
   CharsetDisable Off
  </IfModule>
  </VirtualHost>

Then run the following SQL command to map the Midgard admin site to
the virtual host you just created.

  UPDATE host SET name='localhost',prefix='/admin' WHERE id=1

NOTE: The default administrator username is "admin" and
the password is "password".

Note that you'll need to use the Midgardized PHP module to correctly
parse the Midgard template codes. You shouldn't directly fetch the
Midgard root file as it should be read only by mod_midgard module. 
Do not place the root file inside the Apache document root.

** ADVANCED FEATURES **

  Syntax:  MidgardPageDatabase [database] [username] [password]
  Example: MidgardPageDatabase midgardadmin midgard midgard
The database to fetch page and style information from. You can use
this to partially emulate sitegroups. Pages will be served from this
database but the pages will run accessing data from the database
specified with the 'MidgardDatabase' directive. You can put shared
sites in such a database, and these sites will be available while
access to the data in them is totally prohibited.

  Syntax:  MidgardAuthDatabase [database] [username] [password]
  Example: MidgardAuthDatabase midgardadmin midgard midgard
The database to authenticate from. You can use this to arrange access
to sites served from databases where you have no Midgard user account.
Used in combination with MidgardPageDatabase and MidgardDatabase.
Users authenticated from this database will be granted full
(root-level) access no matter what.

  Syntax:  MidgardAuth [On|Off]
  Example: MidgardAuth On
Allow authentication against the midgard database for regular apache
'require' protection.

  Syntax:  MidgardTemplate [filename]
  Example: MidgardTemplate elements.xml
Name of the style element files used for filetemplates.

----------------------------------------------------------------------
Copyright information:

Copyright (C) 1999 Jukka Zitting <jukka.zitting@iki.fi>
Copyright (C) 2000 The Midgard Project ry

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and this permission notice are preserved,
   thus giving the recipient permission to redistribute in turn.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them.
^L
Local variables:
version-control: never
mode: indented-text
end:
