mfile-www - App::MFILE::WWW server startup script
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 --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).
--ddist
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.
by default (in the absence of the --ddist option), $ddist is set to the empty string
$ddist
$ddist_dir is not set
$ddist_dir
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
App::MFILE::WWW::init
config/WWW_Config.pm
since no sitedir option was specified on the command line, no other configuration files are loaded
sitedir
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
HTTP_ROOT
JS and CSS files are considered "static content" and will be served from HTTP_ROOT/js and HTTP_ROOT/css, respectively
HTTP_ROOT/js
HTTP_ROOT/css
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
process_post
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
main_html
Resource.pm
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
baseURL
$site->MFILE_WWW_REQUIREJS_BASEURL
/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
app
$site->MFILE_APPNAME
foobar
app/bazblat
HTTP_ROOT/js/foobar/bazblat.js
in this particular case, of course, MFILE_APPNAME is set to mfile-www
MFILE_APPNAME
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
requirejs.config
cf
passes control to the app/main JS module
app/main
What happens on the JavaScript side is described in a different section of this documentation.
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".
bin/mfile-www
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)
App-Dochazka-WWW
$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)
File::ShareDir::dist_dir( $ddist )
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 with --init
css
js/core
if already running as root, the symlinks are created and the script displays a message asking to be re-run without --init 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
--sitedir=/etc/dochazka-www
WWW_SiteConfig.pm
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"
To install App::MFILE::WWW, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::MFILE::WWW
CPAN shell
perl -MCPAN -e shell install App::MFILE::WWW
For more information on module installation, please visit the detailed CPAN module installation guide.