/ 
App-MFILE-WWW-0.143
River stage one • 1 direct dependent • 1 total dependent
/ mfile-www

NAME

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

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:

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

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 --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).

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.

Standalone operation (demo)

  • by default (in the absence of the --ddist option), $ddist is set to the empty string

  • $ddist_dir is not set

  • the script calls the App::MFILE::WWW::init routine, which loads the configuration parameters stored in config/WWW_Config.pm of the core distro (App::MFILE::WWW) sharedir

  • since no sitedir option was specified on the command line, no other configuration files are loaded

  • the configuration parameters and their core default values can be seen in config/WWW_Config.pm under the core distro (App::MFILE::WWW) sharedir

  • a very important configuration parameter is MFILE_WWW_LOG_FILE, which is the full path to the log file where the Perl side of 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

  • the HTTP server is started by calling Plack::Runner, and the script reports to the user the port number at which it is listening (5001 by default)

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

  • JS and CSS files are considered "static content" and will be served from HTTP_ROOT/js and HTTP_ROOT/css, respectively

  • 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 Web::Machine application (effectively, App::MFILE::WWW::Resource) for processing

  • POST requests are assumed to be AJAX calls and are handled by the process_post routine of App::MFILE::WWW::Resource

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

  • the HTML so generated contains embedded JavaScript code to start up RequireJS with the required configuration and pass control over to "the JavaScript side" of App::MFILE::WWW

The embedded JavaScript code does the following:

  • sets the baseURL to $site->MFILE_WWW_REQUIREJS_BASEURL, which is set to /js -- in absolute terms, this means HTTP_ROOT/js

  • sets the "app" path config to $site->MFILE_APPNAME -- for example, if $site->MFILE_APPNAME is set to 'foobar', the path config for app will be set to foobar and a RequireJS dependency app/bazblat on the JavaScript side will translate to HTTP_ROOT/js/foobar/bazblat.js

  • in this particular case, of course, MFILE_APPNAME is set to mfile-www

  • persuades RequireJS via magic incantations to "play nice" together with jQuery and QUnit

  • by calling requirejs.config, brings in site configuration parameters needed on the JavaScript side so they can be accessed via the cf JS module

  • passes control to the app/main JS module

What happens on the JavaScript side is described in a different section of this documentation.

Derived distribution mode

Nice as the demo may be, the real purpose of App::MFILE::WWW is to provide a structure for writing "real" web frontends. For this purpose, bin/mfile-www is run in "derived distribution mode".

Here is a "play-by-play" description of what happens in this scenario when the startup script is run. Again, refer to the script source code for better understanding:

  • $ddist is set to the string given in the --ddist option, e.g. App-Dochazka-WWW (or 'App::Dochazka::WWW' in which case it will be converted to the correct, hyphen-separated format)

  • $ddist_dir is set to File::ShareDir::dist_dir( $ddist ), i.e. the derived distro sharedir (extending the above example, the distro sharedir of App::Dochazka::WWW)

  • the presence of the --ddist option triggers a special routine whose purpose is to ensure that the derived distro exists and that its sharedir is properly set up to work with App::MFILE::WWW:

    • error exit if the distro referred to by the --ddist option doesn't exist

    • error exit if the distro lacks a sharedir

    • css and js/core need to exist and be symlinks to the same directories in the App::MFILE::WWW sharedir. If this is not the case, the script displays a message asking the user to re-run the script as root

    • if already running as root, the symlinks are created and the script displays a message asking to be re-run as a normal user

    • once the symlinks are in place, the script runs some sanity checks (mainly verifying the existence of certain files in their expected places)

  • the script calls the App::MFILE::WWW::init routine, which loads the configuration parameters stored in the following places:

    • the App::MFILE::WWW distro sharedir (under config/WWW_Config.pm)

    • the derived distro sharedir (also under config/WWW_Config.pm)

    • finally and optionally, if a sitedir was specified on the command line -- for example --sitedir=/etc/dochazka-www --, configuration parameters are loaded from a file WWW_SiteConfig.pm in that directory, overriding the defaults

  • the derived distro's configuration should override the MFILE_APPNAME parameter -- in our example, it could be set to 'dochazka-www'

  • also refer to the previous section to review the explanation of the MFILE_WWW_LOG_FILE parameter

  • the HTTP server is started by calling Plack::Runner, and the script reports to the user at what port number it is listening (5001 by default)

  • the HTTP server always interprets URL paths it receives relative to its "root" (called HTTP_ROOT for the purposes of this document), which is set to the derived distro's sharedir

  • the rest of the description is the same as for "Standalone operation"