INSTALL

-----------------------
mod_pubsub Installation
-----------------------

In this distribution there are two separate PubSub Servers:
cgi-bin/PubSub/ModPubSub.pm (which requires Apache 1.3 or 2.0 and
mod_perl) and python_pubsub/pubsub.py (which runs standalone on a
command line).

So far, we have run cgi-bin/PubSub/ModPubSub.pm with Apache and
mod_perl on Windows 2000/XP, Linux, Mac OS X, and Solaris 2.8.
Instructions for configuring it to run with Apache 1.3 or 2.0 and
mod_perl, assuming you have root on the web server, are in the
"Installation of ModPubSub.pm" section below.  Other web servers may
work but have not been tested so far.

Also, we have run python_pubsub/pubsub.py in standalone from the
command line on Windows 2000/XP, Linux, Mac OS X, and Solaris 2.8.
For those who don't want to struggle with Apache and mod_perl,
we recommend you use this standalone PubSub Server instead.
Please refer to the "pubsub.py: An Alternative, Standalone Server"
section below.

For questions and comments, please refer to the mailing list.

   http://mod-pubsub.sf.net/
   mod-pubsub-developer@lists.sourceforge.net

$Id: INSTALL,v 1.19 2003/05/17 08:09:23 ifindkarma Exp $



----------------------------
Installation of ModPubSub.pm
----------------------------


0.  You need Perl 5 or higher to be able to use this distribution;
we've run it recently with 5.6.1, but it should probably still work
with 5.005.  You will also need a C compiler.


1.  You need to install the libwww-perl collection for Perl 5.  This 
is a set of Perl modules that provide a nice API for HTTP functions.
If your system doesn't have a package management system like rpm, dpkg,
or ppm, we strongly recommend that you use CPAN.pm, which will fetch and
install all dependencies for you.  CPAN.pm may already be installed on
your system; or learn more and get it at http://www.cpan.org/ .

   cpan install Bundle::LWP


2.  Now, if you don't already have Apache installed, install it.  We
recommend that you enable dynamic shared object support during
configuration (see the ./configure line below).  This will make it
easier to also use other Apache modules and is no more difficult to
build and use.


Option A: Apache 1.3 installation:

NOTE: tested with Apache/1.3.23

If your system doesn't have a package management system, you can
compile and install Apache 1.3 as follows: (refer to the Apache
INSTALL document for details)

   tar -zxvf apache_1.3.x.tar.gz
   cd apache_1.3.x
   ./configure --enable-module=so
   make
   make install


Option B: Apache 2.0 installation:

NOTE: tested with Apache/2.0.45

If your system doesn't have a package management system, you can
compile and install Apache 2.0 as follows: (refer to the Apache
INSTALL document for details)

   tar -zxvf apache_2.0.x.tar.gz
   cd apache_2.0.x
   ./configure --prefix=/usr/local/apache2
   make
   make install


3.  Now, you need to install the Apache Perl module, mod_perl
( http://perl.apache.org/ ).  We recommend that you do so as a dynamic
shared object.


Option A: Apache 1.3 mod_perl 1.x installation:

NOTE: tested with mod_perl/1.26

If your system doesn't have a package management system, you can
compile and install mod_perl as follows: (refer to the mod_perl
INSTALL document for details)

   tar -zxvf mod_perl-1.xx.tar.gz
   cd mod_perl-1.xx
   perl Makefile.PL USE_APXS=1 WITH_APXS=/path/to/apache/bin/apxs EVERYTHING=1
   make
   make test
   make install

Install the module, and make sure there's a line in apache/conf/httpd.conf
giving the correct path to where you've installed it.  On my Debian system,
that line looks like this:

   LoadModule perl_module /usr/lib/apache/1.3/mod_perl.so

You also may need to add (or un-comment) a line like this:

   AddModule mod_perl.c

On other systems, the module may be in somewhere like
/usr/lib/apache/1.3/libexec/libperl.so .


Option B: Apache 2.0 mod_perl 2.x installation

NOTE: tested with mod_perl/1.99_08

If your system doesn't have a package management system, you can compile
and install mod_perl as follows.

   tar -zxvf mod_perl-2.xx.tar.gz
   cd mod_perl-2.xx
   perl Makefile.PL MP_AP_PREFIX=/usr/local/apache2 MP_INST_APACHE2=1
   make
   make test
   make install

Install the module, and make sure there's a line in apache2/conf/httpd.conf
giving the correct path to where you've installed it:

   LoadModule perl_module modules/mod_perl.so

Tell Apache to use the modules we just installed:

   PerlModule Apache2


4.  Extract the mod_pubsub tar file under your Apache document root.
It will create a directory named mod_pubsub/ with lots of goodies in it.


5.  Configure your Apache server to run the mod_pubsub Perl module.
You can do this by adding lines like the following to httpd.conf.
You may need to adjust the filenames for your Apache document root
(default mod_pubsub directory: "/var/www/mod_pubsub"; default
mod_pubsub directory URL: "/mod_pubsub").

NOTE: In Apache 2.0 (at least as of 2.0.45,) you'll have to replace
      the "<Perl>" section start tag with "<Perl >" in the example
      below; hopefully this extra space will not be required in future
      versions.

   <Perl>
      use lib "/var/www/mod_pubsub/cgi-bin";
      use PubSub::ModPubSub 'mod_pubsub';
      mod_pubsub("/var/www/mod_pubsub", "/mod_pubsub", "/kn",
                 \%Location, \%Directory);
   </Perl>

If you are using Apache's virtual hosting feature, you should embed a
copy of the mod_pubsub configuration section inside each
"<VirtualHost>" section where you would like to use mod_pubsub.


6. At this point, your Apache and mod_perl should be working correctly.
To check, view the following page:

   http://localhost/mod_pubsub/cgi-bin/testperl.cgi

You should see about a page of information about your Apache server.
If you see a few lines of Perl instead, mod_perl is not enabled correctly.


7.  Run the Makefile in this directory, for example

   make HTTPD_USER=www-data

This does two things:


7A. Compresses the JavaScript PubSub library, creating pubsub.js :

   bash kn_tools/js_compress.sh < kn_apps/kn_lib/pubsub_raw.js > kn_apps/kn_lib/pubsub.js

NOTE: js_compress.sh depends on the "nl" tool from GNU textutils.
Since not everyone has this tool, we ship the mod_pubsub package
with pubsub.js already generated.


7B. Creates a subdirectory called mod_pubsub/kn_events/ and make it
writable by the user that will be running the event router code,
typically "nobody", "httpd", or "www-data".  We recommend that you do
this by changing the ownership of this directory to that user; as root:

   cd mod_pubsub
   mkdir kn_events
   chown httpd kn_events

If you don't create a kn_events directory with the proper permissions,
none of the apps will work, the test suite will fail, your server
error log will rapidly fill with "Uncaught exception" messages, and
apps run with debugging turned on will display "500 Internal Server
Error" messages.


8. Now try testing your mod_pubsub server:

   http://localhost/mod_pubsub/cgi-bin/pubsub_test.cgi

You should see a list of tests.  All 56 tests should say "OK", with
the possible exception of the "replay" tests, which are flaky due
to timing dependencies.

NOTE: This will fail if you have required HTTP authentication (as
described below.) To make it work, you should append a valid HTTP
username and password to the URL in index.html:

   http://localhost/mod_pubsub/cgi-bin/pubsub_test.cgi?user=knguest&password=knguest

Be aware that this test uses up about 10MB of disk space every time
you run it.


9.  Try viewing a test app in kn_apps:

   http://localhost/mod_pubsub/kn_apps/chat2/index.html?kn_debug

You should see 4 frame windows.  The small one at lower-left should be
red and say "200 Watching topic".  The small one at lower-right should be
yellow.  The top frame window should be blank and beige.  You should be
able to type messages in the form and see them in the top frame.

If you are not seeing what you expected at this point, see the
"Troubleshooting" section below.


10.  At this point, all the Dynamic HTML apps listed in the kn_apps
index should work.  However, several of these applications require
authentication.  We offer a (not secure) cookie_auth.js helper library
to give you a feel for how authentication should work with these apps;
however, if you want real security you'll need to determine usernames
from actual HTTP authentication; to take advantage of this requires
configuring Apache to require password authentication for access to
the mod_pubsub instance.  You can do this by adding something like the
following to your Apache httpd.conf -- and then create a users.passwd
file with the appropriate usernames and passwords.

    <Directory /var/www/mod_pubsub>
        AuthType Basic
        AuthName "pubsub-auth"
        AuthUserFile /var/www/mod_pubsub/users.passwd
        Require valid-user
    </Directory>

As before, you may need to adjust paths for your system.



---------------
Troubleshooting
---------------

Not Found error (The requested URL /kn was not found on this server)

  Perhaps the Alias directive contains an error, or you unpacked the
distribution somewhere other than your document root, or you typoed
the URL.


500 Internal Server Error

  Look at the end of Apache's error_log (by default, usually
/var/log/httpd/error_log, but web server setups vary a lot) for an
error message.  If mod_pubsub complains that files or directories in
kn_events don't exist, maybe it doesn't have permission to create them;
try changing the ownership of the kn_events directory:

  cd /var/www/mod_pubsub
  chown -R httpd kn_events  (your web server may run as a different user,
                             e.g., nobody or www-data instead of httpd)


You can see Perl source when you view test apps

Apache should be running these with mod_perl.  Perhaps Apache hasn't
loaded mod_perl (the PerlHandler directive above should give you an
error message in error_log, and keep Apache from starting, if that's
the case) or mod_perl doesn't handle the cgi-bin directory in which
mod_pubsub has been installed.  Perhaps the <Perl> or <Directory>
directive above has the wrong path?

We have also found embedding the following within a <VirtualHost>
section has helped as a work-around in at least one configuration.

    # Ghosts in the machine might make this necessary:
    <Directory /var/www/mod_pubsub/cgi-bin>
        <Files pubsub.cgi>
            SetHandler perl-script
            PerlHandler PubSub::ModPubSub
            Options ExecCGI
            PerlSendHeader On
        </Files>
        <Files *.cgi>
            SetHandler perl-script
            PerlHandler Apache::Registry
            Options +ExecCGI
            PerlSendHeader On
        </Files>
    </Directory>




--------------------------------------------
pubsub.py: An Alternative, Standalone Server
--------------------------------------------

This release also ships with a standalone Python server that is
feature-compatible with Apache-running-with-the-mod_pubsub scripts.
It's a single file that runs standalone without Apache.

With a Python installation on your machine, it should be runnable
as-is from a command line.

To get Python running on Windows, for example, use

  http://www.python.org/windows/

or

  http://www.activestate.com/Products/ActivePython/

You can run the Python PubSub Server as follows:

   cd mod_pubsub/python_pubsub
   ./pubsub.py 80 ..

This creates a server running on localhost port 80, using
mod_pubsub/ as its document root.  In a browser, you can go to

   http://localhost/kn_apps/

and run some of the sample PubSub-enabled browser applications.

So far, we have tested and run pubsub.py on Linux, Mac OS X, Solaris,
and Windows 2000/XP.



------------------
Cross-Domain Setup
------------------

To use cross-domain, copy mod_pubsub/kn_apps/kn_lib/sample_prologue.js
to mod_pubsub/kn_apps/kn_lib/prologue.js and modify it accordingly.

For example, if you wanted to use the Perl Apache module as the front
door, and get the performance of the Python Server, set the 'kn_server'
property in prologue.js to point to the Python server, and then from
the web browser you connect to the appropriate Perl server URL for your
app, and it forwards appropriately.



--------------------
Setting Up Newsfeeds
--------------------

The newsticker app works fine when set up as above, but there's no news
for it to display; you'll need to run a newsfeed script.  There's a
simple one provided in mod_pubsub/kn_sense/rss/rss.plx; you can run
it as follows:

   cd mod_pubsub/kn_sense/rss
   ./rss.plx -url http://localhost/mod_pubsub/cgi-bin/pubsub.cgi

This fetches a large number of RSS files and posts their contents as
stories to the server; when you do this, you should start seeing
headlines show up in NewsTicker almost immediately.

It will eventually finish; if you want a continuous newsfeed, you
should run rss.plx periodically.

Alternatively, note that we also have an RSS Feed program provided
as a sample in the mod_pubsub/cxx_pubsub/LibKN/Apps/ directory that
runs on Windows after being compiled using VC++ or VC.NET.



--------------------
For More Information
--------------------

Read index.html for an index of goodies provided in this distribution.
Read TODO to see all the things we want to add and improve.  And,
read README for a list of credits.

And: Join the mailing lists to work with the community on making this
project much better.

  http://mod-pubsub.sf.net/
  mod-pubsub-developer@lists.sourceforge.net