diff options
Diffstat (limited to 'notes')
| -rw-r--r-- | notes/INSTALL.pod | 359 | ||||
| -rw-r--r-- | notes/cobranding.txt | 5 | ||||
| -rw-r--r-- | notes/code_structure.txt | 33 | ||||
| -rw-r--r-- | notes/customisation.pod | 205 | ||||
| -rw-r--r-- | notes/glossary.txt | 5 | ||||
| -rw-r--r-- | notes/location_related_flow.txt | 23 | ||||
| -rw-r--r-- | notes/no-update-server | 6 |
7 files changed, 29 insertions, 607 deletions
diff --git a/notes/INSTALL.pod b/notes/INSTALL.pod deleted file mode 100644 index 701112b45..000000000 --- a/notes/INSTALL.pod +++ /dev/null @@ -1,359 +0,0 @@ -=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. diff --git a/notes/cobranding.txt b/notes/cobranding.txt index 1db3b8188..db71c87ce 100644 --- a/notes/cobranding.txt +++ b/notes/cobranding.txt @@ -1,5 +1,5 @@ -Notes on adding a co brand --------------------------- +Notes on adding a cobrand +------------------------- Basic steps @@ -10,7 +10,6 @@ NB: this is moderately specific to producing cobrands for UK councils 1: copy an exiting perllib/FixMyStreet/Cobrand/ file to perllib/FixMyStreet/Cobrand/ExampleCom.pm * Change package name at top of file * Change following functions accordingly: - site_title site_restriction problems_clause enter_postcode_text diff --git a/notes/code_structure.txt b/notes/code_structure.txt index c90db1784..310ffb193 100644 --- a/notes/code_structure.txt +++ b/notes/code_structure.txt @@ -1,11 +1,32 @@ The code is broken down into the following sections: -website: code to display the website and handle user submissions +* Website: code to display the website and handle user submissions -backend: send alerts to the councils, work out who should get the alert, various -confirmation emails +* Backend: send reports to the councils, work out who should get alerts, + send questionnaires, and so on -mobile apps: currently for iPhone and Android - two separate apps +* Mobile apps: currently for iPhone and Android - two separate apps, with + a PhoneGap app being worked on. + +* Utility scripts: odds and ends + +Main top level directories +-------------------------- + +android Native Android phone app source code +bin Scripts, ranging from the ones that send reports to councils to + one-offs to fix data import errors +commonlib Shared mySociety functions +conf Configuration file, needed Debian packages, example Apache config, + and example crontab +db Schema for PostgreSQL database +iphone Native iPhone phone app source code +local Local store of Perl modules +locale Translation files +perllib Source code of the FixMyStreet project +phonegap PhoneGap mobile app, in progress +script Catalyst management commands +t Test suite +templates Email and web templates +web Front end static files; CSS, JS, images -utility scripts: odds and ends - eg importing photos from Flickr tagged -'fixmystreet' diff --git a/notes/customisation.pod b/notes/customisation.pod deleted file mode 100644 index 04bfb6e1d..000000000 --- a/notes/customisation.pod +++ /dev/null @@ -1,205 +0,0 @@ -=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 deleted file mode 100644 index 5a86e5a63..000000000 --- a/notes/glossary.txt +++ /dev/null @@ -1,5 +0,0 @@ -Unfamiliar terms that you may come across in the code: - -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/ diff --git a/notes/location_related_flow.txt b/notes/location_related_flow.txt deleted file mode 100644 index 5af3c88f0..000000000 --- a/notes/location_related_flow.txt +++ /dev/null @@ -1,23 +0,0 @@ ---- '/' --- - - Homepage has a search form that submits to /around. There is no location - processing done on the home page. Any queries sent to the homepage are - redirected to /around. - ---- '/around' --- - - SEARCH: allows user to search for a location using postcode or other text. - If nothing matched error shown. If multiple match show alternatives. - - LIST: If a search could be resolved to a lat/lon, or a lot/lon was in query - show matches near that location. - - PARTIAL: If there is a partial token show a message when searching. When a - match is found redirect to '/report/new' for the partial to be completed. - ---- '/report/new' --- - - Requires a lat/lng, or a tile click, or a partial report with a location - stored. If no location can be deteremined redirects back to '/around'. All - form information is lost but the partial token is preserved. - diff --git a/notes/no-update-server b/notes/no-update-server index 1f59c0116..2d149d850 100644 --- a/notes/no-update-server +++ b/notes/no-update-server @@ -318,7 +318,6 @@ BASE_URL: 'http://$servername' EMAIL_DOMAIN: 'nuug.no' CONTACT_EMAIL: '' -TEST_EMAIL_PREFIX: '' CONTACT_NAME: 'FiksGataMi' STAGING_SITE: 1 @@ -329,7 +328,6 @@ GOOGLE_MAPS_API_KEY: '' MAPIT_URL: 'http://mapit.nuug.no' MAP_TYPE: 'OSM' -EVEL_URL: '' GAZE_URL: 'http://gaze.mysociety.org/gaze' # empty = use /usr/sbin/sendmail' @@ -338,12 +336,8 @@ SMTP_SMARTHOST: '' AUTH_SHARED_SECRET: '' HEARFROMYOURMP_BASE_URL: '' -IPHONE_URL: '' ANDROID_URL: 'http://wiki.nuug.no/grupper/fiksgatami/android' -# Log file (used in test harness, and later in admin scripts) -HTTPD_ERROR_LOG: '/var/log/apache/error.log - ALLOWED_COBRANDS: 'fiksgatami' # How many items are returned in the GeoRSS feeds by default |