=pod

=head1 Name

App::Munchies - Catalyst example application using food recipes as a data set

=head1 Version

0.5.$Revision: 1232 $

=head1 Synopsis

   # Start the development server with

   bin/munchies_server -d -r -rd 1 -rr "\\.xml\$|\\.pm\$" \
      --restart_directory lib

   # Start the production server with

   plackup -s Starman --access-log var/logs/starman_server.log \
      bin/munchies_psgi

=head1 Description

This is an example application for the L<CatalystX::Usul> base class

Some web applications require common controllers and data
models. For example; welcome mat, authentication, password changing,
navigation tools and site map are some of the controllers implemented
here. Since these modules are not an end in themselves, most of the
visible text is stored in XML configuration files and can be
customised using the controllers and data models provided. The string
"Munchies" for example is a generic application name and it is meant
to be replaced with a more specific application name once it has been
written

Pages are rendered using a single TT template. The template, CSS,
Javascript and collection of GIFs, PNG, etc are stored together and
form a "skin" for which a switching mechanism is provided. This
enables development of the web application to proceed independently of
the interface development. Content (provided by Perl on Catalyst) has
been separated from layout (TT+CSS), presentation (CSS) and behaviour
(JS). If the interface is not to your liking, write your own
skin. These ideas and techniques have been aquired from
L<http://www.csszengarden.com/> and L<http://www.cssplay.co.uk/>

Don't even think about using anything other than a modern version of
Chrome / Firefox / Opera to display these pages

=head1 Dependencies

Either Apache/mod_perl or Plack/Starman is required to serve HTTP (the
other Catalyst engines are also supported). Requires either PostgreSQL
or MySQL to be installed. The XML parser requires C<libxml2> and
C<libxml2-dev> otherwise a slow pure Perl implementation will be
used. Installing Perl module dependencies from CPAN will require
C<make>, C<gcc> and C<g++> (or equivalents) to be
installed. L<GD::SecurityImage> (used to generate Captchas) depends on
C<libgd2-noxpm> and C<libgd2-noxpm-dev>. It also requires the
C<StayPuft.ttf> font to be installed

=head1 Installation

Run these commands as root to install this application from a
distribution tarball:

   tar -xvzf App-Munchies-?.?.?.tar.gz
   cd App-Munchies-?.?.?
   ./install.sh

It defaults to installing all files (including the F<var> data) under
F</opt/app-munchies> (which is easy to remove if this is not a
permanent installation)

Once the schema has been deployed and populated the following
(optional) commands will be run:

   bin/munchies_cli    -n -c pod2html
   bin/munchies_schema -n -c catalog_mmf

as the I<munchies> user. They may take some time to finish. When
complete the F<var> area of the application is about 60Mb in size

This distribution contains a setuid root program. It is used to
provide limited access to root only functions, e.g. authentication
against F</etc/shadow>. The build process asks if this should be
enabled.  It is not enabled by default

B<N.B.> Remove I<user_root> from F<var/secure/support.sub> if it exists

B<N.B.> Change the password for the admin account in the R00-Internal realm

=head1 Configuration and Environment

Application configuration is in the file
F<lib/App/Munchies/app_munchies.xml>

=head1 Diagnostics

The C<-d> option on the F<bin/munchies_server.pl> command line starts the
development server server in debug mode

=head1 Subroutines/Methods

=head2 list_sessions

Lists the users session data stored in
L<Catalyst::Plugin::Session::Store::FastMmap>

This method should be implemented on each of the C::P::S::Store::* backends

=head2 log_request_parameters

Overrides the Catalyst method to suppress the printing of passwords in
the debug output. The configuration options C<Debug> attribute
C<skip_dump_parameters> should be set to a regex that match the keys
to suppress

=head1 Incompatibilities

Cygwin - Has a wierd gecos field in the passwd file that is a problem
for the identity model.

The L<Pod::ProjectDocs> module will not install without
forcing. L<CatalystX::Usul::ProjectDocs> monkey patches
L<Pod::ProjectDocs> with a different syntax highlighter so that the post
install commands can generate the HTML version the application
documentation

=head1 Bugs and Limitations

There are no known bugs in this module.
Please report problems to the address below.
Patches are welcome

=head1 Author

Peter Flanigan, C<< <Support at RoxSoft.co.uk> >>

=head1 Acknowledgements

Larry Wall - For the Perl programming language

=head1 License and Copyright

Copyright (c) 2011 Peter Flanigan. All rights reserved

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See L<perlartistic>

This program is distributed in the hope that it will be useful,
but WITHOUT WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE

