#!/usr/bin/head
OpenThought Installation                                http://openthought.net
                                                        eric at openthought.net

This file will give you instructions on how to install the OpenThought engine
and it's demo application.


Section I
---------

1. Install Perl.  Versions 5.005_03 and greater are known to work.


2. Install Apache, and if desired, mod_perl (mod_perl is recommended)

Both of these come with many distributions these days.  However, if you have
any trouble at all with your Apache / mod_perl installation, including
segfaults, please read Appendix A, which describes a known good method of
installing them.


3. Install OpenThought

 tar zxvf OpenThought-x.xx.tar.gz
 cd OpenThought-x.xx
 su
 perl Makefile.pl
 make
 make test
 make install

The installer will check pre-requisite modules and automatically install the
proper versions of anything before continuing.  When it begins the installation
of OpenPlugin, you will be prompted to choose which drivers you wish to
install.  You will also be prompted to install some data files.

NOTE: The system will backup your config files, but only once.  That is, it
will rename them to something like OpenThought.conf.backup.  So, if you already
have a OpenThought.conf.backup file, it will be overwritten.

If you don't have permissions to install modules on the system, see Appendix B
below for simple instructions on installing modules locally, such as in your
home directory.


Choose your own adventure!

For a MOD_PERL 1.2x INSTALLATION, goto to section IIa
For a MOD_PERL 1.99/2.x INSTALLATION, goto to section IIb
For a STANDARD CGI INSTALLATION, goto to section IIc


Section IIa (mod_perl 1.2x users)
--------------------------------

4. Add the following line to the end of your httpd.conf:

 Include /usr/local/etc/OpenThought-httpd-mod_perl1.conf

Substitute "/usr/local/" with the directory you specified as the
Prefix directory during installation.


5. Restart Apache

 /etc/rc.d/init.d/httpd restart


6. Try the OpenThought demo app.  Browse to:

 http://127.0.0.1/OpenThought/demo_app/index.pl       (if on your local machine)

      -- or --

 http://www.mydomain.com/OpenThought/demo_app/index.pl  (if on a remote machine)


Under mod_perl, the url path of /OpenThought/ is automatically aliased for you
to point to your OpenThoughtRoot.  So even if your OpenThoughtRoot is not
physically in the dir /OpenThought, the above url will still take you there.

You may wish to consider running two versions of Apache, one with mod_perl
support, the other without.  See Appendix C below for instructions on using
that setup.

(continue to Section III)


Section IIb (mod_perl 1.99/2.x users)
-------------------------------------

5. Change your OpenPlugin drivers

 vi /usr/local/etc/OpenPlugin.conf

 Locate the sections for the following plugins:
   request, param, httpheader, upload, and cookie

 For each plugin, change the driver from 'Apache' to 'Apache2'


6. Add the following line to the end of your httpd.conf:

 Include /usr/local/etc/OpenThought-httpd-mod_perl2.conf

Substitute "/usr/local/" with the directory you specified as the
Prefix directory during installation.


8. Uncomment the MOD_PERL 1.99/2.x section of the demo

 The demo contains three sections, one for mod_perl 1.x users, one for mod_perl
 1.99/2.x users, and one for CGI users.  Using mod_perl 1.x is the default.

 Edit the index.pl file you installed into the OpenThoughtRoot directory
 (/var/www/OpenThought/demo by default), and uncomment the lines in the section
 "MOD_PERL 1.99/2.x INSTALL".  Then, just comment out the lines in the section
 labeled "MOD_PERL INSTALL".


9. Restart Apache

 /etc/rc.d/init.d/httpd restart


10. Try the OpenThought demo app.  Browse to:

 http://127.0.0.1/OpenThought/demo_app/index.pl       (if on your local machine)

      -- or --

 http://www.mydomain.com/OpenThought/demo_app/index.pl  (if on a remote machine)


Under mod_perl, the url path of /OpenThought/ is automatically aliased for you
to point to your OpenThoughtRoot.  So even if your OpenThoughtRoot is not
physically in the dir /OpenThought, the above url will still take you there.

You may wish to consider running two versions of Apache, one with mod_perl
support, the other without.  See Appendix C below for instructions on using
that setup.

(continue to Section III)


Section IIc (CGI users)
-----------------------

5. Change your OpenPlugin drivers

 vi /usr/local/etc/OpenPlugin.conf

 Locate the sections for the following plugins:
   request, param, httpheader, upload, and cookie

 For each plugin, change the driver from 'Apache' to 'CGI'

6. Uncomment the CGI section of the demo

 The demo contains three sections, one for mod_perl 1.x users, one for mod_perl
 1.99/2.x users, and one for CGI users.  Using mod_perl 1.x is the default.

 Edit the index.pl file you installed into the OpenThoughtRoot directory
 (/var/www/OpenThought/demo by default), and uncomment the lines in the section
 "CGI INSTALL".  Then, just comment out the lines in the section
 "MOD_PERL 1.x INSTALL".


7. Try the OpenThought demo app.  Browse to:

 http://127.0.0.1/cgi-bin/demo_app/index.pl        (if on your local machine)

      -- or --

 http://www.mydomain.com/cgi-bin/demo_app/index.pl   (if on a remote machine)

 Substitute "cgi-bin" for whatever path you installed the demo into.


Section III (All users)
-----------------------

You're Done!

You can use 'perldoc OpenThought' and 'perldoc OpenPlugin' for instructions on
creating applications.

Also be sure to check out the demo application to see an example of how things
work.

Have fun :-)


Appendix A. -- Installing Apache and Mod_Perl 1.x
-------------------------------------------------

Apendix A will describe how to install both Apache and mod_perl from source.

(This section borrowed nearly word for word from AxKit.. thanks Matt!)

 Download mod_perl from http://perl.apache.org/
 Download Apache from http://www.apache.org/httpd.html

 Extract both archives in a suitable location (I use /usr/local/src)
 Do not extract one archive in the other's directory - this
 will cause you problems.

 Now cd to the mod_perl directory, and enter the following:

 perl Makefile.PL \
  EVERYTHING=1 \
  USE_APACI=1 \
  DYNAMIC=1 \
  APACHE_PREFIX=/usr/local/apache.mod_perl \
  APACHE_SRC=../apache_1.3.26/src \
  DO_HTTPD=1 \
  APACI_ARGS="--enable-module=so --enable-shared=info \
  --enable-shared=proxy --enable-shared=rewrite \
  --enable-shared=log_agent"
 make
 su
 make install

Also note that the paths for the APACHE_SRC and APACHE_PREFIX should
be fixed to the version of Apache you downloaded, and the location
you wish to install Apache into, respectively.


Appendix B. -- Installing Modules Locally
-----------------------------------------

In some cases, we don't always have permissions to install modules system wide.
In cases like this, it's simple to install modules in your home directory.

First, create a directory in your home directory called "lib" by doing the
following:

  mkdir ~/lib

Secondly, whenever you go to install a module, instead of following the step
that reads "perl Makefile.PL", use the following step instead:

  perl Makefile.PL LIB=~/lib

If you have more questions on this topic, there is an excellent tutorial at:

  http://www.perlmonks.org/index.pl?node_id=128077


Appendix C. -- Running OpenThought With Apache on a Non-Standard Port
---------------------------------------------------------------------

For administrators of mod_perl, there are excellent reasons for wanting to run
your mod_perl enabled Apache server on a non-standard port.  Perhaps on port 80
you'll have a version of Apache to handle non-Perl requests, and then on port
81 you'd have a version of Apache set to handle all mod_perl requests.

That is an excellent way to setup your webserver, but one thing you don't want
to do is start telling users to go to url's like:

  http://www.someserver.com:81/OpenThought/myperlscript.pl

Note the port 81.  It makes the url longer, it confuses the user, it's not very
flexible, and it's a good way to find several bugs in a few browsers (notably
IE 4.0), which will end up breaking your application.  Also, publishing that
port may even be a security risk.

Instead, we can tell Apache (the one on port 80) that anytime somebody requests
a document under a particular directory, that it needs to hand off that request
to the Apache running on port 81.  You can do that easily, by editing the
httpd.conf associated with the Apache running on port 80.

In your httpd.conf for your port 80 Apache, make sure the following four lines
exist, and are uncommented:

  LoadModule rewrite_module     modules/mod_rewrite.so
  LoadModule proxy_module       modules/libproxy.so

  AddModule mod_rewrite.c
  AddModule mod_proxy.c

Then, perhaps at the end of the config file, add these lines:

  RewriteEngine On
  RewriteRule ^/OpenThought/(.*) http://127.0.0.1:81/OpenThought/$1 [P]
  ProxyPassReverse / http://127.0.0.1/
  RewriteRule ^proxy:.* - [F]

The above code says that whenever we receive a request destined for a location
under the directory "OpenThought", forward it to the server running on port 81.
Note that with the above, you only need to have the port 81 Apache listening on
127.0.0.1, it doesn't need to be listening on an external interface.

For further information on the above, check out the following urls:

  http://httpd.apache.org/docs/mod/mod_rewrite.html
  http://httpd.apache.org/docs/mod/mod_proxy.html