Dogcows Code - chaz/chatty/blob - doc/README.pod

   1
   2 =head1 NAME
   3
   4 Chatty -- Real-time (comet) chat application written with Perl/Catalyst
   5
   6 =head1 SYNOPSIS
   7
   8     cpan Catalyst::Devel                    # install Catalyst
   9
  10     perl Makefile.PL
  11     make installdeps                        # install other dependencies
  12
  13     cp extra/nginx.conf /etc/nginx/nginx.conf
  14     /etc/rc.d/nginx start                   # run nginx http server
  15
  16     cp extra/cometd/meteord.conf.dist /etc/meteord.conf
  17     # also add the 'SubscriberDocumentRoot' option to meteord.conf;
  18     # it should be set to $REPOSITORY_ROOT/extra/cometd/public_html
  19
  20     cd extra/cometd; ./meteord -d           # run meteord in a new shell
  21
  22     cat extra/hosts >>/etc/hosts            # configure hostnames
  23     sqlite3 db/info.db <db/schema.sql       # create the user database
  24
  25     ./script/chatty_server.pl -f            # run the app
  26     firefox http://chatty.com/              # finally, see if it works
  27
  28 =head1 DESCRIPTION
  29
  30 This is a toy web application implementing real-time (comet) chat.  I wrote
  31 this as an exercise to see how easy it would be to write such an
  32 application using Perl/Catalyst.  It was fairly easy.
  33
  34 Catalyst itself provides no streaming support or message bus, so I am using
  35 a dedicated comet server to handle all of that, meteord.  However, in order
  36 to get meteord to work, it needs to be serving on the same port as the
  37 Catalyst app.  I accomplished this by using nginx as a reverse proxy.
  38 However, you can't just use localhost because meteord does some checks on
  39 the hostname to make sure it will not run into any cross-domain
  40 restrictions, and those checks barf if the hostname doesn't have a TLD.
  41 The fix for this is to just assign some fake hostnames to localhost; the
  42 provided nginx configuration uses chatty.com for the Catalyst app and
  43 data.chatty.com for the comet server, both on port number 80.  The actual
  44 Catalyst app runs on port 3000 and meteord runs on port 4670.  That's the
  45 reason for the complicated setup.
  46
  47 The perl dependencies can all be installed locally in a subdirectory of the
  48 user's home directory using local::lib, like this:
  49
  50     # install local::lib (see L<http://search.cpan.org/dist/local-lib/>)
  51     # then,
  52     eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)
  53
  54 It is also usually much nicer to work with cpanminus rather than plain old
  55 cpan:
  56
  57     # install cpanminus
  58     curl -L http://cpanmin.us | perl - --self-upgrade
  59
  60 =head1 BUGS
  61
  62 Tests are sadly nonexistent. :-(
  63
  64 =head1 AUTHOR
  65
  66 Charles McGarvey E<lt>chazmcgarvey at brokenzipper.comE<gt>
  67
  68 =head1 LICENSE
  69
  70 This library is free software. You can redistribute it and/or modify
  71 it under the same terms as Perl itself.
  72
  73 =cut
  74