INSTALL 0100644 0000764 0000144 00000021362 07317376546 011367 0 ustar meretz users Installing an open theory Server (abbr: ot-server)
==================================================
Date of INSTALL: 30.06.2001
The server software ot, version 0.7, 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
AuthName opentheory
AuthType Basic
require valid-user
PerlAuthenHandler ot_aut
'deutsch', # first = default
'en' => 'english' # last /wo colon!
# 'fr' => 'français', # example
# 'es' => 'espagñol', # example
# 'pt' => 'português' # example
);
$sql = array(
'host' => 'localhost', # hostname
'user' => 'otdb', # mysql username
'pw' => 'password', # mysql user password
'db' => 'otdb' # mysql database name
);
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 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!
README 0100644 0000764 0000144 00000002324 07317376546 011213 0 ustar meretz users The open theory server software (abbr: ot-server)
==================================================
Date of the README: 30.06.2001
The ot server software, version 0.7, 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.
The INSTALL document describes how to install a open theory system.
The SETUP document describes the setup procedure, e.g. how to fit the system
to your needs. Admins should read this.
If you want to support the development process by translating ot-outputs,
please refer to TRANSLATE document.
The SNAPSHOT document gives hints on how to make a "copy" of a running open
theory system, e.g. for testing purposes.
If you followed INSTALL and SETUP properly, you also have access to some
manual pages documenting all perl functions (see SETUP).
On http://www.opentheory.org/ot_per_mail you'll find additional descriptions
about the mail interface (unfortunately in german only).
Any hints are welcome!
mailto:stefan@meretz.de
Keep on theorizing!
SETUP 0100644 0000764 0000144 00000020701 07310641146 011135 0 ustar meretz users Setup of an installed open theory server
========================================
Date of the SETUP file: 07.06.2001
If you don't have installed the ot-server yet, please refer to README. This
document describes the setup of an installed ot-server by the adminstrator.
Background
----------
All pages of the website driven by the ot-server are generated dynamically
in a comprehensive sense. This means, that data and functions are completely
separated. Data are static and dynamic texts. Static texts are all
descriptions of the website, of their funtions etc. Dynamic texts are all
text projects which can be done using the ot-server functions - at least,
this is the sense of open theory;-)
The separation of static texts from website functions make it relatively
easy to translate the ot-server. If want to do that - you're welcome! - then
refer to document TRANSLATE.
The ot-server comes with no project, although some descriptions of the ot
funtionality is done using ot-projects. So, you are highly recommended to
include some of them by founding them (see below). These basic projects are
initially linked inside the website you installed up to now. These links
and their texts reside in database, too. If you want to renounce of some
projects you have to adjust these links.
In the following it is assumed that you take over all basic projects coming
with this server. Hints will be given what has to be done if you don't want
to take all basic projects.
1st step: become a member
------------------------
Introduce yourself as an ot member using normal member functions on page
http://yourdomain/member.phtml. Type first name, last name, e-mail address,
and a password an click the button. You will be automatically logged on.
2nd step: create projects
------------------------
Click on link "Founding projects" (in given language) which is
http://yourdomain/setupform.phtml - including your session id, which is
appended to this link. Fill in the form with
- project title
- short title
- keywords
- short description
Take those projects from the following list basic projects you want. Titles
and descriptions are only proposals. You will find all basic texts under its
short title names followed by '.txt' in directory /anypath/ottxt.
1. What is ot?
- project title: Das Projekt: open theory (german only)
- short title: open_theory
- description: Die Anwendung von ot auf ot! In
diesem Hauptprojekt wird die Grundidee des gesamten open theory Projektes
beschrieben. Die untergeordneten Texte enthalten weitergehende Details
zum Hintergrund und zur Funktionsweise von ot-Projekten.
2. Rules
- project title: Wie ein Projekt funktioniert (german only)
- short title: regeln
- description: Hier werden die Regeln beschrieben - für Projektmitglieder
und für Maintainer.
3. Links
- project title: Links auf verwandte Projekte (german only)
- short title: links
- description: Diese Seite kommentiert Links auf verwandte, mehr oder
weniger offene Theorieprojekte.
4. FAQ
- project title: Frequently Asked Questions (german only)
- short title: faq
- description: Frequently Asked Questions versammelt die häufig gestellten
Fragen zu ot-Projekten und der ot-Website -
und die entsprechenden Antworten.
5. What's new?
- project title: Was hat sich bei open theory geaendert (german only)
- short title: change_history
- description: In diesem Text werden die letzten Änderungen der
ot-Software beschrieben.
6. Sketch of idea's
- project title: Ideenskizze des open-theory-Projekts (german only)
- short title: initial
- description: Das Initial-Projekt beschreibt die ursprünglichen Ideen vor
der Entwicklung von open theory. Ein historisches Dokument!
7. To-do list
- project title: Wunsch- und Fehlerliste (german only)
- short title: todo_and_bugs
- description: In diesem Text werden die Wünsche der Nutzer/innen über
erweiterte ot-Funktionen sowie die bekannten Fehler in der
aktuellen Version dokumentiert.
8. Development
- project title: Hacker-Seiten von open theory (german)
- short title: dev_de
- description: Das ist die deutsche Version der Entwicklungs-Seite von open
theory.
or
- project title: Hacker's page of open theory (english)
- short title: dev
- description: This is the english version of the development page of open
theory.
The first four projects are used in the menu bar, so I recommend to use
them, maybe in a modified form. Projects 5 to 8 give a little bit more
insight in sense and development of open theory project. They appear in
default configuration in the right menu bar on home page. Change them if you
want.
Instead of using the above project as parts of your ot-server system, you
also can use simple links to the _original_ open theory projects at
http://www.opentheory.org. How to do this is described in the next chapter.
3rd step: adjust parameters
--------------------------
All static texts stored in the database can be modified using web front end
at http://yourdomain/otauth/param.phtml. This page is secured by http-auth
mechanism. Enter your e-mail address (as "name") and your password.
Initially the first user in system (with memb_id=1) is administrator. This
can be changed later.
From the drop down list you can choose all text list for the web site. Some
of them include special parameters influencing behavior and outfit of the
side.
- general parameters [en]
Here you find parameters for fonts, colors etc. used for ot website.
The most important field here is the first one (with number zero), which
contains the memb_id(s) of the adminstrator(s). More then one memb_ids are
separated through hashmarks ('#'). Check the database memb_id carefully
before you replace old values. A good idea might be to add the new memb_id
using the hashmark first, and then, in a second step after testing that
the new memb_id works, to remove the old id.
Row 10 contain 5 colors for body tag (page, text, link, vlink, alink).
Row 11 contains 5 background colors and row 12 contains 5 foreground
colors. Rows 15 to 19 describe fonts.
From row 20 to 39 you can adjust links for the horizontal menu bar. The
menu bar is devided in three parts - two variable parts left and right an a
fixed part in the middle (links for member and maintainer). Left and right
variable parts can own up to 7 links each.
Row 20 contains the number of links of the left variable menu part. This row
must be followed by that number of rows describing links. Default is 'Home',
'What is ot?', and 'Rules'.
Row 30 contains the number of links of the right variable menu part. This row
must be followed by that number of rows describing links. Default is 'Links'
and 'FAQ'.
For both you can use external link, e.g. to the corresponding pages of the
original open theory server. Note: Using external links means, that a user
leaves your site clicking such link. On the external site he/she might not
be a member of that site - which might confuse the user. For this special
case it makes sense to use a diffrent outfit for your site to give some
distinctions between your and the external site.
Rows 40 to 46 contains informations about your site, which should fit to
your parameter (e.g. appearing in the footer).
All other values should only be changed with a parallel testing of the
corresponding web pages. See document TRANSLATE.
4th step: adjust path to man pages of open theory
-------------------------------------------------
Finally, if you want to use man pages of open theory, append the path
/anypath/otman to variable $MANPATH in your .profile or .bashrc file:
export MANPATH=$MANPATH:/anypath/otman
Then change to /anypath/otman and call the manual build script:
cd /anypath/otman
./build.sh,
This automatically generates all open theory man pages. These man pages are
the systems documentation and apply only to the admin and hackers level.
Users find all informations on web pages.
Now, you can use following manual pages by calling "man ":
- ot_tabs: all tables of database (MySQL)
- ot_aut: authentication of admin access
- ot_sender: sends waiting comments from table par_mail (usually cronjob)
- ot_mail: general mail interface
- ot_const: constants
- ot_dblib: database access library
- ot_maillib: mail library
- ot_receive: mail receive module
- ot_parse_a: mail parser, address based mode
- ot_parse_b: mail parser, body based mode
- ot_validate: mail command validator
- ot_execute: mail command executor
The funtionality of these modules is described in a more detail at
http://www.opentheory.org/ot_per_mail.
SNAPSHOT 0100644 0000764 0000144 00000004073 07310640011 011466 0 ustar meretz users Making a snapshot of a running ot-system
========================================
Date of the SNAPSHOT file: 07.06.2001
This document describes how to make "copy" of a running open theory web
server e.g. for testing purposes.
You can create a test system by making a snapshot of the productive system
on the same server. The risk to crash the server by translating texts is
negligible. This is done like a fresh installation (except installing
LAMP-system, you already have it). Refer to INSTALL document and do the
following steps (or the admin for you):
- make an archive of the tree part beginning at /anypath/htdocs:
cd /anypath/htdocs
tar cvzf ottest.tgz ./*
- make an archive of the entire database, say from /var/mysql/otdb
(it is a clever idea to do this daily e.g. driven by a cron job)
cd /var/mysql/otdb
tar cvfz otdb.tgz ./*
- create a new base directory for ottest, say /anypath/ottest, an extract
the tree-archive:
mkdir /anypath/ottest
cd /anypath/ottest
tar xzf ottest.tgz
- create a new mysql database as described in mysql documentations, say
ottest. You will find a new directory /var/mysql/ottest. Then extract the
db-archive:
cd /var/mysql/ottest
tar xzf otdb.tgz
- reload the database daemon:
mysqladmin reload
- open http.conf file from apache and include a new directory definition for
the authentication like that:
PerlSetEnv PERL5LIB /anypath/ottest/otperl
AuthName opentheory
AuthType Basic
require valid-user
PerlAuthenHandler ot_aut