diff options
Diffstat (limited to 'INSTALL.md')
| -rw-r--r-- | INSTALL.md | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 000000000..304d912b3 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,220 @@ + * Email: angie@mysociety.org; WWW: http://www.mysociety.org + * + * $Id: INSTALL.txt,v 1.10 2009-10-02 13:17:59 francis Exp $ + * + + +These instructions are based on getting the FOI site up and running on +Ubuntu and/or Debian. + +It was last run using the Lucid Lynx version of Ubuntu and on the +Parallels debian instance (2.6.18-4-686). + +Commands are intended to be run via the terminal or over ssh. + +1. Package Installation +----------------------- +i.e. Install git (sudo apt-get install git-core), +to get the alaveteli code from github: git clone https://github.com/sebbacon/alaveteli.git + +Firstly, in a terminal, navigate to the alaveteli folder where this +install guide lives. + +Install the packages that are listed in config/packages using apt-get e.g.: + +> sudo apt-get install `cut -d " " -f 1 config/packages | grep -v "^#"` + +Some of the files also have a version number listed in config/packages - check +that you have appropriate versions installed. Some also list "|" and offer +a choice of packages. + +Some of the required packages only exist in the mysociety debian archive (or we +have updated versions there), so you will want to add that to your +/etc/apt/sources.list: + + deb http://debian.mysociety.org etch main non-free contrib + deb-src http://debian.mysociety.org etch main non-free contrib + +You will also want to install mySociety's common ruby libraries and the Rails +code. Run: + + git submodule update --init + +to fetch the contents of the submodules. + +2. Configure Database +--------------------- + +There has been a little work done in trying to make the code work with +other databases (e.g. SQLite), but the preferred database is PostgreSQL. + +If you don't have it installed: + apt-get install postgresql postgresql-client + +Now we need to set up the database config file to contain the name, +username and password of your postgres database. + +* copy database.yml-example to database.yml in alaveteli/config +* edit it to point to your local postgresql database in the development + and test sections and create the databases: + +Become the 'postgres' user (sudo su - postgres) + +psql template1 + to get into command tool + +\l to list databases + CREATE DATABASE foi_development encoding = 'UTF8'; + CREATE DATABASE foi_test encoding = 'UTF8'; + +Make sure that the user specified in database.yml exists, and has full +permissions on this database. As they need the ability to turn off +constraints whilst running the tests they also need to be a superuser. + (See http://dev.rubyonrails.org/ticket/9981) + + CREATE USER <username> WITH CREATEUSER; + ALTER USER <username> WITH PASSWORD '<password>'; + ALTER USER <username> WITH CREATEDB; + GRANT ALL PRIVILEGES ON DATABASE foi_development TO <username>; + GRANT ALL PRIVILEGES ON DATABASE foi_test TO <username>; + ALTER DATABASE foi_development OWNER TO <username>; + ALTER DATABASE foi_test OWNER TO <username>; + + +3. Set up configs +----------------- + +For overall application settings, copy config/general-example to +config/general and edit to your taste. + +Note that the default settings for frontpage examples are designed to +work with the dummy data shipped with Alaveteli; once you have real +data, you should edit these. + +The default theme is the "WhatDoTheyKnow" theme. When you run +rails-post-deploy, that theme gets installed automatically. + +You'll also want to copy config/memcached.yml-example to +config/memcached.yml. The application is configured, via the Interlock +Rails plugin, to cache content using memcached. You probably don't +want this in your development profile. + +4. Deployment +------------- + +In the 'alaveteli' directory, run: +> ./script/rails-post-deploy + +(This will need execute privs so chmod 755 if necessary) + +This sets up directory structures, creates logs, etc. + +Next, if you have a alaveteli/config/rails_env.rb file, delete it, so that +tests run against our test database, rather than the development one. +(Otherwise, any data you create in development will be blown away every +time you run the tests.) + +If you want some dummy data to play with, you can try loading the +fixtures that the test suite uses into your development database. You +can do this with: + +> rake spec:db:fixtures:load + +Next we need to create the index for the search engine (Xapian): + +> ./script/rebuild-xapian-index + +If this fails, the site should still mostly run, but it's a core +component so you should really try to get this working. + +5. Run the Tests +---------------- + +Make sure everything looks OK: + +> rake spec + +If there are failures here, something has gone wrong with the preceding +steps. You might be able to move on to the next step, depending on how +serious they are, but ideally you should try to find out what's gone +wrong. + +6. Run the Server +----------------- + +run the following to get the server running (may need to chmod 755 again) +> ./script/server --environment=development + +By default the server listens on all interfaces. You can restrict it to the +localhost interface by adding --binding=127.0.0.1 + +You’ll probably need to install various things to make this work. The server +script will tell you about any missing dependencies. + + +7. Success +---------- + +The server should have told you the URL to access in your browser to see +the site in action. + +8. Administrator privileges +--------------------------- + +By default, anyone can access the administrator pages without authentication. +They are under the URL /admin. + +At mySociety, we use a separate layer of HTTP basic authentication, proxied +over HTTPS, to check who is allowed to use the administrator pages. You might +like to do something similar. + +Alternatively, update the code so that +* By default, admin pages use normal site authentication (checking user admin +level 'super'). +* Create an option in config/general which lets mySociety override that +behaviour. +And send us the patch! + +9. Mailer setup +--------------- + +When an authority receives an email, its reply-to address is a magic +email which is parsed and consumed by the Rails app. + +Currently, this is done by calling script/mailin and piping in the raw +email. You will need to configure your MTA to accept emails to magic +addresses, and to pipe such emails to this script. + +Magic email addresses are of the form: + + <foi+request-3-691c8388@example.com> + +The respective parts of this address are controlled with options in +options/general, thus: + + $OPTION_INCOMING_EMAIL_PREFIX = 'foi+' + $OPTION_INCOMING_EMAIL_DOMAIN = 'example.com' + +INSTALL-exim.txt describes one possible configuration for Exim 1.9. + +When you set up your MTA, note that if there is some error inside +Rails, the email is returned with an exit code 75, which for Exim at +least means the MTA will try again later. Additionally, a stacktrace +is emailed to $OPTION_CONTACT_EMAIL. + +A well-configured installation of this code will separately have had +Exim make a backup copy of the email in a separate mailbox, just in +case. + +This setup isn't very scaleable, as it spawns a new Ruby process for +each email received; patches welcome! + +10. Cron jobs +------------ + +config/crontab.ugly contains the cronjobs we run on WhatDoTheyKnow. It's +in a strange templating format we use in mySociety, but you should be +able to work out the syntax and variables fairly easily :) + +We render the "ugly" file to reference absolute paths, and then drop +it in /etc/cron.d/ on the server. |