diff options
Diffstat (limited to 'notes/INSTALL.pod')
| -rw-r--r-- | notes/INSTALL.pod | 370 |
1 files changed, 0 insertions, 370 deletions
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. |