Installation instructions

Copyright (C) 2000 The Midgard Project Ry

These are the installation instructions for the Midgard default
database that contains the Midgard Admin and Example sites.

** IMPORTANT -- WHEN UPGRADING *********************************
Midgard 1.4 supports everything that was supported by Midgard 1.4beta3
or earlier, but has since added features to the core that require extra
fields in your database. You will need to run database-upgrade to prepare
your database for running with 1.4 or later. This will add fields and
tables where necesary. It is safe to run this script against a database
that is allready up to date -- it tests for existance of fields and
tables and only tries to add them if missing. It does not alter data in
your database, nor does it add data.

After upgrading you can still choose to install the datapackage in
order to install Asgard if you want it.

AS ALWAYS, BACKUP BEFORE INSTALLING DATA
****************************************************************

Midgard 1.4 includes two variants of Administrative interfaces.
First one is old-fashioned Midgard Admin Site from 1.2.x series
of Midgard Suite. It doesn't support all features of Midgard 1.4
and provided for backward compability for transition period
during which new admin site, Asgard, will replace it.

Asgard fully supports Midgard 1.4 features. It has been localized
to several languages and may be installed into existing database
without removal of previously created data. We are aware about
several problems with it though and will eliminate them in future.
If you are starting with Midgard 1.4, Asgard is your choice.

Installation process is separated into two phases.

NOTE: If you're using Midgard earlier than 1.4-beta6, please
run database-upgrade before doing anything else. Database-upgrade
script requires MySQL support from Perl (Perl's DBD:Mysql module).

1. Configuration of install script.

Midgard is complex suite and allows flexible configuration of
its parts. Installation script uses many variables which better
to enter once and re-use later. Thus, configure script is used
to store these values. You can pass following options to
configure script:

--with-db-host=host                   hostname of the database server
--with-db-admin-user=user             username of the database administrator
--with-db-admin-password=password     password of the database administrator
--with-db-user=user                   username of the midgard database user
--with-db-user-password=password      password of the midgard database user
--with-db=databasename                database name
--with-host=hostname                  hostname of this machine
--with-ip=ipaddress                   IP address of this machine
--with-port=portnumber                port number for this server
--with-blobdir=DIR                    directory where BLOBs will be stored
--with-pagecache=DIR                  directory where MMP will store generated
                                      pages
--with-midgard=DIR                    installation directory of Midgard
--with-apxs=PROGRAM                   full path of the apxs binary
--with-apache-user=user               username that apache runs as
--with-apache-group=group             group that apache runs as
--with-adminsite                      install the 1.2.5 adminsite
--with-lang=language                  the 1.2.5 adminsite language
--with-asgard                         install the Asgard admin site
--with-asgard-ru                      install the russian translation for Asgard
--with-php=version                    defaults for php version 3 or 4
--with-install=new|upgrade            install new database or upgrade existing
  
Omitted options will have default values or will be gathered from 
operating system environment.

1.1.  --with-db-admin* options specify username and password of MySQL's
      administrator. These values is needed to setup correct access rights
      for Midgard database user.

1.2.  --with-db-user* options specify username and password for Midgard
      database user. Midgard uses these values in Repligard replication
      utility and mod_midgard Apache module configuration. These default
      to 'midgard'/'midgard'

1.3.  --with-host, --with-ip, --with-port specify host name, IP address,
      and port of Apache virtual host which will serve Midgard Administrative
      interface. These values will be used in midgard-data.conf file to
      form complete Apache's virtual host with Midgard configuration.

1.4.  --with-db specifies name of Midgard database. It will be created by
      installation script and defaults to 'midgard'.

1.5.  --with-lang specifies language for old Midgard Admin Site interface.
      There are two values currently: 'en' and 'ru' for English and Russian
      respectively. You need to specify it if you still want to use old
      Admin Site. Option defaults to 'en'.

1.6.  --with-blobdir specifies path to Midgard Blob directory where BLOBs
      are stored. This option defaults to /var/www/blobs and you need
      to specify it if you're using different location. Required.

1.7.  --with-midgard specifies path to Midgard library installation. Configure
      script automatically determines correct value if you installed Midgard
      to /usr or /usr/local. If your installation differs from it, please
      point configure script to right location with this option.

1.8.  --with-apxs specifies path to Apache's apxs utility. Configure script
      tries to find it in order to gather path to Apache's loadable modules
      and uses it as path where the midgard root file should be.

1.9.  --with-apache-user specifies the user that apache runs as.
      Common values are 'apache', 'nobody' and 'www-data'. There's no
      default for this -- check into your apache configuration and
      find the User directive. Required.

1.10. --with-apache-group specifies the group that apache runs as.
      Required but defaults to the value supplied for
      --with-apache-user. This should match the value of the Group
      directive in your apache configuration.

1.11. --with-php=<version> specifies which PHP version to set up for.
      Required, but it defaults to 4 these days since we no longer
      support 3.

1.12. --with-install=[new|upgrade] specifies whether you're doing a
      fresh install or a database upgrade. Specifying 'new' WILL OBLITERATE
      the database specified WITHOUT COMMENT if it exists. 'upgrade' will
      only work if you've previously done a 'new'. Required.

Example:

./configure --with-db-admin=root \
	    --with-db-admin-password=foo \
	    --with-blobdir=/home/apache/blobs \
	    --with-apxs=/usr/sbin/apxs \
	    --with-install = new


2. Installation

Install script is called 'dbinstall' and created by configure script
from dbinstall.in template. This script takes all its values from the
configure run so it will run without stopping for questions. dbinstall
actually does the database installation work, so the OBLITERATION part
mentioned above only happens when you run this script.

The configure script will also create a sample config file for Apache
called midgard-data.conf. Put it into Apache's config directory and
include into main Apache's config file by

   Include /etc/httpd/conf/midgard-data.conf

directive (substitute /etc/httpd/conf by correct path on your system).

3. Copying images and accessing Midgard admin sites

Copy 'example' and 'midgard' subdirectories with images to Apache's
DOCUMENT_ROOT (Usually it is /home/httpd/html or /var/www/html).

After that, restart Apache and point your browser to specified
hostname/port to directory /asgard/, for example:

netscape http://myhost.mydomain:80/asgard/

The defaults for hostname and port are 'localhost' and '80'
respectively, so if you left defaults for all non-required configure
options, you would access it thus:

netscape http://localhost/asgard/

If you want to have remote access from the start you can use the
--with-host option to specify the name of the server. IMPORTANT
NOTICE: this puts the admin interface online with a well-known
administrator password. Please change it immediately.

Enter 'admin' as username and 'password' as password. You'll be logged
in as Midgard Administrator.

If you installed old Midgard Admin site only then point your browser to
directory /admin/:

netscape http://myhost.mydomain:80/admin/

Happy work with Midgard!
