view release on metacpan or  search on metacpan

lib/App/ForExample.pm  view on Meta::CPAN

package App::ForExample;

use warnings;
use strict;

=head1 NAME

App::ForExample - A guide through Catalyst, Apache, lighttpd, nginx, monit, ..., configuration hell

=head1 VERSION

Version 0.024

=cut

our $VERSION = '0.024';

=head1 SYNOPSIS

    # To output a FastCGI (ExternalServer)/Apache configuration (with monit stub and start-stop script), run:
    for-example catalyst/fastcgi apache2 standalone --class My::App --hostname example.com --output my-app

    # The above command would have created the following:

        my-app.apache2      The Apache2 virtual host configuration (hosted at (www.)example.com)
        my-app.start-stop   The start/stop script to launch the FastCGI process
        my-app.monit        A monit stub used for monitoring the FastCGI process

    # This will generate a basic, stripped-down monit configuration (monitrc) suitable for a non-root user:
    for-example monit --home $HOME/monit --output $HOME/monit/monitrc

    # A mod_perl configuration for Catalyst:
    for-example catalyst/mod_perl --class Project::Xyzzy --hostname xyzzy.com --home Project-Xyzzy

=head1 DESCRIPTION

App::ForExample is a command-line tool for generating sample configurations. It is not designed to do configuration
management, but rather as a guide to get you 80% of the way there

Besides the usual Apache, lighttpd, nginx, and FastCGI configurations, App::ForExample can create a FastCGI start-stop script and a
monit configuration for monitoring those processes

=head1 USAGE

    Usage: for-example ACTION

    Where ACTION can be

    (Note: Every option below is, well, optional. If not specified, a fun default will be chosen/guessed for you)

        catalyst/fastcgi ...

            Generate a Catalyst FastCGI configuration (for monit, start-stop, or the specified http daemon and fastcgi method)

            --class             The Catalyst class for your application (e.g. Project::Xyzzy or My::App)
            --home              The path to your Catalyst home directory, default: . (The current directory)
            --log-home          The directory to log into, default: <home>/log (Below the directory given by --home)
            --base              The base for your application, default: / (At the root)
            --hostname          The hostname from which your application is served (e.g. example.com)

            --bare              Do not output anything BUT the configuration (no monit, no start-stop)
            --output -          Print output to stdout
            --output <path>     Write output to <path> (which can be either a directory or file)
                                This will split output appropiately (e.g. <file>.apache2, <file>.start-stop, <file>.monit)

            --fastcgi-script                The <path> to the Catalyst fastcgi script (e.g. script/xyzzy_fastcgi.pl)
            --fastcgi-socket <path>         Have fastcgi use <path> for the file socket
            --fastcgi-socket <host:port>    Have fastcgi use <host:port> for the socket
            --fastcgi-pid-file <path>       Store the pid for the process in <path>

            apache2 standalone  Apache2 with standalone FastCGI (mod_fastcgi)
            apache2 static      Apache2 with static FastCGI (mod_fastcgi)
            apache2 dynamic     Apache2 with dynamic FastCGI (mod_fastcgi)

            lighttpd standalone lighttpd with dynamic FastCGI
            lighttpd static     lighttpd with static FastCGI

            nginx               nginx with standalone FastCGI (the only kind supported)

            monit               A monit configuration for a standalone FastCGI setup
            start-stop          A start-stop script for a standalone FastCGI setup
            
        catalyst/mod_perl

            Generate a mod_perl2 (for Apache2) Catalyst configuration

            --class             The Catalyst class for your application (e.g. Project::Xyzzy or My::App)
            --home              The path to your Catalyst home directory, default: . (The current directory)
            --log-home          The directory to log into, default: <home>/log (Below the directory given by --home)
            --base              The base for your application, default: / (At the root)
            --hostname          The hostname from which your application is served (e.g. example.com)

        monit

            Generate a basic, stripped-down monit configuration suitable for a non-root user

            --home              The directory designated monit home (containing the pid file, log, rc, ...)

=head1 TUTORIAL

=head2 Apache2 with FastCGI on Ubuntu

Install apache2, mod_fastcgi, and L<FCGI>

    sudo apt-get install apache2 libapache2-mod-fastcgi

    cpan -i FCGI

Create the Catalyst application C<My::App>

lib/App/ForExample.pm  view on Meta::CPAN

    my $name = $ctx->option( 'name' );
    $name = $package_name unless defined $name;

    # Catalyst home
    my $home = $ctx->option( 'home' ) || "./";
    $home = dir( $home )->absolute;

    my $log_home = $ctx->option( 'log_home' ) || $home->subdir( 'log' );
    $log_home = dir( $log_home )->absolute;

    # Catalyst application base
    my $base = $ctx->option( 'base' ) || '/';
    $base =~ s/^\/+//;
    my $alias_base = $base eq '' ? '/' : "/$base/";

    # Hostname
    my $hostname = $ctx->option( 'hostname' ) || "$name.example.com";

    my $fastcgi_script = $ctx->option( 'fastcgi-script' );
    $fastcgi_script = join '/', $home, 'script', "${name_underscore}_fastcgi.pl" unless defined $fastcgi_script;
    my $fastcgi_script_basename = file( $fastcgi_script )->basename;
    my $fastcgi_socket = $ctx->option( 'fastcgi-socket' );
    $fastcgi_socket = "/tmp/$name.socket" unless defined $fastcgi_socket;
    my $fastcgi_host_port;
    if ( $fastcgi_socket =~ m/^(.+):(\d+)$/ ) {
        $fastcgi_host_port = [ $1, $2 ];
    }
    my $fastcgi_socket_path = $ctx->option( 'fastcgi-socket-path' );
    $fastcgi_socket_path = "/tmp/$name.fcgi" unless defined $fastcgi_socket_path;
    my $fastcgi_pid_file = $ctx->option( 'fastcgi-pid-file' );
    $fastcgi_pid_file = "$name-fastcgi.pid" unless $fastcgi_pid_file;
    $fastcgi_pid_file = join '/', $home, $fastcgi_pid_file unless $fastcgi_pid_file =~ m/^\//;

    my @data;
    push @data, package => $package,
        name => $name,
        name_underscore => $name_underscore,
        home => $home,
        log_home => $log_home,
        base => $base,
        alias_base => $alias_base,
        hostname => $hostname,
        fastcgi_script => $fastcgi_script,
        fastcgi_script_basename => $fastcgi_script_basename,
        fastcgi_socket => $fastcgi_socket,
        fastcgi_host_port => $fastcgi_host_port,
        fastcgi_socket_path => $fastcgi_socket_path,
        fastcgi_pid_file => $fastcgi_pid_file,
    ;
    return { @data };
}

sub do_help ($) {
    my $ctx = shift;

    print <<_END_;
Usage: for-example ACTION

Where ACTION can be

(Note: Every option below is, well, optional. If not specified, a fun default will be chosen/guessed for you)

    catalyst/fastcgi ...

        Generate a Catalyst FastCGI configuration (for monit, start-stop, or the specified http daemon and fastcgi method)

        --class             The Catalyst class for your application (e.g. Project::Xyzzy or My::App)
        --home              The path to your Catalyst home directory, default: . (The current directory)
        --log-home          The directory to log into, default: <home>/log (Below the directory given by --home)
        --base              The base for your application, default: / (At the root)
        --hostname          The hostname from which your application is served (e.g. example.com)

        --bare              Do not output anything BUT the configuration (no monit, no start-stop)
        --output -          Print output to stdout
        --output <path>     Write output to <path> (which can be either a directory or file)
                            This will split output appropiately (e.g. <file>.apache2, <file>.start-stop, <file>.monit)

        --fastcgi-script                The <path> to the Catalyst fastcgi script (e.g. script/xyzzy_fastcgi.pl)
        --fastcgi-socket <path>         Have fastcgi use <path> for the file socket
        --fastcgi-socket <host:port>    Have fastcgi use <host:port> for the socket
        --fastcgi-pid-file <path>       Store the pid for the process in <path>

        apache2 standalone  Apache2 with standalone FastCGI (mod_fastcgi)
        apache2 static      Apache2 with static FastCGI (mod_fastcgi)
        apache2 dynamic     Apache2 with dynamic FastCGI (mod_fastcgi)

        lighttpd standalone lighttpd with dynamic FastCGI
        lighttpd static     lighttpd with static FastCGI

        nginx               nginx with standalone FastCGI (the only kind supported)

        monit               A monit configuration for a standalone FastCGI setup
        start-stop          A start-stop script for a standalone FastCGI setup
        
    catalyst/mod_perl

        Generate a mod_perl2 (for Apache2) Catalyst configuration

        --class             The Catalyst class for your application (e.g. Project::Xyzzy or My::App)
        --home              The path to your Catalyst home directory, default: . (The current directory)
        --log-home          The directory to log into, default: <home>/log (Below the directory given by --home)
        --base              The base for your application, default: / (At the root)
        --hostname          The hostname from which your application is served (e.g. example.com)

    monit

        Generate a basic, stripped-down monit configuration suitable for a non-root user

        --home              The directory designated monit home (containing the pid file, log, rc, ...)

For example:

    for-example catalyst/fastcgi apache2 standalone --class My::App --hostname example.com
    for-example monit --home \$HOME/my-monit
    for-example catalyst/mod_perl --class Project::Xyzzy --hostname xyzzy.com --home Project-Xyzzy

_END_
}

start [qw/ help|h|? /], sub {
    my $ctx = shift;