aboutsummaryrefslogtreecommitdiffstats
path: root/web/js
diff options
context:
space:
mode:
Diffstat (limited to 'web/js')
0 files changed, 0 insertions, 0 deletions
'n53' href='#n53'>53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359
=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

If you're using git version 1.6.5 or later, you can do those steps in
one go with:

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

=head1 REQUIREMENTS

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

=head2 Software requirements

=over

=item *

PostgreSQL.

=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 Debian 6.0 ("squeeze") then the packages to install
some required dependencies (though not all the required Perl modules)
are listed in C<conf/packages.debian-squeeze>. To install all of them
you can run:

    sudo xargs -a conf/packages.debian-squeeze apt-get install

A similar list of packages should work for other Debian-based
distributions.  (Please let us know if you would like to contribute
such a package list or instructions for other distributions.)

To generate the CSS for the current design of FixMyStreet you will
also need Compass L<http://compass-style.org/>, but unfortunately
it is not packaged in Debian squeeze (or squeeze-backports).  You
will either need to install the package from testing, or you could
install it from the Ruby gem with:

    gem install compass

=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 Creating the database

The default settings file (C<conf/general.yml>) assumes the database is called fms and the user the same.
You can change these if you like.

If you wish to create this new database and database user with
password authentication, the following steps may help.  First, create
the fms user:

    $ sudo -u postgres createuser fms
    Shall the new role be a superuser? (y/n) n
    Shall the new role be allowed to create databases? (y/n) n
    Shall the new role be allowed to create more new roles? (y/n) n

Then create the fms database:

    $ sudo -u postgres createdb fms

Set the password of the fms user, and change the owner of the fms database to be the fms user:

    $ sudo -u postgres psql
    postgres=# ALTER USER fms WITH PASSWORD 'somepassword'
    ALTER ROLE
    postgres=# ALTER DATABASE fms OWNER to fms;
    ALTER DATABASE
    postgres=# \q
    $

Then you need to configure PostgreSQL to allow password-based access
to the fms database as the user fms from using Unix-domain sockets.
Edit the file C</etc/postgresql/8.4/main/pg_hba.conf> and add as the
first line:

    local   fms     fms     md5

You will then need to restart PostgreSQL with:

    $ sudo /etc/init.d/postgresql restart

If you want to access the database from the command line, you can add
the following line to C<~/.pgpass>:

    localhost:*:fms:fms:somepassword

Then you should be able to access the database with:

    $ psql -U fms fms

=head2 Set up the database

Before creating the database schema, you will need to install the
PostgreSQL's SQL procedural language into the database:

    createlang -U fms plpgsql fms

Now 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.  For
example, you might run:

    $ psql -U fms fms < db/schema.sql
    ...
    $ psql -U fms fms < db/alert_types.sql
    ...

=head2 Install Perl modules

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

It uses cpanminus and Carton under the hood but should install these
if 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

For production use of FixMyStreet, we suggest you use Apache and
FastCGI.  (See below.)  For local development, however, you can use
the Catalyst development server.  First, install the Catalyst
development tools with:

    ./bin/cron-wrapper local/bin/carton install Catalyst::Devel

Then the development server can be run with:

     CATALYST_DEBUG=1 ./bin/cron-wrapper ./script/fixmystreet_app_server.pl -r

The server will be accessible as L<http://localhost:3000/>.

=head3 Setting up Apache

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_DIR

This is the location where images will be stored when they are 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.