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

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