view release on metacpan or  search on metacpan

bin/mfile-www  view on Meta::CPAN

# -------------------------------------------------------------------------

use 5.014;
use strict;
use warnings;

#use App::CELL::Test::LogToFile; # uncomment this line to debug initialization
use App::CELL qw( $meta $site );
use App::CELL::Util qw( is_directory_viable );
use App::MFILE::WWW qw( $VERSION );
use Getopt::Long;
use File::Path qw( make_path remove_tree );
use File::ShareDir;
use File::Spec;
use Module::Load;
use Module::Runtime qw( is_module_name require_module );
use Plack::Builder;
use Plack::Runner;
use Plack::Session::Store::File;
use Try::Tiny;
use Web::Machine;
 



=head1 NAME

mfile-www - App::MFILE::WWW server startup script




=head1 SYNOPSIS

Standalone mode (runs demo "app" on http://localhost:5001):

    $ mfile-www

Derived distribution mode with derived distro 'App::Dochazka::WWW':

First, create necessary directories and symlinks by running as root with --init:

    $ sudo mfile-www --ddist=App-Dochazka-WWW --init

Then, start the HTTP server

    $ mfile-www --ddist=App-Dochazka-WWW

Or, if you need site configuration:

    $ mfile-www --dist=App-Dochazka-WWW --sitedir=/foo/bar/baz
  
NOTE: Be careful with the C<--ddist> option - especially when running as
root - because the script will treat the argument to this option as a
"derived" Perl distribution, and attempt to create new directories and
symlinks in that distribution's "sharedir" (shared directory).


=head1 DESCRIPTION

Run this script from the bash prompt to start the server that will provide the
HTTP server (e.g. Starman) that will serve the JavaScript source files that
make up your application's frontend.

=head2 Standalone operation (demo)

=over

=item * by default (in the absence of the C<--ddist> option), C<$ddist> is
set to the empty string

=item * C<$ddist_dir> is not set

=item * the script calls the C<App::MFILE::WWW::init> routine, which loads
the configuration parameters stored in C<config/WWW_Config.pm> of the
core distro (L<App::MFILE::WWW>) sharedir

=item * since no C<sitedir> option was specified on the command line, no
other configuration files are loaded

=item * the configuration parameters and their core default values can be
seen in C<config/WWW_Config.pm> under the core distro (L<App::MFILE::WWW>)
sharedir

=item * a very important configuration parameter is MFILE_WWW_LOG_FILE,
which is the full path to the log file where the Perl side of
L<App::MFILE::WWW> will write its log messages -- by default, this is set
to '.mfile-www.log' in the user's home directory, and the current setting is
always reported on-screen by the startup script so the user knows where to
look if something goes wrong

=item * the HTTP server is started by calling L<Plack::Runner>, and the
script reports to the user the port number at which it is listening (5001 by
default)

=item * the HTTP server always interprets URL paths it receives relative to
its "root" (called C<HTTP_ROOT> for the purposes of this document), which
is set to the core distro (L<App::MFILE::WWW>) sharedir in this case

=item * JS and CSS files are considered "static content" and will be served
from C<HTTP_ROOT/js> and C<HTTP_ROOT/css>, respectively

=item * when an HTTP 'GET' request comes in on the port where the HTTP
server is listening, and it is not requesting static content, the request
is passed on to the L<Web::Machine> application (effectively,
L<App::MFILE::WWW::Resource>) for processing

=item * POST requests are assumed to be AJAX calls and are handled by the
C<process_post> routine of L<App::MFILE::WWW::Resource>

=item * GET requests are assumed to have originated from a web browser
running on a user's computer -- to handle these, the C<main_html> routine
of C<Resource.pm> generates HTML code which is sent back in the HTTP
response

=item * the HTML so generated contains embedded JavaScript code to start up
L<RequireJS|http://requirejs.org> with the required configuration
and pass control over to "the JavaScript side" of L<App::MFILE::WWW>

=back