diff options
Diffstat (limited to 'notes')
| -rw-r--r-- | notes/INSTALL | 320 |
1 files changed, 220 insertions, 100 deletions
diff --git a/notes/INSTALL b/notes/INSTALL index 560eb6c0f..a5375f272 100644 --- a/notes/INSTALL +++ b/notes/INSTALL @@ -1,141 +1,261 @@ -Installing FixMyStreet -====================== +=head1 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. +=head1 DOWNLOADING + +Fetch the latest version from L<github|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: -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. +=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 L<memcached|http://memcached.org/> + +If you are using a Debian based linux distribution there is a list of relevant +packages in C<conf/packages>. + +=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 L<mapit pypi page|http://pypi.python.org/pypi/django-mapit/> + +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 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 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<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 a development toolchain in place ( gcc, make etc ) + +If you need to add a module manually you can do it using: + + ./bin/cron_wrapper ./local/bin/carton install Module::To::Add + +which will install the module into the local directory + +=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 C<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 + +=back + +=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 -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. +=item CONTACT_EMAIL -Copy conf/general.yml-example to conf/general.yml and set it up appropriately: -* provide the relevant database connection details -* the BASE_URL to be where your test site will run - eg 'http://localhost' -* set UPLOAD_CACHE and GEO_CACHE to your preferred values -* MAP_TYPE - OSM is probably the best one to try to start with, it's being - successfully used. +The email address to be used on the site for the contact us form. -Environment setup ------------------ +=item STAGING_SITE -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` +If this is 1 then all email ( alerts and reports ) will be sent to the +contact email address. Use this for development sites. -Cron scripts can be run through the bin/cron-wrapper script in order to be run -within the right environment. +=item UPLOAD_CACHE -CPAN module dependencies ------------------------- +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. -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: +=item GEO_CACHE - eval `./setenv.pl` - module-manage.pl setup +This is the location where Geolocation data will be cached. +It should be accessible by and writeable by the FixMyStreet process. -Look in the perl-external directory for details. Notably the following are important: +=back -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 +If you are using Bing or Google maps you should also set one of +BING_MAPS_API_KEY or GOOGLE_MAPS_API_KEY. -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 are using a MaPit install you should update MAPIT_URL. -If you need to add a module do it using: +=head2 Generate CSS - module-manage.pl add Module::To::Add - -and it will update all the relevant bits. +There is a script, bin/make_css, that uses L<sass|http://sass-lang.com/> to +convert the SCSS files to CSS files. -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: +=head2 Restart the webserver - cpanm \ - --mirror /absolute/path/to/perl-external/minicpan \ - --mirror-only \ - --force \ - Test::WWW::Mechanize +At this point you be able to restart the webserver and see your FixMyStreet +installation at the configured URL. -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. +=head2 Cron jobs -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 +There is an example crontab in 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: -Notes ------ +=over -* no-update-server is a shell script used by NUUG for setting up - www.fiksgatami.no using the FixMyStreet codebase. +=item * -Running the code -================ +Replace C<!!(*= $user *)!!> with the name of the user the cron should run under -Development ------------ +=item * -Start the catalyst dev server using: +Replace C<!!(* $vhost *)!!> with the path to the FixMyStreet code. - CATALYST_DEBUG=1 ./script/fixmystreet_app_server.pl -r +=back -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. +=head2 Check it's working -Production ----------- +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. -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. +=head2 Next Steps -What's where in the code? -========================= +The admin site should be protected using HTTP AUTH. -FixMyStreet::App is a fairly standard Catalyst app; there aren't any really big -surprises. +Customise your install using Templates, CSS and a Cobrand module. See L<notes/customisation.pod> +for details. -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. +Add contact details for authorities and categories using the admin interface. -Testing -======= +Add authority data to the MaPit install if required. -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. +=head1 COMMON PROBLEMS -Run all the tests (within the correct environment) using: +=head2 locale - prove -lr t +By default FixMyStreet uses the en_GB.UTF-8 locale. If it is not installed then +it may not start -or a specific test in verbose mode using: +=head2 Template caching - prove -lv t/app/controller/report_new.t +FixMyStreet caches compiled templates alongside the source files so the templates +directory needs to be writable by the process that is running FixMyStreet. -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. +=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. |