#!/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 1.3.x, and if desired, mod_perl 1.2x

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 XML2Hash         (Not on CPAN yet, can be found at openthought.net)

 tar zxvf OpenThought-XML2Hash-x.xx.tar.gz
 cd OpenThought-XML2Hash-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.

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.


4. Install OpenPlugin       (Not on CPAN yet, can be found at openthought.net)

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

The installer will ask which drivers you want, check pre-requisite modules,
and then automatically install the proper versions of everything before
continuing.  It will also prompt you for where to install the config files.

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.


5. 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.  It will also prompt you for
where to install some data files.

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.


6. Edit the OpenPlugin/OpenThought Config files and tell them your correct paths

 vi /usr/local/etc/OpenPlugin.conf
 vi /usr/local/etc/OpenThought.conf


Choose your own adventure!

For a MOD_PERL INSTALLATION, goto to section IIa
For a STANDARD CGI INSTALLATION, goto to section IIb


Section IIa (mod_perl users)
----------------------------

7. Edit your OpenThoughtRoot and Prefix settings

 vi /usr/local/etc/OpenThought-httpd.conf

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


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

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


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/demo.pl        (if on your local machine)

      -- or --

 http://www.mydomain.com/OpenThought/demo_app/demo.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 (CGI users)
-----------------------

7. 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'

8. Uncomment the CGI section of the demo

 The demo contains two sections, one for mod_perl users, and one for CGI users.
 Using mod_perl is the default.

 Edit the demo.pl file you installed into the OpenThoughtRoot directory, and
 uncomment the lines in the section "CGI INSTALL".  Then, just comment out the
 lines in "MOD_PERL INSTALL".


9. Try the OpenThought demo app.  Browse to:

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

      -- or --

 http://www.mydomain.com/cgi-bin/demo_app/demo.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.



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

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 / non-CGI 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 two lines
exist, and are uncommented:

  LoadModule proxy_module       modules/libproxy.so

  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
