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

Date of INSTALL: 27.09.2002

The server software ot, version 0.9, 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 find problems in the following 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
PHP 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, PHP 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.

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].tgz

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/otsql: SQL-scripts
- /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)
- /anypath/otbackup: directory for database backups

All PHP-scripts should be owned by the Apache-user and group, usually
wwwrun.nogroup. However, I recommend to create an own user under which the
httpd can run. For example (% is prompt):

	% useradd -c "to run the httpd" -d /anypath -g nogroup -s /bin/false
	-u 200 opentheory

creates a user "opentheory" with group "nogroup" and no login shell. In
addition, following dirs/files must be owned by wwwrun.nogroup or
opentheory.nogroup respectively:

- /anypath/counter.txt
- /anypath/otlog


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

- You may adjust user and/or group to run the httpd under

	- user opentheory
	- group nogroup

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

	ServerRoot "/anypath"
	DocumentRoot "/anypath/ot"
	<Directory "/anypath/ot">

- Use index.phtml as directory index

	<IfModule mod_dir.c>
		DirectoryIndex index.html index.phtml
	</IfModule>

- 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 MySQL version 3.22.27 or higher, including MySQL-client (e.g.
availble at http://www.mysql.com). Please refer to descriptions how to
install MySQL in a safe way.

Move to directory /anypath/otsql:

	% cd /anypath/otsql

Create a database "otdb" (% is prompt, -p asks for root password,
-u root is only necessary if not not logged on as root):

	% mysqladmin -u root -p create otdb

Create an user "otuser" with a "password" (edit ot_user.sql first and choose
an appropriate password) followed by a reload to apply this change:

	% mysql mysql -u root -p < ot_user.sql
	% mysqladmin reload

Then use the scripts ot_tabs.sql and ot_init.sql to create and inititialize
tables for the ot server including some basic data for the web pages (ALL
texts reside in database!). With ot_init.sql three initial users will be
created:
- anonym@yourdomain.dom: for anonymous comments, no login
- listmaster@yourdomain.dom: for listsender user, no login
- webmaster@yourdomain.dom: for webmaster user, login with 'password'

Before applying ot_init.sql, you may replace "yourdomain.dom" with your
domain in the script.

Please do these jobs on console, because web-based tools like phpMyAdmin
cause errors during import due to HTML-character conversions. Let's go:

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

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

$langs = array(				# valid languages
	'de' => 'deutsch',		# first = default
	'en' => 'english'		# last /wo colon!
#	'fr' => 'fran&ccedil;ais',	# example
#	'es' => 'espag&ntilde;ol',	# example
#	'pt' => 'portugu&ecirc;s'	# example
);
$sql = array(
	'host'	=> 'localhost',		# hostname
	'user'	=> 'otuser',		# mysql username
	'pw'	=> 'password',		# mysql user password
	'db'	=> 'otdb'		# mysql database name
);

Change 'password' with your password chosen during creation of the user
'otdb' (see above). You can change the order of the given languages, the
first is used as default language. To add a new language, please refer to
file TRANSLATE.


4. The "P": PHP
---------------

I recommend to use mod_php version 3.x, but not version 4.x due to license
incompatibilities with GPL. However, ot-server works also fine with PHP4.

Search for the php3.ini or php.ini respectively, generally found in
/etc/httpd or /etc and configure it in a way like that:

	short_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 for admin access

All perl scripts reside in /anypath/otperl/. Generally the directory of the
scripts is determined by FindBin. However, in some contexts a very weird
error occurs during compilation:

	Cannot find current script '/dev/null' at /usr/lib/perl5/5.6.1/FindBin

If you have any idea: please give me a hint, thanks. You'll find my workaround
inside the scripts:

	use FindBin;			# if it works: use FinBin
	use lib $FindBin::Bin;		# instead of static path
	#use lib '/anypath/otperl';	# or: adjust path

If FindBin does not work in your environment, than comment out the two
FindBin-Lines and use the (adjusted) static path below.

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

You have two sections for these vars, one for the test mode, and the other
for production. Toggeling between these modes is done by

	$testmode = 1;				# switch between test and production

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
domains 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. Cron job
-----------

You have to setup a cron job, at least to send all piped mails every day. I
recommend to use this job to make a database backup too. My example (call
crontab -e):

SHELL=/bin/sh
MAILTO=you

0 5 * * *	/anypath/otbackup/otsave.sh
0 6 * * *	/anypath/otperl/ot_sender.pl

Every 5 o'clock in the morning make a backup (delete yesterday backup,
leave one backup at end of every month), and every 6 o'clock send all mail
piped in table par_mail of the database. You'll find the shell script
otsave.sh inside ot-package - adjust it to your needs (paths!).

ATTENTION: This simple daily database snapshot is only a kind of a "logical
backup" if you want to recover faults made in the last hours. This does not
compensate a careful and reliable backup of the whole opentheory
installation (the server).


8. 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 http://www.opentheory.org/dev by subscribing via
http://www.opentheory.org/member.phtml

Keep on theorizing!
