=head1 Installing FixMyStreet

=head1 DOWNLOADING

Fetch the latest version from L<http://github.com/mysociety/fixmystreet>

At the moment the best way is to clone it using git:

    git clone https://github.com/mysociety/fixmystreet.git

You'll then need to install mySociety's common library of code by running the 
following command from inside the fixmystreet directory:

    git submodule update --init

=head1 REQUIREMENTS

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

=head2 Software requirements

=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 L<http://sass-lang.com/>

=back

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

If you're using a Debian based Linux distribution then the packages to
install all the required dependencies are listed in C<conf/packages>. To
install all of them you can run:

    xargs -a conf/packages apt-get install

Note, you will need to either be logged in as root or to use

    sudo xargs -a conf/packages apt-get install

for this to work.

=head2 Service dependencies

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 mapit pypi page: L<http://pypi.python.org/pypi/django-mapit/>

If you are in the UK then you can always use the mySociety's MaPit: L<http://mapit.mysociety.org>
although please check with us if you are expecting to generate a lot of
requests.

You will also need a Tile Server to serve up Map tiles. FixMyStreet can use
Google, Bing and OpenStreetMap Tile servers.

Finally, you will need a geolocation service to turn addresses into longitude
and latitudes. FixMyStreet currently includes code to use both Bing and Google
geolocation services.

=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 on the django site: 
L<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 C<db/schema.sql> to create the required
tables, triggers and stored procedures. You will also need to run
C<db/alert_types.sql> which
populates the alert_types table.

=head2 Install Perl modules

FixMyStreet uses a number of CPAN modules which are installed by the
C<bin/install_perl_modules> script. This will install them into a directory
called local.

It uses cpanminus and Carton under the hood but should install these
of they are missing. You may need to install some source packages to
allow some of the included modules to be built, including:

=over

=item *

expat

=item *

Postgresql

=item *

The GMP math library

=back

You will also need development tools installed. If you have installed the
above source packages from distribution packages this should also install
the required development tools.

=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 in C<conf/httpd.conf-example>
which contains a sample configuration and the required redirect rules.

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

=back

For most Linux distributuions you should be able to install these using the distribution's
packaging system.

=head1 SETTINGS

The settings for FixMyStreet are defined in C<conf/general.yml> using the YAML
markup language. There are some defaults in C<conf/general.yml-example> which
you should copy to C<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 sass (L<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.

=head2 Cron jobs

There is an example crontab in C<conf/crontab.ugly>. At the moment this is in
the format used by mySociety's internal deployment tools. To convert this to
a valid crontab the following should be done:

=over

=item *

Replace C<!!(*= $user *)!!> with the name of the user the cron should run under

=item *

Replace C<!!(* $vhost *)!!> with the path to the FixMyStreet code.

=back

=head2 Check it's working

You can run the unit tests using C<prove -r t> in the FixMyStreet directory. Note
that this may leave entries in your database at the moment and should not be run 
on a live site.

=head2 Next Steps

The admin site should be protected using HTTP AUTH.

Customise your install using Templates, CSS and a Cobrand module. See C<notes/customisation.pod>
for details.

Add contact details for authorities and categories using the admin interface.

Add authority data to the MaPit install if required.

=head1 COMMON PROBLEMS

=head2 locale

By default FixMyStreet uses 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.

=head2 Image::Magick perl module

If your OS has a way to install a binary version of Image::Magick then it's recommended
that you do that rather than install via CPAN.

=head2 Missing Perl modules

We think we've included all the modules you should need to run and develop FixMyStreet on your
machine but it we've missed one (please let us know if this is the case), or you want to add one
for something you are developing then you can do so using:

    ./bin/cron-wrapper ./local/bin/carton install Module::To::Add

which will install the module into the local directory. C<./bin/cron-wrapper> is a script to
make sure the correct library paths are set up for running scripts.