diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CHANGES.md | 26 | ||||
| -rw-r--r-- | doc/INSTALL-exim4.md | 8 | ||||
| -rw-r--r-- | doc/INSTALL-vagrant.md | 8 | ||||
| -rw-r--r-- | doc/INSTALL.md | 69 |
4 files changed, 61 insertions, 50 deletions
diff --git a/doc/CHANGES.md b/doc/CHANGES.md index 51da903b1..c01bbbe17 100644 --- a/doc/CHANGES.md +++ b/doc/CHANGES.md @@ -2,18 +2,26 @@ ## Highlighted features -* Ruby dependencies are now handled by Bundler +* Ruby dependencies are now handled by Bundler. ## Upgrade notes -* Existing installations will need to install the Bundler gem. See - `INSTALL.md` for details. - -* Because dependencies are now handled by Bundler, when you next run - the `rails-post-deploy` script, it will download, compile and - install various things. Part of this is compiling xapian, which may - take a *long* time (subsequent deployments should be much faster) - +* You should set aside a while to do this upgrade, as it will require + some manual intervention and a wait while dependencies compile: + + * Existing installations will need to install the Bundler gem. See + `INSTALL.md` for details. + + * Because dependencies are now handled by Bundler, when you next run + the `rails-post-deploy` script, it will download, compile and + install various things. Part of this is compiling xapian, which may + take a *long* time (subsequent deployments should be much faster) + +* As a side effect of using bundler, `rake` tasks (such as `rake spec` + and `rake db:migrate`) should now be prefixed with `bundle exec` + (e.g. `bundle exec rake spec`) to ensure they use the correct + bundled environment + # Version 0.5.1 ## Highlighted features diff --git a/doc/INSTALL-exim4.md b/doc/INSTALL-exim4.md index 82c1aba45..84f105c57 100644 --- a/doc/INSTALL-exim4.md +++ b/doc/INSTALL-exim4.md @@ -34,7 +34,7 @@ In `/etc/exim4/conf.d/transport/04_alaveteli`: user = ALAVETELI_USER group = ALAVETELI_USER -And, assuming you set `OPTION_INCOMING_EMAIL_PREFIX` in your config at +And, assuming you set `INCOMING_EMAIL_PREFIX` in your config at `config/general` to "foi+", create `config/aliases` with the following content: @@ -59,7 +59,11 @@ with `FORWARD_NONBOUNCE_RESPONSES_TO: 'raw_team@whatdotheyknow.com'` Finally, make sure you have `dc_use_split_config='true'` in `/etc/exim4/update-exim4.conf.conf`, and execute the command -`update-exim4.conf` +`update-exim4.conf`. + +NB: if the file `/etc/exim4/exim4.conf` exists then `update-exim4.conf` +will silently do nothing. Some distributions include this file. If +yours does, you will need to rename it before running `update-exim4.conf`. (You may also want to set `dc_eximconfig_configtype='internet'`, `dc_local_interfaces='0.0.0.0 ; ::1'`, and diff --git a/doc/INSTALL-vagrant.md b/doc/INSTALL-vagrant.md index 18db33c95..34a8ae30e 100644 --- a/doc/INSTALL-vagrant.md +++ b/doc/INSTALL-vagrant.md @@ -24,9 +24,9 @@ Usage ### Download, install and run VM -NOTE: This will download at least 400MB and take some time (30 minutes with a -broadband internet connection). This time and downloading is only required the -first time you run this command. +NOTE: This will download at least 400MB and take some time (30 minutes +with a broadband internet connection). The downloading is only +required the first time you run this command. You'll be asked for your password to sudo - this is required to create NFS shared folders. @@ -44,7 +44,7 @@ shared folders. ### Run the tests - bundle exec rake + bundle exec rake spec ### Start the development server diff --git a/doc/INSTALL.md b/doc/INSTALL.md index 35d64fc68..5cbad765c 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -6,7 +6,7 @@ deployment platform. Commands are intended to be run via the terminal or over ssh. As an aid to evaluation, there is an -[Amazon AMI](https://github.com/sebbacon/alaveteli/wiki/Alaveteli-ec2-amix) +[Amazon AMI](https://github.com/sebbacon/alaveteli/wiki/Alaveteli-ec2-ami) with all these steps configured. It is *not* production-ready. # Get Alaveteli @@ -27,21 +27,15 @@ branch: # Dev environment quickstart -To get a dev environment running quickly on Debian or Ubuntu, you can -use Chef. - -Alternatively, you can use Vagrant (which provisions a virtual machine -and installs Alaveteli there) on any platform supported by Vagrant. - -These quickstart methods are not currently recommended for production, -because they are still under development (and don't include memcached, -varnish, exim fonfiguration, etc). For production, you should follow -the steps below manually. +To get a dev environment running quickly you can use Vagrant (which +provisions a virtual machine and installs Alaveteli there) on any +platform supported by Vagrant. To install using Vagrant, see `INSTALL-vagrant.md`. -To install using chef, install chef (e.g. `apt-get install chef`) and -run: +You can also use chef to install directly into Debian (Ubuntu may work +but is not currently tested). To do so, first install chef +(e.g. `apt-get install chef`), then run: sudo chef-solo -c chef/solo.rb -j chef/solo.json @@ -57,7 +51,11 @@ packages by adding the following to `/etc/apt/sources.list` and running `apt-get update`: deb http://debian.mysociety.org squeeze main - + +If you don't set up that mySociety Debian source (e.g. if you're +running Ubuntu), you should comment out `wkhtmltopdf-static` from +`config/packages`, as it won't install in the next step + Now install the packages that are listed in config/packages using apt-get e.g.: @@ -65,10 +63,7 @@ e.g.: 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. If you've not set up the -mySociety Debian source (e.g. if you're running Ubuntu), you should -comment out `wkhtmltopdf-static` from `config/packages`, as it won't -install. +"|" and offer a choice of packages. # Step 2: Install Ruby dependencies @@ -203,7 +198,7 @@ is emailed to `CONTACT_EMAIL`. 1.9). 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 +the MTA make a backup copy of the email in a separate mailbox, just in case. # Step 6: Set up configs @@ -225,6 +220,9 @@ 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. +As a precaution, you should probably set your `elinks` configuration +according to the Troubleshooting guide at the end of this document. + # Step 7: Deployment In the 'alaveteli' directory, run: @@ -233,23 +231,18 @@ In the 'alaveteli' directory, run: (This will need execute privs so `chmod 755` if necessary.) This sets up directory structures, creates logs, installs/updates themes, runs -database migrations, etc. You should run it after each new software -update. +database migrations, etc. **You should run it after each new software +update.** One of the things the script does is install dependencies (using `bundle install`). Note that the first time you run it, part of the `bundle install` that compiles `xapian-full` takes a *long* time! -On Debian, at least, the binaries installed by bundler are not put in -the system `PATH`; therefore, in order to run `rake` (needed for -deployments), you will need to do something like: - - ln -s /usr/lib/ruby/gems/1.8/bin/rake /usr/local/bin/ - -Or (Debian): - - ln -s /usr/lib/ruby/gems/1.8/bin/rake /usr/local/bin/ +The binaries installed by bundler are not put in the system `PATH`, +but in `$ALAVETELI_HOME/bin/`; therefore, in order to run `rake` +(needed for deployments), you will need to do something like: + ln -s `pwd`/bin/rake /usr/local/bin/ 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 @@ -271,8 +264,8 @@ Make sure everything looks OK: bundle exec rake spec If there are failures here, something has gone wrong with the -preceding steps (see the next section for a common problem and -workaround). You might be able to move on to the next step, depending +preceding steps (see the next section for common problems and +workarounds). 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. @@ -310,6 +303,9 @@ And send us the patch! # Step 11: Cron jobs `config/crontab.ugly` contains the cronjobs run on WhatDoTheyKnow. +These jobs are mostly to process queues: things that need reindexing, +email alerts that need sending out, etc. + It's in a strange templating format they use in mySociety. mySociety render the "ugly" file to reference absolute paths, and then drop it in `/etc/cron.d/` on the server. @@ -382,16 +378,19 @@ are evolving on the wiki. and then pipe it through the mailin script. A non-zero exit code means there was a problem. For example: + # get a valid email source (this example is from the text fixtures): $ cp spec/fixtures/files/incoming-request-plain.email /tmp/ + # substitute a magic email address in the existing To: header: $ perl -pi -e 's/^To:.*/To: <request-101-50929748@localhost>/' /tmp/incoming-request-plain.email + # now try piping this to the mailin script: $ ./script/mailin < /tmp/incoming-request-plain.email $ echo $? 75 The `mailin` script emails the details of any errors to - `CONTACT_EMAIL` (from your `general.yml` file). A common problem is - for the user that the MTA runs as not to have write access to - `files/raw_emails/`. + `CONTACT_EMAIL` (from your `general.yml` file). A common problem + is when the user that the MTA runs as does not have write access + to `files/raw_emails/`. * **Various tests fail with "*Your PostgreSQL connection does not support unescape_bytea. Try upgrading to pg 0.9.0 or later.*"** |