diff options
| -rw-r--r-- | INSTALL-exim4.md | 43 | ||||
| -rw-r--r-- | INSTALL.md | 193 |
2 files changed, 118 insertions, 118 deletions
diff --git a/INSTALL-exim4.md b/INSTALL-exim4.md index a235d6782..fcc845f0d 100644 --- a/INSTALL-exim4.md +++ b/INSTALL-exim4.md @@ -1,35 +1,36 @@ As an example of how to set up your MTA, in exim on Ubuntu, you might add the following to its configuration. -In /etc/exim4/conf.d/main/04_wdtk_options: +In `/etc/exim4/conf.d/main/04_wdtk_options`: - WDTK_HOME=/path/to/wdtk/software - WDTK_USER=www-data + WDTK_HOME=/path/to/wdtk/software + WDTK_USER=www-data -In /etc/exim4/conf.d/router/04_wdtk: +In `/etc/exim4/conf.d/router/04_wdtk`: - wdtk_request: - debug_print = "R: wdtk for $local_part@$domain" - driver = redirect - data = ${lookup{$local_part}wildlsearch{WDTK_HOME/config/aliases}} - pipe_transport = wdtk_mailin_transport + wdtk_request: + debug_print = "R: wdtk for $local_part@$domain" + driver = redirect + data = ${lookup{$local_part}wildlsearch{WDTK_HOME/config/aliases}} + pipe_transport = wdtk_mailin_transport -In /etc/exim4/conf.d/transport/04_wdtk: +In `/etc/exim4/conf.d/transport/04_wdtk`: - wdtk_mailin_transport: - driver = pipe - command = $address_pipe ${lc:$local_part} - current_directory = WDTK_HOME - home_directory = WDTK_HOME - user = WDTK_USER - group = WDTK_USER + wdtk_mailin_transport: + driver = pipe + command = $address_pipe ${lc:$local_part} + current_directory = WDTK_HOME + home_directory = WDTK_HOME + user = WDTK_USER + group = WDTK_USER -And, assuming you set OPTION_INCOMING_EMAIL_PREFIX to "foi+", this in -config/aliases: +And, assuming you set `OPTION_INCOMING_EMAIL_PREFIX` in your config at +`config/general` to "foi+", create `config/aliases` with the following +content: - ^foi\+request-.*: |/path/to/wdtk/software/script/mailin + ^foi\+request-.*: |/path/to/wdtk/software/script/mailin Finally, make sure you have `dc_use_split_config='true'` in -/etc/exim4/update-exim4.conf.conf, and execute the command +`/etc/exim4/update-exim4.conf.conf`, and execute the command `update-exim4.conf` diff --git a/INSTALL.md b/INSTALL.md index 304d912b3..6ea418a33 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,9 +1,3 @@ - * 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. @@ -12,29 +6,25 @@ 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 +# Package Installation + +First, get hold of the source code from github: + + git clone https://github.com/sebbacon/alaveteli.git -Firstly, in a terminal, navigate to the alaveteli folder where this +(You may need to install git first, e.g. with `sudo apt-get install git-code`) + +Now, 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 "^#"` + 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: @@ -42,165 +32,158 @@ code. Run: to fetch the contents of the submodules. -2. Configure Database ---------------------- +# 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 + + 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 +* 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'; +Become the 'postgres' user (`sudo su - postgres`) 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 +permissions on these databases. 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>; +The following command will set up a user 'foi' with password 'foi': + + echo "CREATE DATABASE foi_development encoding = 'UTF8'; + CREATE DATABASE foi_test encoding = 'UTF8'; + CREATE DATABASE foi_development encoding = 'UTF8'; + CREATE DATABASE foi_test encoding = 'UTF8'; + CREATE USER foi WITH CREATEUSER; + ALTER USER foi WITH PASSWORD 'foi'; + ALTER USER foi WITH CREATEDB; + GRANT ALL PRIVILEGES ON DATABASE foi_development TO foi; + GRANT ALL PRIVILEGES ON DATABASE foi_test TO foi; + ALTER DATABASE foi_development OWNER TO foi; + ALTER DATABASE foi_test OWNER TO foi;" | psql -3. Set up configs ------------------ +# Set up configs -For overall application settings, copy config/general-example to -config/general and edit to your taste. +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. +`rails-post-deploy` (see below), 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. +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; the example +`memcached.yml` file disables this behaviour. -4. Deployment -------------- +# Deployment In the 'alaveteli' directory, run: -> ./script/rails-post-deploy -(This will need execute privs so chmod 755 if necessary) + ./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.) +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 + rake spec:db:fixtures:load Next we need to create the index for the search engine (Xapian): -> ./script/rebuild-xapian-index + ./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 ----------------- +# Run the Tests Make sure everything looks OK: -> rake spec + 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 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 +Run the following to get the server running: -You’ll probably need to install various things to make this work. The server -script will tell you about any missing dependencies. + ./script/server --environment=development - -7. Success ----------- +By default the server listens on all interfaces. You can restrict it to the +localhost interface by adding ` --binding=127.0.0.1` The server should have told you the URL to access in your browser to see the site in action. -8. Administrator privileges ---------------------------- +# Administrator privileges By default, anyone can access the administrator pages without authentication. -They are under the URL /admin. +They are under the URL `/admin`. + +At mySociety (originators of the Alaveteli software), they 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. -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: -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 +* Create an option in `config/general` which lets us override that behaviour. + And send us the patch! -9. Mailer setup ---------------- +# 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. +When an authority receives an email, the email's `reply-to` field is a +magic address which is parsed and consumed by the Rails app. -Currently, this is done by calling script/mailin and piping in the raw +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> + <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' + $OPTION_INCOMING_EMAIL_PREFIX = 'foi+' + $OPTION_INCOMING_EMAIL_DOMAIN = 'example.com' -INSTALL-exim.txt describes one possible configuration for Exim 1.9. +`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. +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 @@ -209,12 +192,28 @@ case. This setup isn't very scaleable, as it spawns a new Ruby process for each email received; patches welcome! -10. Cron jobs ------------- +# 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 +`config/crontab.ugly` contains the cronjobs run on WhatDoTheyKnow. It's +in a strange templating format they 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. +mySociety render the "ugly" file to reference absolute paths, and then +drop it in /etc/cron.d/ on the server. + +# Troubleshooting + +* *Various tests fail with "Your PostgreSQL connection does not support + unescape_bytea. Try upgrading to pg 0.9.0 or later."* + + You have an old version of `pg`, the ruby postgres driver. In + Ubuntu, for example, this is provided by the package `libdbd-pg-ruby`. + + Try upgrading your system's `pg` installation, or installing the pg + gem with `gem install pg` + +* Some of the tests relating to mail are failing + + Did you remember to remove the file `alaveteli/config/rails_env.rb` + as described above? It's created every time you run + `script/rails-post-deploy` |