[PATCH 0/4] various example updates

[PATCH 0/4] various example updates

[Eric Wong]

TODO: manpages for -httpd...

Eric Wong (4):
      examples/: PSGI example updates
      examples/cgi-webrick.rb: set CGIPathEnv, update comments
      examples: various Apache-related doc updates
      examples/public-inbox.psgi: relax license to GPL-3.0+

 examples/README                | 13 ++++++-------
 examples/apache2_cgi.conf      |  5 +++--
 examples/apache2_perl.conf     | 42 +++++++++++++++---------------------------
 examples/apache2_perl_old.conf | 38 ++++++++++++++++++++++++++++++++++++++
 examples/cgi-webrick.rb        |  5 ++++-
 examples/public-inbox.psgi     | 14 ++++++++++++--
 6 files changed, 78 insertions(+), 39 deletions(-)

[PATCH 1/4] examples/: PSGI example updates

[Eric Wong]

Users wanting to customize their installation should know
to about the usability of STDOUT for logging.
(and we still need manpages for -nntpd and -httpd)
---
 examples/public-inbox.psgi | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/examples/public-inbox.psgi b/examples/public-inbox.psgi
index 0d11c19..f574912 100644
--- a/examples/public-inbox.psgi
+++ b/examples/public-inbox.psgi
@@ -3,6 +3,8 @@
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
 # Note: this is part of our test suite, update t/plack.t if this changes
 # Usage: plackup [OPTIONS] /path/to/this/file
+# A startup command for development which monitors changes:
+#	plackup -I lib -o 127.0.0.1 -R lib -r examples/public-inbox.psgi
 use strict;
 use warnings;
 use PublicInbox::WWW;
@@ -22,6 +24,7 @@ builder {
 	};
 	$@ and warn
 "Plack::Middleware::Deflater missing, bandwidth will be wasted\n";
+
 	# Enable to ensure redirects and Atom feed URLs are generated
 	# properly when running behind a reverse proxy server which
 	# sets X-Forwarded-For and X-Forwarded-Proto request headers.
@@ -31,6 +34,13 @@ builder {
 "Plack::Middleware::ReverseProxy missing,\n",
 "URL generation for redirects may be wrong if behind a reverse proxy\n";
 
+	# Optional: Log timing information for requests to track performance.
+	# Logging to STDOUT is recommended since public-inbox-httpd knows
+	# how to reopen it via SIGUSR1 after log rotation.
+	# enable 'AccessLog::Timed',
+	#	logger => sub { syswrite(STDOUT, $_[0]) },
+	#	format => '%t "%r" %>s %b %D';
+
 	enable 'Head';
 	sub { $www->call(@_) };
 }
-- 
EW

[PATCH 2/4] examples/cgi-webrick.rb: set CGIPathEnv, update comments

[Eric Wong]

webrick clears PATH otherwise, and we rely on git commands.
---
 examples/cgi-webrick.rb | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/examples/cgi-webrick.rb b/examples/cgi-webrick.rb
index 21e336d..5554a01 100644
--- a/examples/cgi-webrick.rb
+++ b/examples/cgi-webrick.rb
@@ -1,13 +1,16 @@
 #!/usr/bin/env ruby
 # Sample configuration using WEBrick, mainly intended dev/testing
 # for folks familiar with Ruby and not various Perl webserver
-# deployment options.
+# deployment options.  For those familiar with Perl web servers,
+# plackup(1) is recommended for development and public-inbox-httpd(1)
+# is our production deployment server.
 require 'webrick'
 require 'logger'
 options = {
   :BindAddress => '127.0.0.1',
   :Port => 8080,
   :Logger => Logger.new($stderr),
+  :CGIPathEnv => ENV['PATH'], # need to run 'git' commands
   :AccessLog => [
     [ Logger.new($stdout), WEBrick::AccessLog::COMBINED_LOG_FORMAT ]
   ],
-- 
EW

[PATCH 3/4] examples: various Apache-related doc updates

[Eric Wong]

Plack::Handler::Apache2 exists and seems to work very well.
---
 examples/README                | 13 ++++++-------
 examples/apache2_cgi.conf      |  5 +++--
 examples/apache2_perl.conf     | 42 +++++++++++++++---------------------------
 examples/apache2_perl_old.conf | 38 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 62 insertions(+), 36 deletions(-)
 create mode 100644 examples/apache2_perl_old.conf

diff --git a/examples/README b/examples/README
index 5113393..1244cb2 100644
--- a/examples/README
+++ b/examples/README
@@ -5,14 +5,13 @@ For all server admins
 ---------------------
 public-inbox-config - configuration file, this maps configured inboxes
 
-For Apache2 users without Plack
--------------------------------
-apache2_perl.conf - intended to be the basis of a production config
+For PSGI/Plack (HTTP) servers
+-----------------------------
+public-inbox.psgi - starting point for PSGI/Plack users in production and dev
 
-Web server configs for quick-and-dirty demos
---------------------------------------------
-apache2_cgi.conf - for Apache2 users who cannot install mod_perl
-cgi-webrick.rb - only for Rubyists who do not wish to install Plack or Apache
+For Apache2 users
+-----------------
+apache2_perl.conf - intended to be the basis of a production config
 
 Contact
 -------
diff --git a/examples/apache2_cgi.conf b/examples/apache2_cgi.conf
index 775b7e6..5ec64d7 100644
--- a/examples/apache2_cgi.conf
+++ b/examples/apache2_cgi.conf
@@ -1,5 +1,6 @@
-# Example Apache2 configuration using mod_cgi
-# If possible, use mod_perl (see apache2_perl.conf) instead of this.
+# Example Apache2 configuration using CGI mod_cgi
+# If possible, use mod_perl (see apache2_perl.conf) or
+# a standalone PSGI/Plack # server instead of this.
 # Adjust paths to your installation.
 
 ServerName "public-inbox"
diff --git a/examples/apache2_perl.conf b/examples/apache2_perl.conf
index 6615eb9..a4721b5 100644
--- a/examples/apache2_perl.conf
+++ b/examples/apache2_perl.conf
@@ -1,37 +1,25 @@
-# Example Apache2 configuration using mod_perl2
+# Example Apache2 configuration using Plack::Handler::Apache2
 # Adjust paths to your installation
 
 ServerName "public-inbox"
-ServerRoot "/var/www/cgi-bin"
-DocumentRoot "/var/www/cgi-bin"
+ServerRoot "/var/www"
+DocumentRoot "/var/www"
 ErrorLog "/tmp/public-inbox-error.log"
 PidFile "/tmp/public-inbox.pid"
 Listen 127.0.0.1:8080
 LoadModule perl_module /usr/lib/apache2/modules/mod_perl.so
-LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so
-LoadModule dir_module /usr/lib/apache2/modules/mod_dir.so
-LoadModule mime_module /usr/lib/apache2/modules/mod_mime.so
-TypesConfig "/dev/null"
 
-# PerlPassEnv PATH # this is implicit
-<Directory /var/www/cgi-bin>
-	Options +ExecCGI
-	AddHandler perl-script .cgi
-	PerlResponseHandler ModPerl::Registry
-	PerlOptions +ParseHeaders
+# no need to set no rely on HOME if using this:
+PerlSetEnv PI_CONFIG /home/pi/.public-inbox/config
 
-	# we use this hack to ensure "public-inbox.cgi" doesn't show up
-	# in any of our redirects:
-	PerlSetEnv NO_SCRIPT_NAME 1
+<Location />
+	SetHandler perl-script
+	PerlResponseHandler Plack::Handler::Apache2
+	PerlSetVar psgi_app /path/to/public-inbox.psgi
+</Location>
 
-	# no need to set no rely on HOME if using this:
-	PerlSetEnv PI_CONFIG /home/pi/.public-inbox/config
-
-	# our public-inbox.cgi requires PATH_INFO-based URLs with minimal
-	# use of query parameters
-	DirectoryIndex public-inbox.cgi
-	RewriteEngine On
-	RewriteCond %{REQUEST_FILENAME} !-f
-	RewriteCond %{REQUEST_FILENAME} !-d
-	RewriteRule ^.* /public-inbox.cgi/$0 [L,PT]
-</Directory>
+# Optional, preload the application in the parent like startup.pl
+<Perl>
+	use Plack::Handler::Apache2;
+	Plack::Handler::Apache2->preload("/path/to/public-inbox.psgi");
+</Perl>
diff --git a/examples/apache2_perl_old.conf b/examples/apache2_perl_old.conf
new file mode 100644
index 0000000..a6de230
--- /dev/null
+++ b/examples/apache2_perl_old.conf
@@ -0,0 +1,38 @@
+# Example legacy Apache2 configuration using CGI + mod_perl2
+# Consider using Plack::Handler::Apache2 instead (see apache2_perl.conf)
+# Adjust paths to your installation
+
+ServerName "public-inbox"
+ServerRoot "/var/www/cgi-bin"
+DocumentRoot "/var/www/cgi-bin"
+ErrorLog "/tmp/public-inbox-error.log"
+PidFile "/tmp/public-inbox.pid"
+Listen 127.0.0.1:8080
+LoadModule perl_module /usr/lib/apache2/modules/mod_perl.so
+LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so
+LoadModule dir_module /usr/lib/apache2/modules/mod_dir.so
+LoadModule mime_module /usr/lib/apache2/modules/mod_mime.so
+TypesConfig "/dev/null"
+
+# PerlPassEnv PATH # this is implicit
+<Directory /var/www/cgi-bin>
+	Options +ExecCGI
+	AddHandler perl-script .cgi
+	PerlResponseHandler ModPerl::Registry
+	PerlOptions +ParseHeaders
+
+	# we use this hack to ensure "public-inbox.cgi" doesn't show up
+	# in any of our redirects:
+	PerlSetEnv NO_SCRIPT_NAME 1
+
+	# no need to set no rely on HOME if using this:
+	PerlSetEnv PI_CONFIG /home/pi/.public-inbox/config
+
+	# our public-inbox.cgi requires PATH_INFO-based URLs with minimal
+	# use of query parameters
+	DirectoryIndex public-inbox.cgi
+	RewriteEngine On
+	RewriteCond %{REQUEST_FILENAME} !-f
+	RewriteCond %{REQUEST_FILENAME} !-d
+	RewriteRule ^.* /public-inbox.cgi/$0 [L,PT]
+</Directory>
-- 
EW

[PATCH 4/4] examples/public-inbox.psgi: relax license to GPL-3.0+

[Eric Wong]

Using the AGPL for server config files is probably overkill.
GPL-3.0+ still requires appliance vendors to disclose
configurations which seems desirable for end users.
---
 examples/public-inbox.psgi | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/public-inbox.psgi b/examples/public-inbox.psgi
index f574912..dcca3b0 100644
--- a/examples/public-inbox.psgi
+++ b/examples/public-inbox.psgi
@@ -1,6 +1,6 @@
 #!/usr/bin/perl -w
-# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
-# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+# Copyright (C) 2014-2016 all contributors <meta@public-inbox.org>
+# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
 # Note: this is part of our test suite, update t/plack.t if this changes
 # Usage: plackup [OPTIONS] /path/to/this/file
 # A startup command for development which monitors changes:
-- 
EW

[PATCH 2/4] examples/cgi-webrick.rb: set CGIPathEnv, update comments

[Eric Wong]

webrick clears PATH otherwise, and we rely on git commands.
---
 examples/cgi-webrick.rb | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/examples/cgi-webrick.rb b/examples/cgi-webrick.rb
index 21e336d..5554a01 100644
--- a/examples/cgi-webrick.rb
+++ b/examples/cgi-webrick.rb
@@ -1,13 +1,16 @@
 #!/usr/bin/env ruby
 # Sample configuration using WEBrick, mainly intended dev/testing
 # for folks familiar with Ruby and not various Perl webserver
-# deployment options.
+# deployment options.  For those familiar with Perl web servers,
+# plackup(1) is recommended for development and public-inbox-httpd(1)
+# is our production deployment server.
 require 'webrick'
 require 'logger'
 options = {
   :BindAddress => '127.0.0.1',
   :Port => 8080,
   :Logger => Logger.new($stderr),
+  :CGIPathEnv => ENV['PATH'], # need to run 'git' commands
   :AccessLog => [
     [ Logger.new($stdout), WEBrick::AccessLog::COMBINED_LOG_FORMAT ]
   ],
-- 
EW