Installing an open theory Server (abbr: ot-server)
==================================================

Date of INSTALL: 07.06.2001

The server software ot, version 0.6, is released under the terms of GNU
general public license (GPL), version 2 or higher, published by the Free 
Software Foundation (http://www.fsf.org). This implies the exclusion of 
any warranty using this software. The GPL can be found in document LICENSE
or on the web at http://www.gnu.org/copyleft/gpl.html.

If you got problems due to following this description: Please send me some
hints: stefan@meretz.de - successors will thank it to you. I am really 
not an operating system specialist.

Installing the software requires a LAMP system: Linux, Apache, MYSQL and
PHP3 plus some glue done with PERL and, Sendmail or Postfix as MTA. The
software may run any other combinations of a unix-like OS, a web server
with apache-like features, a fast SQL database, PHP3 running on such
combinations, and other MTAs - however, it has not been tested in any 
other way described here. The following guide implies the use of a 
classical LAMP system, which configurations are presented step by step. 
Please always read READMEs and other description coming with the software
described below.


1. The "L": Linux
-----------------

Any variant of Linux OS, kernel 2.x, should be usable for an ot server. 
Please refer to many manuals describing a safe installation, especially 
when ot runs on an internet reachable web server. The PHP3 should be 
owned by a simple user, not by root. Don't use PHP4 due incompatibilities
with GPL used for open theory server.

Choose a nice base directory for all scripts, e.g. /anypath.
Expand and untar the archive in the base dir with a command like that:

	tar xzf ot.[x.yz].tar.gz

where [x.yz] is the given version number. This creates the following
directory structure:
- /anypath: secure root directory for php includes
- /anypath/ot: root directory for virtual web server
- /anypath/otperl: secure directory for perl scripts
- /anypath/otlog: error log dir
- /anypath/otauth: auth dir for admin scripts
- /anypath/otman: path to open theory manual pages
- /anypath/otman/man1: doc of perl program and MySQL scripts
- /anypath/otman/man3: doc of perl modules used in perl programs
- /anypath/ottxt: texts of some basic open theory projects (see SETUP)
Make sure that ./ot and ./otlog have write access for all (777).


2. The "A" : Apache
-------------------

The most convenient way is to install an newer Apache version with mod_php
and mod_perl, however, the CGI-version should also work. Here, the mod_php
variant is discussed.

The httpd.conf script of apache should be adjusted in a proper way like that:

- Exclude all modules which are not neccessary (e.g. SSL etc.).
  Note, that you have to comment out both the LoadModule and
  AddModule directive.

- Neccessary modules are:

	- mmap_static_module
	- env_module
	- define_module
	- config_log_module
	- mime_module
	- includes_module
	- autoindex_module
	- dir_module
	- alias_module
	- rewrite_module
	- access_module
	- auth_module
	- setenvif_module
	- mod_php
	- mod_perl

- Of course, you should have (see apache docs):

	ServerRoot "/anypath"
	DocumentRoot "/anypath/ot"

- Define an alias:

	Alias /otauth/ "/anypath/otauth/"

- make a directory definition for the authentication like that:

	PerlSetEnv PERL5LIB /anypath/otperl

	<DIRECTORY /anypath/otauth>
		AuthName opentheory
		AuthType Basic
		require valid-user
		PerlAuthenHandler ot_aut
	</DIRECTORY)

Note: You have to restart apache server to enable new settings.


3. The "M": MySQL
-----------------

Install a MySQL version 3.22.27 or newer, avaible at http://www.mysql.com.
Please refer to descriptions how to install MySQL in a safe way.
Create a database "otdb" and a "otuser" with a "password". Then use the
scripts crea_tabs.sql and init_tabs.sql to create and inititialize tables
for the ot server including some basic data for the web pages (ALL texts
reside in database!). The command to do this is like this (% is prompt):

	% mysql otdb -u otuser -p < ot_tabs.sql
	% mysql otdb -u otuser -p < ot_init.sql

Then enter the password. Please do this job on console, because web-based
tools like phpMyAdmin cause errors during import due to HTML-character
conversions.

Edit the file /anypath/const.inc and adjust the following lines
with parameters of your environment:

	$sqlhost = 'localhost';		# hostname
	$sqluser = 'otuser';		# mysql username
	$sqlpw = 'password';		# mysql user password
	$sqldb = 'otdb';		# mysql database name
	$langs = array( 'de', 'en' );	# valid languages, first=default

You can change the order of the given languages. To add a new language,
please refer to file TRANSLATE.


4. The "P": PHP3
----------------

Please use mod_perl version 3.x or higher, but NOT version 4.x due to
lisence incompatibilities. These newer 3.x versions come with
most newer apache versions 1.3.9 or higher. Search for the php3.ini,
generally found at /etc/httpd/ and configure it in a way like that:

	start_open_tag = Off
	# meaning: only <?php ... ?> tags are allowed.

	log_errors = On
	error_log = /anypath/otlog/php.log
	# path and name of the the log file

	include_path = /anypath/
	# this defines the safe base dir for PHP implying
	# that no path has to be used in include or require statements


5. The glue: PERL
-----------------

The Perl installation should be of version 5.005 or higher. Additionally the
DBI and Data_ShowTable packages have to be installed (see
http://www.perl.com). Perl is used for the following tasks:

- managing all mails (with some exceptions, see below) arriving at
  open theory domain (those for mailing lists, and command mails).
- authentication against database

All perl scripts reside in /anypath/otperl/

Edit the file /anypath/otperl/ot_const.pm and adjust the following lines
with parameters of your environment:

 	domain => "yourdomain.dom",		# domain name
	fqdomain => "www.yourdomain.dom",	# full qualified name
	maildom => "yourdomain.dom",		# mail domain name
	listmaster => "listmaster",		# ot listmaster
	bb_addr => "ot",			# ident. for body based mode
	sqlhost => "localhost",			# hostname
	sqluser => "otuser",			# mysql username
	sqlpw => "password",			# mysql users password
	sqldb => "otdb",			# mysql database name
	logpath => "/anypath/otlog/"		# path to logs

Yes, some of them are double defined, for PHP and PERL. However, I didn't
find a way to define them only once. And, it would be a good idea to have a
comfortable make script.


6. The MTA: Sendmail or Postfix
-------------------------------

Sendmail:
Any sendmail release 8.x can be used for the simple task of sending
and relying mails. I recommend a newer version starting from 8.8 which 
include anti spam features and prevention of misuse of relying mail 
by spammers. Due to some complicate configuration tasks with sendmail I
prefer Postfix. And configuration steps are described for Postfix.

Postfix:
Postfix has many advantages comparing to sendmail. Postfix is downward
compatible to sendmail, but uses additional features. It is much easer
to handle virtual mail domains. Postfix uses the /etc/aliases file
known from sendmail, and a /etx/postfix/virtual file, where multiple
domain can be defined.

In file /etc/postfix/virtual please add

	yourdomain.dom blablabla		# line 1
	your.name@yourdomain.dom username	# line 2
	username@yourdomain.dom username	# line 3
	listmaster@yourdomain.dom username	# line 4
	webmaster@yourdomain.dom username	# line 5
	anonym@yourdomain.dom username		# line 6
	@yourdomain.dom ot_mail			# line 7

Please replace yourdomain.dom with your domain (e.g. opentheory.org in case
of the main ot project) and username with your username on the server (where
the mail is forwarded to). Description of lines:

line 1: declare your domain, "blablabla" doesn't matter
lines 2-6: declare some aliases for you, at least the name you use for
footer lines on all pages (see SETUP, 3rd - adjust parameters),
"listmaster", "webmaster", and "anonym".
line 7: all other mail to yourdomain is redirected to alias "ot_mail"

In file /etc/aliases please add:

	ot_mail "|/perlpath/perl /anypath/otperl/ot_mail.pl"

Where /perlpath has to be replaced with path to perl (e.g. /usr/bin). This
means, that all mails - except those defined in /etc/postfix/virtual at
lines 2-6 - are piped to script "ot_mail.pl". This is the general mail
interface of open theory.


7. Setup
--------

The setup of the installed ot-server is described in another document named
SETUP.


Participate!
------------

That's it. You're invited to participate in further development of
ot. Join the project 'dev' by subscribing via
http://www.opentheory.org/member.phtml

Keep on theorizing!
