From c89636c5063ea0bac876bf56248c97ade994cf8c Mon Sep 17 00:00:00 2001
From: Charles McGarvey <chazmcgarvey@brokenzipper.com>
Date: Tue, 3 Jan 2012 19:39:54 -0700
Subject: [PATCH] add supporting documents and help files

---
 README           | 73 ++++++++++++++++++++++++++++++++++++++
 doc/README.pod   | 82 ++++++++++++++++++++++++++++++++++++++++++
 extra/hosts      |  3 ++
 extra/nginx.conf | 92 ++++++++++++++++++++++++++++++++++++++++++++++++
 lib/Chatty.pm    |  1 +
 5 files changed, 251 insertions(+)
 create mode 100644 README
 create mode 100644 doc/README.pod
 create mode 100644 extra/hosts
 create mode 100644 extra/nginx.conf

diff --git a/README b/README
new file mode 100644
index 0000000..c60cc4f
--- /dev/null
+++ b/README
@@ -0,0 +1,73 @@
+NAME
+    Chatty -- Real-time (comet) chat application using Catalyst
+
+SYNOPSIS
+        # install perl dependencies; skip to the next set of instructions
+        # while the dependencies are installing
+        cpan Catalyst::Devel
+        perl Makefile.PL
+        make installdeps
+
+        # install nginx (or install and configure some other reverse proxy)
+        # configure nginx and run it
+        sudo cp extra/nginx.conf /etc/nginx/nginx.conf
+        sudo /etc/rc.d/nginx start
+
+        # configure the comet server (see L<http://meteorserver.org/>)
+        sudo cp extra/cometd/meteord.conf.dist /etc/meteord.conf
+        # add the 'SubscriberDocumentRoot' option to meteord.conf;
+        # it should be set to $REPOSITORY_ROOT/extra/cometd/public_html
+        # run meteord (in another terminal)
+        ./extra/cometd/meteord -d
+
+        # configure hostnames
+        sudo cat extra/hosts >>/etc/hosts
+
+        # create the user database
+        sqlite3 db/info.db <db/schema.sql
+
+        # finally, run the application and try it out
+        ./script/chatty_server.pl -f
+        firefox http://chatty.com/
+
+DESCRIPTION
+    This is a toy web application implementing real-time (comet) chat. I
+    wrote this as an exercise to see how easy it would be to write such an
+    application using Perl/Catalyst. It was fairly easy.
+
+    Catalyst itself provides no streaming support or message bus, so I am
+    using a dedicated comet server to handle all of that, meteord. However,
+    in order to get meteord to work, it needs to be serving on the same port
+    as the Catalyst app. I accomplished this by using nginx as a reverse
+    proxy. However, you can't just use localhost because meteord does some
+    checks on the hostname to make sure it will not run into any
+    cross-domain restrictions, and those checks barf if the hostname doesn't
+    have a TLD. The fix for this is to just assign some fake hostnames to
+    localhost; the provided nginx configuration uses chatty.com for the
+    Catalyst app and data.chatty.com for the comet server, both on port
+    number 80. The actual Catalyst app runs on port 3000 and meteord runs on
+    port 4670. That's the reason for the complicated setup.
+
+    The perl dependencies can all be installed locally in a subdirectory of
+    the user's home directory using local::lib, like this:
+
+        # install local::lib (see L<http://search.cpan.org/dist/local-lib/>)
+        # then,
+        eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)
+
+    It is also usually much nicer to work with cpanminus rather than plain
+    old cpan:
+
+        # install cpanminus
+        curl -L http://cpanmin.us | perl - --self-upgrade
+
+BUGS
+    Tests are sadly nonexistent. :-(
+
+AUTHOR
+    Charles McGarvey <chazmcgarvey at brokenzipper.com>
+
+LICENSE
+    This library is free software. You can redistribute it and/or modify it
+    under the same terms as Perl itself.
+
diff --git a/doc/README.pod b/doc/README.pod
new file mode 100644
index 0000000..cd25121
--- /dev/null
+++ b/doc/README.pod
@@ -0,0 +1,82 @@
+
+=head1 NAME
+
+Chatty -- Real-time (comet) chat application using Catalyst
+
+=head1 SYNOPSIS
+
+    # install perl dependencies; skip to the next set of instructions
+    # while the dependencies are installing
+    cpan Catalyst::Devel
+    perl Makefile.PL
+    make installdeps
+
+    # install nginx (or install and configure some other reverse proxy)
+    # configure nginx and run it
+    sudo cp extra/nginx.conf /etc/nginx/nginx.conf
+    sudo /etc/rc.d/nginx start
+
+    # configure the comet server (see L<http://meteorserver.org/>)
+    sudo cp extra/cometd/meteord.conf.dist /etc/meteord.conf
+    # add the 'SubscriberDocumentRoot' option to meteord.conf;
+    # it should be set to $REPOSITORY_ROOT/extra/cometd/public_html
+    # run meteord (in another terminal)
+    ./extra/cometd/meteord -d
+
+    # configure hostnames
+    sudo cat extra/hosts >>/etc/hosts
+
+    # create the user database
+    sqlite3 db/info.db <db/schema.sql
+
+    # finally, run the application and try it out
+    ./script/chatty_server.pl -f
+    firefox http://chatty.com/
+
+=head1 DESCRIPTION
+
+This is a toy web application implementing real-time (comet) chat.  I wrote
+this as an exercise to see how easy it would be to write such an
+application using Perl/Catalyst.  It was fairly easy.
+
+Catalyst itself provides no streaming support or message bus, so I am using
+a dedicated comet server to handle all of that, meteord.  However, in order
+to get meteord to work, it needs to be serving on the same port as the
+Catalyst app.  I accomplished this by using nginx as a reverse proxy.
+However, you can't just use localhost because meteord does some checks on
+the hostname to make sure it will not run into any cross-domain
+restrictions, and those checks barf if the hostname doesn't have a TLD.
+The fix for this is to just assign some fake hostnames to localhost; the
+provided nginx configuration uses chatty.com for the Catalyst app and
+data.chatty.com for the comet server, both on port number 80.  The actual
+Catalyst app runs on port 3000 and meteord runs on port 4670.  That's the
+reason for the complicated setup.
+
+The perl dependencies can all be installed locally in a subdirectory of the
+user's home directory using local::lib, like this:
+
+    # install local::lib (see L<http://search.cpan.org/dist/local-lib/>)
+    # then,
+    eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)
+
+It is also usually much nicer to work with cpanminus rather than plain old
+cpan:
+
+    # install cpanminus
+    curl -L http://cpanmin.us | perl - --self-upgrade
+
+=head1 BUGS
+
+Tests are sadly nonexistent. :-(
+
+=head1 AUTHOR
+
+Charles McGarvey E<lt>chazmcgarvey at brokenzipper.comE<gt>
+
+=head1 LICENSE
+
+This library is free software. You can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
+
diff --git a/extra/hosts b/extra/hosts
new file mode 100644
index 0000000..6c137fa
--- /dev/null
+++ b/extra/hosts
@@ -0,0 +1,3 @@
+
+127.0.0.1	chatty.com data.chatty.com
+
diff --git a/extra/nginx.conf b/extra/nginx.conf
new file mode 100644
index 0000000..cf522e8
--- /dev/null
+++ b/extra/nginx.conf
@@ -0,0 +1,92 @@
+user nginx nginx;
+worker_processes 1;
+
+error_log /var/log/nginx/error_log info;
+
+events {
+	worker_connections 1024;
+	use epoll;
+}
+
+http {
+	include /etc/nginx/mime.types;
+	default_type application/octet-stream;
+
+	log_format main
+		'$remote_addr - $remote_user [$time_local] '
+		'"$request" $status $bytes_sent '
+		'"$http_referer" "$http_user_agent" '
+		'"$gzip_ratio"';
+
+	client_header_timeout 10m;
+	client_body_timeout 10m;
+	send_timeout 10m;
+
+	connection_pool_size 256;
+	client_header_buffer_size 1k;
+	large_client_header_buffers 4 2k;
+	request_pool_size 4k;
+
+	gzip on;
+	gzip_min_length 1100;
+	gzip_buffers 4 8k;
+	gzip_types text/plain;
+
+	output_buffers 1 32k;
+	postpone_output 1460;
+
+	sendfile on;
+	tcp_nopush on;
+	tcp_nodelay on;
+
+	keepalive_timeout 75 20;
+
+	ignore_invalid_headers on;
+
+	index index.html;
+
+	server {
+		listen 80;
+		server_name chatty.com;
+
+		access_log /var/log/nginx/chatty main;
+		error_log /var/log/nginx/chatty info;
+
+		location / {
+			proxy_set_header Host $http_host;                                             
+			proxy_set_header X-Forwarded-Host $http_host;                                 
+			proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+			#proxy_set_header X-Forwarded-Port 443;                                        
+			proxy_set_header X-Real-IP $remote_addr;                                      
+			proxy_pass http://localhost:3000/;
+		}
+	}
+
+	server {
+		listen 80;
+		server_name data.chatty.com;
+
+		access_log /var/log/nginx/chatty main;
+		error_log /var/log/nginx/chatty info;
+
+		location / {
+			proxy_buffering off;
+			proxy_pass http://localhost:4670/;
+		}
+	}
+
+	# SSL example
+	#server {
+	#	listen 127.0.0.1:443;
+	#	server_name localhost;
+
+	#	ssl on;
+	#	ssl_certificate /etc/ssl/nginx/nginx.pem;
+	#	ssl_certificate_key /etc/ssl/nginx/nginx.key;
+
+	#	access_log /var/log/nginx/localhost.ssl_access_log main;
+	#	error_log /var/log/nginx/localhost.ssl_error_log info;
+
+	#	root /var/www/localhost/htdocs;
+	#}
+}
diff --git a/lib/Chatty.pm b/lib/Chatty.pm
index 80772e7..ba1bad7 100644
--- a/lib/Chatty.pm
+++ b/lib/Chatty.pm
@@ -42,6 +42,7 @@ our $VERSION = '0.01';
 
 __PACKAGE__->config(
 	name => 'Chatty',
+	using_frontend_proxy => 1,
 	# Disable deprecated behavior needed by old applications
 	disable_component_resolution_regex_fallback => 1,
 	'Plugin::Authentication' => {
-- 
2.43.0