path: root/README.pod

=head1 NAME

FixMyStreet

=head1 ABOUT

FixMyStreet is a project that allows anyone to report an issue such as potholes,
broken street lights, severe littering, water leaks. These issues are then
routed to the correct body who can arrange to have them fixed. By default it
supports routing problems via email or using an Open311 WebService.

It's written in Perl and uses the Catalyst web framework.

=head1 QUICKSTART

=over

=item *

Download latest version from [THIS BIT TODO]

=item *

Untar this in the vhost location [TODO - more detail here]

=item *

Create a new PostGIS enabled database

=item *

Run db/schema.sql and the db/alert_types.sql

=item *

Run ./bin/cron-wrapper ./perl-external/bin/module-manage.pl setup

=item *

Create a new Apache vhost based on conf/httpd-conf.example

=item *

Copy conf/general-example.yml to conf/general.yml and update accordingly [FIXME!]

=item *

Generate the CSS by running bin/make_css

=item *

Restart the webserver

=back

=head1 DOWNLOADING

Download from [URL GOES HERE]

or get the latest version from L<github|http://github.com/mysociety/fixmystreet>

=head1 REQUIREMENTS

On the server you are installing FixMyStreet on you will need the following things:

=over

=item *

PostgreSQL and the PostGis extension

=item *

Perl 5.8 or above

=item *

ImageMagick and the perl bindings

=item *

A webserver that supports FastCGI

=item *

gettext

=item *

The CSS for FixMyStreet is generated from SCSS sources so you will need a SCSS
to CSS convertor. You can get one from http://sass-lang.com/

=back

For most uses of FixMyStreet you'll also need access to a MaPit server with
data for the types of bodies you are reporting issues to. For more details on
how to install MaPit see the L<mapit pypi page|http://pypi.python.org/pypi/django-mapit/>

If you're expecting a lot of traffic it's recommended that you install L<memcached|http://memcached.org/>

If you are using a Debian based linux distribution there is a list of relevant
packages in conf/packages.

=head1 DETAILED INSTALLATION INSTRUCTIONS

=head2 Unpacking the Code

Once you've downloaded the code you should unpack it. The best place to do this
is in the location you want the web server vhost to be.

=head2 Creating the database

The default settings file assumes the database is called fms and the user the same. 
You can change these if you like.

The database you create for FixMyStreet should be a PostGis enabled one. The best way
to do this is to use a PostGIS template database. There are good instructions on how
to create one L<on the django site|https://docs.djangoproject.com/en/dev/ref/contrib/gis/install/#spatialdb-template>
as well as some bash scripts that automate the process.

=head2 Set up the database

Once you've created the database you can use the sql in db/schema.sql to create the required
tables, triggers and stored procedures. You will also need to run db/alert_types.sql which
populates the alert_types table.

=head2 Install Perl modules

FixMyStreet uses a number of CPAN modules which can be installed 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

Note that unless you have already installed the DBD::Pg module then you will need
the postgresql source available, most likely through your distributions postgresql-dev
package. You will also need a development toolchain in place ( make, gcc etc ) for
some modules.

Look in the perl-external directory for details. Notably the following are important:

=over

=item urls.txt

url to the specific packages to fetch

=item modules.txt

list of all modules that need to be built

=item minicpan/

local subset of cpan - used as source for all packages

=item local-lib

where the cpan modules get built to

=item lib

some initial modules needed for bootstrap

=item bin

scripts to make it all work

=back

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.

=head2 Set up Webserver

It is recommended that you run FixMyStreet using FastCGI. It should also be
possible to run it using Plack/PSGI.

There is an example Apache vhost configuration file on conf/httpd.conf-example
which you can copy and update the paths in if you are running FixMyStreet under
FastCGI.

If you are using Apache and the sample configuration you will need the following 
modules enabled:

=over

=item *

mod_rewrite

=item *

mod_proxy

=item *

mod_expires

=item *

mod_fastcgi

=over

=head1 SETTINGS

The settings for FixMyStreet are defined in conf/general.yml using the YAML
markup language. There are some defaults in conf/general-example.yml which 
you should copy to conf/general.yml.

The bare minimum of settings you will need to fill in or update are:

=over

=item FMS_DB_PASS

This is the password for the database.

=item BASE_URL

The URL for the homepage of your FixMyStreet install.

=item EMAIL_DOMAIN

The email domain that emails will be sent from

=item CONTACT_EMAIL

The email address to be used on the site for the contact us form.

=item STAGING_SITE

If this is 1 then all email ( alerts and reports ) will be sent to the
contact email address. Use this for development sites.

=item UPLOAD_CACHE

This is the location where imaged will be stored as they are being uploaded.
It should be accessible by and writeable by the FixMyStreet process.

=item GEO_CACHE

This is the location where Geolocation data will be cached.
It should be accessible by and writeable by the FixMyStreet process.

=back

If you are using Bing or Google maps you should also set one of
BING_MAPS_API_KEY or GOOGLE_MAPS_API_KEY.

If you are using a MaPit install you should update MAPIT_URL.

=head2 Generate CSS

There is a script, bin/make_css, that uses L<sass|http://sass-lang.com/> to
convert the SCSS files to CSS files.

=head2 Restart the webserver

At this point you be able to restart the webserver and see your FixMyStreet
installation at the configured URL.

=head1 COMMON PROBLEMS

=head2 CPAN MODULE PROBLEMS

Currently, you probably need to add EncodedColumn manually:

    module-manage.pl add DBIx::Class::EncodedColumn

...because it's explicitly overridden in the code, which is fooling the installer.

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

=head2 locale

By default FixMyStreet used the en_GB.UTF-8 locale. If it is not installed then
it may not start

=head2 Template caching

FixMyStreet caches compiled templates alongside the source files so the templates
directory needs to be writable by the process that is running FixMyStreet.