diff options
Diffstat (limited to 'notes')
| -rw-r--r-- | notes/INSTALL | 141 | ||||
| -rw-r--r-- | notes/INSTALL.pod | 284 | ||||
| -rw-r--r-- | notes/customisation.pod | 205 | ||||
| -rw-r--r-- | notes/glossary.txt | 7 |
4 files changed, 489 insertions, 148 deletions
diff --git a/notes/INSTALL b/notes/INSTALL deleted file mode 100644 index bb28e60fa..000000000 --- a/notes/INSTALL +++ /dev/null @@ -1,141 +0,0 @@ -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.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_DIR 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. - -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 - -Notes ------ - -* no-update-server is a shell script used by NUUG for setting up - www.fiksgatami.no using the FixMyStreet codebase. - -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. - diff --git a/notes/INSTALL.pod b/notes/INSTALL.pod new file mode 100644 index 000000000..b795a0043 --- /dev/null +++ b/notes/INSTALL.pod @@ -0,0 +1,284 @@ +=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. + +=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 +some required dependencies (though not all the required Perl modules) 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. + +=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, 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 +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_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. diff --git a/notes/customisation.pod b/notes/customisation.pod new file mode 100644 index 000000000..04bfb6e1d --- /dev/null +++ b/notes/customisation.pod @@ -0,0 +1,205 @@ +=head1 Customising FixMyStreet + +This document explains how to tailor the default installation of +FixMyStreet to your requirements, including limiting the geographic +area it accepts queries for and translating the text. + +It also includes information about how to change the design. + +=head1 OVERVIEW + +FixMyStreet implements a Cobrand system in order to allow customisation +of the default behavior. The Cobrand is made up of a set of templates for +the Cobrand and a Cobrand module that contains code that customises the +way the Cobrand behaves. There are defaults for both of these so the +Cobrand only needs to override things that are specific to it. + +Customisations should be implemented like this as this means that any +upgrade to FixMyStreet will not overwrite your changes. + +For a cobrand to work then it should have the same name as your site, +e.g if your site is www.FixMyPark.com then your Cobrand should be +called FixMyPark. + +The default Cobrand is called Default. + +=head1 TEMPLATES + +Templates are found in the templates directory. Within that there are +seperate directories for web templates and email templates. Under each +of these there is a directory for each Cobrand. In our FixMyPark example +this would be C<templates/web/fixmypark> for the web templates and +C<templates/email/fixmypark> for the email templates. + +The full set of templates is stored in the default Cobrand and if no +equivalent template is found in a Cobrand directory FixMyStreet will +use the default template. + +At a bare minimum you will probably want to copy the header and footer +web templates found in C<templates/web/default/header.html> and +C<templates/web/default/footer.html> into your Cobrand and make appropriate +changes. + +The other template you should make your own version of is the FAQ which +is in C<templates/web/default/faq-en-gb.html> + +=head1 CSS + +The CSS is stored in web/css/ under which there are directories for Cobrands +but this is only by custom. The loading of the css is controled by the header +templates. Note that FixMyStreet uses sccs files to generate our CSS so by there +are no CSS files until C<bin/make_css> has been run. + +The CSS provided with FixMyStreet uses CSS3 media queries in order to adapt +the layout to work on different devices. + +The CSS is structured into two main files: + +=over + +=item core.css + +This contains all the styling for the content of the pages. This should not +need changed unless you are significantly changing the layout of the site. + +=item main.css + +This contains the CSS for the header and footer as well as the colour scheme. + +=back + +=head1 Cobrand modules + +Much of the rest of the customisation takes place in the Cobrand modules. These +are automatically loaded according to the current Cobrand and can be found in +C<perllib/FixMyStreet/Cobrands/>. There is a default Cobrand ( Default.pm ) which +all Cobrands should inherit from. A Cobrand module can then override any of the +methods from the default Cobrand. + +FixMyStreet uses the hostname of the current request along with the contents +of the C<ALLOWED_COBRANDS> config option to determine which cobrand to use. +C<ALLOWED_COBRANDS> is a list of cobrand names with an optional hostname match. +override. If there is no hostname override then the first cobrand name that +matches all or part of the hostname of the current request is used. If there is +a hostname override then that is compared against the hostname of the current +request. For example if C<ALLOWED_COBRANDS> is + + ALLOWED_COBRANDS: + - fixmypark_fr: 'fr.fixmypark' + - fixmypark + +then a request to www.fixmypark.com will use the fixmypark cobrand but a +request to fr.fixmypark.com will use fixmypark_fr. If no Cobrand listed in +C<ALLOWED_COBRANDS> matches then the default Cobrand will be used. + +This means you can provide multiple Cobrands for the site if you require, e.g. +for providing different languages, and FixMyStreet will use the first match +listed in C<ALLOWED_COBRANDS>. + +Many of the functions in the Cobrand module are used by FixMyStreet in the UK +to allow the site to offer versions localised to a single authority and should +not be needed for most installs. Listed below are the most useful options that +can be changed. + +=over + +=item site_title + +This should be set to the name of your site. + +=item country + +This should be set to the two letter ISO code for the country your site is for. + +=item disambiguate_location + +This is used by the Geocoding module of FixMyStreet to constrain the area for +which results are returned when locating an address. It should return a hash +reference of parameters that are compatible with the arguments of the geocoding module +you are using. + +At a most basic level it should limit it to the country you are in: + + sub disambiguate_location { + return { + country => 'uk', + }; + } + +You can limit it to a smaller area using bounding boxes to contrain the area +that the geocoder will consider: + + sub disambiguate_location { + return { + centre => '52.688198,-1.804966', + span => '0.1196,0.218675', + bounds => [ '52.807793,-1.586291', '52.584891,-1.963232' ], + }; + } + +The centre and span are used by the Google geocoding API and the bounds by +Bing. + +Note that these areguments are only as good a limiting results as the API +that they are used by. + +=item geocode_postcode + +This function is used to convert postcodes entered into a latitude and +longitude. If the text passed is not a valid postcode then an error should +be returned. If you do not want to use postcodes and always use a geocoding +service then always return an error. + +If the postcode is valid and can be converted then the return value should +look like this: + + return { latitude => $latitude, longitude => $longitude }; + +If there is an error it should look like this: + + return { error => $error_message }; + +=item find_closest and find_closest_address_for_rss + +These are used to provide information on the closest street to the point of +the address in reports and rss feeds or alerts. + +=item allow_photo_upload + +Return 0 to disable the photo upload field. + +=item allow_photo_display + +Return 0 to disable the display of uploaded photos. + +=item area_types + +If you are using MaPit alongside FixMyStreet this should return a +list of the area type codes that the site will handle. This is used +to filter the data returned from MaPit so that only appropriate areas are +displayed. + +=item remove_redundant_councils + +This is used to filter out any overlapping jurisdictions from MaPit results +where only one of the authorities actually has reponsability for the events +reported by the site. An example would be be a report in a city where MaPit +has an id for the city council and the state council but problems are only +reported to the state. In this case you would remove the id for the the city +council from the results. + +=item short_name + +This is used to turn the full authority name returned by MaPit into a short +name. + +=back + +=head1 Translations and Language + +The translations for FixMyStreet are stored as gettext files and the +language for a Cobrand is set in the C<set_lang_and_domain> call of +the Cobrand module. + +The templates use the C<loc> method to pass strings to gettext for +translation. diff --git a/notes/glossary.txt b/notes/glossary.txt index 0c533a944..5a86e5a63 100644 --- a/notes/glossary.txt +++ b/notes/glossary.txt @@ -1,12 +1,5 @@ Unfamiliar terms that you may come across in the code: - -BCI: Broken Civic Infrastructure - project name before it became FixMyStreet - -still to be found used in some config variable names - MaPit: The mySociety database and web service that maps postcodes and points to current or past administrative area information and polygons for all the United Kingdom. http://mapit.mysociety.org/ - -EvEl: A generic email sending and mailing list functionality, with bounce -detection: https://secure.mysociety.org/cvstrac/dir?d=mysociety/services/EvEl |