Notes on getting Catalyst running

1 files changed, 102 insertions, 0 deletions

diff --git a/notes/INSTALL-catalyst.txt b/notes/INSTALL-catalyst.txt
new file mode 100644
index 000000000..2f7175607
--- /dev/null
+++ b/notes/INSTALL-catalyst.txt
@@ -0,0 +1,102 @@
+These are notes on how to get the Catalyst version of FMS up and running during the change from Apache/CGI based code to pure Catalyst based code.
+
+########## location ############
+
+Pretty much everything that follows assumes that you run the commands from the root of the fixmystreet project.
+
+
+########## setup environment ###########
+
+There is a little script that is used to setup the correct environment needed for FMS to run (perl library paths, cpan install locations, bin paths etc). It can either be evaled in a bash shell to set environment variables:
+
+   eval `./setenv.pl`
+
+or used as a runner to start scripts (eg in cron):
+
+   setenv.pl some_script
+
+
+########## build CPAN dependecies ###########
+
+There are many CPAN dependencies that should be dealt with using module-manage.pl which takes care of fetching specific versions of packages from CPAN and building them. To install all the CPAN packages needed:
+
+    eval `./setenv.pl`
+    module-manage.pl setup
+
+Look in the perl-external directory for details. Notably the following are important:
+
+urls.txt    - url to the specific packages to fetch
+modules.txt - list of all modules that need to be built
+minicpan/   - local subset of cpan - used as source for all packages
+local-lib   - where the cpan modules get built to
+lib         - some initial modules needed for bootstrap
+bin         - scripts to make it all work
+
+Read the perl-external/bin/module-manage.pl code to see how it all works. It is basically a wrapper around cpanm (which builds the packages) and dpan (which helps maintain the fake cpan subset).
+
+If you need to add a module do it using:
+
+  module-manage.pl add Module::To::Add
+  
+and it will update all the relevant bits.
+
+If a module won't build (Test::WWW::Mechanize and HTTP::Server::Simple fail tests for me but the failures are not pertinent) then the module-manage script will bail out. Look in ~/.cpanm/build_log to see what went wrong. You can force an install if the test failures are not important by running cpanm directly:
+
+    cpanm                                                   \
+        --mirror /absolute/path/to/perl-external/minicpan   \
+        --mirror-only                                       \
+        --force                                             \
+        Test::WWW::Mechanize
+
+Hopefully once it is all built we can put something like this into the exec in vhosts.pl to make sure that the setup is current:
+
+    setenv.pl module-manage.pl setup
+
+
+############ running the code (dev server) ############
+
+Start the catalyst dev server using:
+
+  CATALYST_DEBUG=1 ./script/fixmystreet_app_server.pl -r
+
+CATALYST_DEBUG turns on the very verbose debug output which is helpful to see what the code is actually doing. The '-r' flag watches for files to change and then restarts the dev server.
+
+
+############ running the code (under Apache) #############
+
+The Catalyst App (FixMyStreet::App) is the last thing that gets tried by apache if none of the redirects in httpd.conf get triggered. This means that the existing code can run unchanged and the bits we want to have Catalyst process just get removed from the redirects.
+
+Currently the httpd.conf runs the FixMyStreet::App as a cgi (rather than fastcgi) which means that the startup hit happens everytime. In production this should probably be fastcgi, or we could go all hip and use the psgi interface. Whatevah!
+
+
+################ databases ######################
+
+The database modifications needed are in the scripts 'db/schema_00*' which should be applied in order.
+
+After further changes to the schema the script 'db/rerun_dbic_loader.pl' should be run to inspect the database and update the model files in perllib/FixMyStreet/DB/Result. Also note that several tables are ignored in that script but just deleting them from the ignore list will cause code to be generated for them.
+
+The DBIx::Class code is pulled into the FixMyStreet::App using FixMyStreet::App::Model::DB which is just a thin wrapper. The separation is there so that the models can be easily used outside of Catalyst (eg in the utility scripts).
+
+The DBIx::Class code uses a separate DBI connection than the mySociety::DBHandler code. This is due to different assumptions about the transaction commit policy.
+
+
+########## What's where in the code? ##############
+
+FixMyStreet::App is a fairly standard Catalyst app, there aren't any really big surprises.
+
+Note that the FixMyStree.pm file is used though to abstract some config related things. Note the FixMyStreet->test_mode(1) which will do things like send all emails to a memory queue for the test scripts. test_mode should only be used in test scripts, and so is different from setting STAGING to true.
+
+
+############## testing ##################
+
+There are several tests in the t directory - organized into subdirs. Note that there is a module FixMyStreet::TestMech that abstracts some things like logging in as a user and grabbing all the form error messages. This makes testing much slicker and less fiddly.
+
+Run all the tests using:
+
+  prove -lr t
+
+or a specific test in verbose mode using:
+
+  prove -lv t/app/controller/reports_new.t
+
+For all the lovely options do 'prove --help'. Note I've made no attempt to make the tests be able to run in parallel, the database fiddling would not be worth it.
\ No newline at end of file