INSTALLATION INSTRUCTIONS for the Globule Broker System (GBS)
=============================================================

NOTE: The Globule Broker System is normally not installed by end-users of
Globule.  They would rather make use of a third party who provides the broker
system as a service.  The Vrije Universiteit provides such a free service
which is available at <URL:http://www.globeworld.net/>.

Since the Globule Broker System is a pure web application, it requires
no pre-installation configuration or compilation.

Installation therefore consists only of five steps:
1. checking the prerequisites;
2. configuring the apache server to use the GBS web application;
3. installing/copying the web application to the proper directory;
4. loading the database with skeleton-information
5. bootstrapping the final configuration file.

Upgrading normally only requires a repeat of step 3 ONLY.  This assumes
that the database schemas from one version to another haven't changed.
To this end, always check the NEWS file first before upgrading.


PREREQUISITES

- Globule-enabled Apache web server, see <URL:http://www.globule.org/>.
  It should be a recent Globule module, at least version 1.3.0, which
  in it's turn requires at least Apache httpd version 2.0.52.
- PHP 5.x
- MySQL 4.1.x

for re-building the documentation (normally not required):
- LaTeX and usual tools such as dvips, GNU-make, etcetera
- Hevea from: http://pauillac.inria.fr/~maranget/hevea/

The best way to get a working Apache installation with Globule and PHP
is to use the source installer script provided by Globule.  This installer
script will install all the prerequisites in one setup.  The installer
script can be used as such:

	./installer.sh --keep-build --omit-start

The installer script is available from the Globule web site:
<URL:http://www.globule.org/>


CONFIGURATION OF "httpd.conf"

It is required that you enable the support for PHP in your Apache
configuration, and add support for named virtual hosting and have a spare
hostname to use (in our case this will be www.globeworld.net).  Setting up
this is beyond the scope of this installation guide, refer to PHP and Apache
documentation.  The httpd.conf as build and supplied by the source based
installer script of Globule will provide a working httpd.conf to add the
section below.

Having your initial httpd.conf, which will be replaced later on, you need
to add a section like such:

	<VirtualHost *>
	  ServerName www.globeworld.net
	  DocumentRoot .../www.globeworld.net/htdocs
          ErrorLog     .../www.globeworld.net/logs/gbs-error.log
          CustomLog    .../www.globeworld.net/logs/gbs-access.log common
        </VirtualHost>

Replacing the www.globeworld.net with your own hostname and ... with the
ServerRoot path where your documents in htdocs also normally reside.  Create
the directories used by the DocumentRoot and log directives, otherwise Apache
will silently refuse to start.
Restart your Apache server.


INSTALLING FILES

Copy the files from the htdocs directory of this distribution into the
DocumentRoot directory and do not forget to make them of the user/group by
which the httpd server worker tasks are running (The User and Group run-time
directives of Apache).  For example, I need to use the following sequence:

	cp -a htdocs/* /usr/local/globule/www.globeworld.net/htdocs
	chown -R nobody:svn /usr/local/globule/www.globeworld.net
	chmod -R go+rX /usr/local/globule/www.globeworld.net
	chown root:root /usr/local/globule/www.globeworld.net/logs
	chmod 700 /usr/local/globule/www.globeworld.net/logs

Which is based on an Apache installed by root in /usr/local/globule and with
the directives "User nobody" and "Group svn" (used by subversion, your group
is probably either www or nobody).
Replace www.globeworld.net with your chosen hostname.  Edit in the DocumentRoot
the file "constants.php", and change the definition of G_BASE_NAME, C_DOMAIN
and G_FETCH_PREFIX to also reflect your chosen host/domainname.  Also
set the G_REDIR_NAME to the real hostname of the machine hosting the equivalent
of your www.globeworld.net.


DATABASE INITIALIZATION

Make sure your MySQL database is running, and connect to it.  If you use the
source based installer installation of Globule, there might be multiple MySQL
servers running on your system.  To connect to the right one, use the right
MySQL client binary.  Thus if your installer script used the prefix
/usr/local/globule, make sure to use the program /usr/local/globule/bin/mysql
to connect to the MySQL server.

Now give the MySQL server the following command:

	GRANT ALL ON gbs.* TO 'gbs'@'localhost' IDENTIFIED BY 'gbs';
	CREATE DATABASE gbs;

Also load the skeleton database schemas from the GBS package which are stored
in the package in file "db/gbs-dump.sql".  This can be accomplished using
a command similar to:

	/usr/local/globule/bin/mysql --user=gbs --password=gbs \
	                             gbs < db/gbs-dump.sql

Enter the MySQL client program again and give the server the commands below,
replacing globeworld.net with your domain and the ip number of the server
you are using:

	UPDATE `Servers` SET ip = '130.37.193.70', \
	       hostname = 'www.globeworld.net' WHERE ServerID = '2';

	UPDATE `Sites` SET name = 'www.globeworld.net/' WHERE SiteID = '1';

Note that this wipes out any existing data for the GBS, so do not use this
if you are reinstalling and want to preserve any data.



BOOTSTRAPPING "httpd.conf"

Surf with a WWW browser to http://www.globeworld.net/, or rather, the by
you elected address.  Log in with username "Globule" and password "geheim".
Change the password and optionally the personal details using the "Personal
Details" side bar menu.

Use the "Servers" -> "View Server(s)" in the left side menu.

Use the icon "Generate Apache Configuration file" in the "Default Action" line
and "Download Config File" in the next page.

Save the resulting file as "httpd.conf".  This Apache configuration file will
now replace the previously setup httpd.conf.  However always keep a copy
of your old configuration file in hand, in case something screws up.
You can edit the httpd.conf in certain ways to reflect your local setup.
If you have used the installer script to install Apache and Globule you
mostly do not have to change things.  You should however check the following
items in the httpd.conf, and correct them if necessary:
- The "User" and "Group" directives should use the correct username and
  group of the files.  The default "apache" may not be applicable on all
  systems.
- The mime.types may reside in a different path.  Especially with the
  installer script, change conf/mime.types to etc/mime.types.

Since your server will act as Globule Broker System web site and as a
stand-alone redirector for others, it will need to regulary modify it's own
configuration file, in order to play the role of redirector for new sites.
Using the globulectl utility the site can load a new version of the httpd.conf
configuration file from it's own web site.  In other words: the site maintains
and generates it's own configuration file httpd.conf.

You are however allowed to make certain changes and additions in the
httpd.conf, so the globulectl utility will try to incorporate your changes in
newly downloaded versions of the httpd.conf file.  This patching between
re-generations of the configuration file may fail in certain cases so a backup
httpd.conf is kept however you should keep a record of your changes too.