Installing FixMyStreet
======================

mySociety applications have generally been run on Debian systems. Other Linux
distributions (and more) may well work but may also require some tweaking.

Clone the repository (you've probably already done this):
    git clone git://github.com/mysociety/fixmystreet.git
and be sure to run:
    git submodule update --init
inside to fetch the shared commonlib submodule.

conf/packages is a list of Debian packages that are needed, so install them if
you're on Debian/Ubuntu. You'll also probably need to install lots of CPAN
modules, see the section on that below.

FixMyStreet expects a PostgreSQL database, so set one of them up - the schema
is available in db/schema.sql. You will also need to load in db/alert_types.sql
to populate the alert types table.

Copy conf/general-example to conf/general and set it up appropriately:
* provide the relevant database connection details
* the OPTION_BASE_URL to be where your test site will run - eg 'http://localhost'
* set OPTION_UPLOAD_CACHE and OPTION_GEO_CACHE to your preferred values
* MAP_TYPE - OSM is probably the best one to try to start with, it's being
  successfully used.

Environment setup
-----------------

There is a little script that is used to set up the correct environment needed
for FMS to run (perl library paths, cpan install locations, bin paths etc). It
should be eval-ed in a bash shell to set environment variables:
   eval `./setenv.pl`

Cron scripts can be run through the bin/cron-wrapper script in order to be run
within the right environment.

CPAN module dependencies
------------------------

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 automate the running of module-manage.pl
in order to make sure that the setup is current.

Note: Others are starting to work on this and it might be a good idea to switch
to their output:
http://blogs.perl.org/users/sebastian_willert/2011/03/how-i-distribute-my-projects.html

Running the code
================

Development
-----------

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.

Production
----------

mySociety currently use Apache, our httpd.conf performs a few redirect checks
and then passes everything else to the Catalyst app using FastCGI. Other
options are available with Catalyst, including PSGI, mod_perl, and so on.

What's where in the code?
=========================

FixMyStreet::App is a fairly standard Catalyst app; there aren't any really big
surprises.

Note that the FixMyStreet.pm file is used though to abstract some config
related things. 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 (within the correct environment) using:

  prove -lr t

or a specific test in verbose mode using:

  prove -lv t/app/controller/report_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. The tests currently assume MAPIT_URL is set to the UK version.