From eb2dcf3ad9bfd2beae1fdcd496570bfc1a788a65 Mon Sep 17 00:00:00 2001 From: Struan Donald Date: Fri, 3 Feb 2012 10:25:21 +0000 Subject: add .pod extension --- notes/INSTALL | 261 ------------------------------------------------------ notes/INSTALL.pod | 261 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 261 insertions(+), 261 deletions(-) delete mode 100644 notes/INSTALL create mode 100644 notes/INSTALL.pod (limited to 'notes') diff --git a/notes/INSTALL b/notes/INSTALL deleted file mode 100644 index a5375f272..000000000 --- a/notes/INSTALL +++ /dev/null @@ -1,261 +0,0 @@ -=head1 Installing FixMyStreet - -=head1 DOWNLOADING - -Fetch the latest version from L - -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 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 - -=back - -If you're expecting a lot of traffic it's recommended that you install L - -If you are using a Debian based linux distribution there is a list of relevant -packages in C. - -=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 - -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 -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 to create the required -tables, triggers and stored procedures. You will also need to run -C which -populates the alert_types table. - -=head2 Install Perl modules - -FixMyStreet uses a number of CPAN modules which are installed by the -C 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 -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 using the YAML -markup language. There are some defaults in C which -you should copy to C. - -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_CACHE - -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. - -=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 L 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 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 with the name of the user the cron should run under - -=item * - -Replace C with the path to the FixMyStreet code. - -=back - -=head2 Check it's working - -You can run the unit tests using C 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 L -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. diff --git a/notes/INSTALL.pod b/notes/INSTALL.pod new file mode 100644 index 000000000..a5375f272 --- /dev/null +++ b/notes/INSTALL.pod @@ -0,0 +1,261 @@ +=head1 Installing FixMyStreet + +=head1 DOWNLOADING + +Fetch the latest version from L + +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 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 + +=back + +If you're expecting a lot of traffic it's recommended that you install L + +If you are using a Debian based linux distribution there is a list of relevant +packages in C. + +=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 + +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 +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 to create the required +tables, triggers and stored procedures. You will also need to run +C which +populates the alert_types table. + +=head2 Install Perl modules + +FixMyStreet uses a number of CPAN modules which are installed by the +C 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 +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 using the YAML +markup language. There are some defaults in C which +you should copy to C. + +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_CACHE + +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. + +=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 L 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 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 with the name of the user the cron should run under + +=item * + +Replace C with the path to the FixMyStreet code. + +=back + +=head2 Check it's working + +You can run the unit tests using C 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 L +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. -- cgit v1.2.3