INSTALL.txt

TheyWorkForYou.com Installation Instructions 
============================================
$Id: INSTALL.txt,v 1.8 2008/01/24 22:11:36 matthew Exp $

TODO: Add an explanation of how to set up a virtual host in apache.

Introduction
============

This file explains how to install a working version of
theyworkforyou.com. I'll assume you have a basic knowledge of apache,
php and mysql.

System Requirements
===================

* Perl 5.8.1 

* PHP 4.3.3

  The site appears to work on the whole with PHP 5, do let us know if it errors
  anywhere. short_open_tag has to be enabled. PHP must be configured with curl, 
  using the '--with-curl' option.

* Apache 1.3.28

  The site also appreas to work on the whole with Apache 2.2

* MySQL 4.1

  Note: it is possible to make the code with 4.0 versions of MySQL, but you have
  to do some mucking around with character sets.

Other sources of help
=====================

Documentation and help is also available from the following:

1. mySociety IRC - http://www.irc.mysociety.org/ - there are
   generally always people hanging around willing to help or
   point you in the right direction.

2. Out of date wiki:
   http://wiki.theyworkforyou.com/cgi-bin/moin.cgi

3. Also look out for announcements on http://www.theyworkforyou.com/
   or http://www.mysociety.org/

Installation
============

NOTE: 
  I assume you will set this up to run as a NAME BASED VIRTUAL
  HOST. It's quite possible to set it up without using its own
  virtual host, but I'll not cover that here.

INSTALLATION SECTION 1 -- THE BASICS
====================================
1. Download the latest version of the TheyWorkForYou code from:
   https://secure.mysociety.org/cvstrac/dir?d=mysociety/twfy

2. create a new mysql database:

mysqladmin -u root -p create twfy

3. create a user for your database:

grant all on twfy.* to twfy@localhost identified by 'mypass';

4. create database schema. The creation script is in the 'db'
   subdirectory of the theyworkforyou source code package.

$ cd db
$ mysql -u twfy -p twfy < schema.sql

5. Configure the configuration file

In directory
  <theyworkforyou>/conf

You should rename the file:
  general-example
to 
  general

and then edit the first few lines to be appropriate for your setup.

6. configure apache:

If you want to create a virtual host, make sure that the 
NameVirtualHost directive is uncommented and says

NameVirtualHost * 

and then add something like the following, with the paths updated
 for your setup, and restart apache (apachectl restart)

<VirtualHost localether>
 ServerAdmin me@example.com
 DocumentRoot /var/www/theyworkforyou/www/docs
 ServerName twfy.example.com
  <Directory /var/www/theyworkforyou/www/docs>
   Options FollowSymLinks
   AllowOverride All
   Allow from all
   Order allow,deny
  </Directory>

 ErrorLog /var/log/httpd/twfy_error
 CustomLog /var/log/httpd/twfy_access combined
</VirtualHost>

INSTALLATION SECTION 2 -- GETTING SOME DATA
===========================================

In this section we'll populate your mysql database with lots of nice
data about MPs. This will be based on XML format data published by
theyworkforyou.com.

1. Download various data from http://www.theyworkforyou.com/pwdata/

You need to preserve the directory structure which exists under pwdata, but you
don't need to get *everything*. Most of the useful stuff is under scrapedxml.
You'll also need the members directory in the parlparse folder, which is
available from http://ukparse.kforge.net/svn/parlparse/ I recommend either
using rsync or downloading the zip files containing all the data if you want it
- for more information, see http://ukparse.kforge.net/parlparse/ under "Getting
the Data".

2. Now you have that data, you are ready to import it into your
   database. You do this using a script called xml2db.pl which is in
   the "scripts" subdir.

3. Make sure the configuration file has it PWMEMBERS variable
   pointing to the 'members' subdir which you fetched above.

4. now run xml2db.pl as follows:

$ ./xml2db.pl --wrans --debates --members --all

That will process all written answers, debates and members. Running
the script with no args gives usage.

**** You should now have a working ****
**** install of theyworkforyou.com ****

Final notes/known issues
========================

1. Features that don't work on development versions.

The Postcode lookup service is disabled on development versions. Instead, postcodes are mapped randomly but deterministically to MPs.

2. Search engine:

the search engine relies uses Xapian (http://www.xapian.org/), which
is a search toolkit written in C++. In order to use the search system,
you need to compile the PHP bindings of Xapian. If you don't have
Xapian, you will probably get an error like this when you try to do a
search:

Fatal error: Class 'XapianStem' not found in
/.../www/includes/easyparliament/searchengine.php
on line 39

There are some instructions on how to do this here:
  http://lists.tartarus.org/pipermail/xapian-discuss/2004-May/000037.html
  
On newer Linuxes, e.g. Ubuntu 14.04, these instructions seem to work well:
  http://trac.xapian.org/wiki/FAQ/PHP%20Bindings%20Package
  
They're even used as part of mySociety's build script:
  https://github.com/mysociety/theyworkforyou/blob/master/bin/site-specific-install.sh#L30-L62

In addition to the PHP bindings you'll also need the Perl bindings to do
the indexing with `search/index.pl`. Just install the Ubuntu package
`libsearch-xapian-perl` and you should be golden.