diff options
| -rw-r--r-- | README.md | 28 | ||||
| -rw-r--r-- | README.pod | 76 | ||||
| -rw-r--r-- | notes/INSTALL.pod | 370 |
3 files changed, 28 insertions, 446 deletions
diff --git a/README.md b/README.md new file mode 100644 index 000000000..32d3c4740 --- /dev/null +++ b/README.md @@ -0,0 +1,28 @@ +# Welcome to FixMyStreet Platform + +FixMyStreet Platform is an open source project to help people run websites for +reporting common street problems such as potholes and broken street lights to +the appropriate authority. + +Users locate problems using a combination of address and sticking a pin +in a map without worrying about the correct authority to report it to. +FixMyStreet then works out the correct authority using the problem location and +type and sends a report, by email or using a web service such as Open311. +Reported problems are visible to everyone so they can see if something has +already been reported and leave updates. Users can also subscribe to email or +RSS alerts of problems in their area. + +It was created in 2007 by [mySociety](http://www.mysociety.org/) for reporting +problems to UK councils and has been copied around the world. + +## Installation + +We're working hard to make FixMyStreet Platform easy to install and re-use in +other countries - please see our site at <http://code.fixmystreet.com/> for +help and documentation in installing FixMyStreet Platform. + +## Examples + +* <http://www.fixmystreet.com/> +* <http://www.fiksgatami.no/> + diff --git a/README.pod b/README.pod deleted file mode 100644 index e49b94991..000000000 --- a/README.pod +++ /dev/null @@ -1,76 +0,0 @@ -=head1 Welcome to FixMyStreet - -FixMyStreet is an open source project to develop a website for reporting -problems such as potholes and broken street lights to the appropriate authority. - -Users locate problems using a combination of address and sticking a pin -in a map without worrying about the correct authority to report it to. -FixMyStreet then works out the correct authority to report it to using -the problem location and type and sends a report. - -It was created in 2007 by L<mySociety|http://www.mysociety.org> for reporting problems to UK councils and -has been copied around the world. - -We're working hard to make it easy to install and re-use in other -countries and welcome questions about how it works on our mailing list: -L<https://secure.mysociety.org/admin/lists/mailman/listinfo/fixmystreet>. - -We've also got a new site and blog which over time will become a useful -resource for people interested in installing or developing FixMyStreet -at L<http://code.fixmystreet.com/>. - -FixMyStreet is written in Perl and uses the Catalyst web framework. - -=head1 EXAMPLES - -L<http://www.fixmystreet.com/> - -L<http://www.fiksgatami.no/> - -=head1 QUICKSTART - -If you're reasonably sure what you are doing then you can follow the -quickstart instructions. Otherwise there are more detailed instructions -in C<notes/INSTALL.pod> - -=over - -=item * - -Fetch the latest version from L<Github|https://github.com/mysociety/fixmystreet> - -=item * - -Create a new Postgres database - -=item * - -Set up the database using C<db/schema.sql> and C<db/alert_types.sql> - -=item * - -Run C<./bin/install_perl_modules> to install the required Perl modules. - -=item * - -Create a new Apache vhost based on C<conf/httpd-conf.example> - -=item * - -Copy C<conf/general.yml-example> to C<conf/general.yml> and update -the defaults accordingly. - -=item * - -Generate the CSS by running C<bin/make_css> - -=item * - -Restart the webserver - -=item * - -Edit the crontab from C<conf/crontab> to replace the placeholders and -install it. See C<notes/INSTALL.pod> for more details on the placeholders. - -=back diff --git a/notes/INSTALL.pod b/notes/INSTALL.pod deleted file mode 100644 index 106f3c174..000000000 --- a/notes/INSTALL.pod +++ /dev/null @@ -1,370 +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 and uses Compass, -so you'll need to install Compass: L<http://compass-style.org/> - -=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.) - -Unfortunately, Compass 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 Installing on Mac OS X - -The github wiki page at -L<https://github.com/mysociety/fixmystreet/wiki/Installing-on-Mac-OS-X> -has a basic runthrough of installation steps to get FiMyStreet running -on a Mac OS X machine. This does not include the setting up of the database. - -=head2 Service dependencies - -FixMyStreet works by mapping points to administrative areas to which reports -can be sent. It normally does this using a different mySociety service called -MapIt. By default, in the absence of a MapIt installation, FixMyStreet will map -any point to the same administrative area, to allow for ease of set up and -testing. - -If you are in the UK then you can use mySociety's UK MapIt: -L<http://mapit.mysociety.org> although please check with us if you are -expecting to generate a lot of requests or are using it commercially. We also -have a global MapIt at L<http://global.mapit.mysociety.org> that may be -suitable for you. If you have some other boundary data, you can set up your -own MapIt server to serve it out; for more details on how to install MapIt see -the mapit repository at L<https://github.com/mysociety/mapit> - -You will also need a tile server to serve up map tiles. FixMyStreet can -currently use Bing and OpenStreetMap tile servers, defaulting to OpenStreetMap. - -Finally, you will need a geolocation service to turn addresses into longitude -and latitudes. FixMyStreet currently includes code to use Bing, Google, and -OpenStreetMap geolocation services, again defaulting to OpenStreetMap. - -=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 might 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 might 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 --fork - -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 Compass and sass 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. |