diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CHANGES.md | 39 | ||||
| -rw-r--r-- | doc/INSTALL-exim4.md | 8 | ||||
| -rw-r--r-- | doc/INSTALL-postfix.md | 40 | ||||
| -rw-r--r-- | doc/INSTALL.md | 77 |
4 files changed, 139 insertions, 25 deletions
diff --git a/doc/CHANGES.md b/doc/CHANGES.md index 51da903b1..cca6a08e8 100644 --- a/doc/CHANGES.md +++ b/doc/CHANGES.md @@ -3,17 +3,56 @@ ## Highlighted features * Ruby dependencies are now handled by Bundler +* Support for invalidating accelerator cache -- this makes it much + less likely, when using Varnish, that users will be presented with + stale content. Fixes + [issue #436](https://github.com/sebbacon/alaveteli/issues/436) +* Adding a `GA_CODE` to `general.yml` will cause the relevant Google + Analytics code to be added to your rendered pages +* It is now possible to have more than one theme installed. The + behaviour of multiple themes is now layered in the reverse order + they're listed in the config file. See the variable `THEME_URLS` in + `general.yml-example` for an example. ## Upgrade notes * Existing installations will need to install the Bundler gem. See `INSTALL.md` for details. +* As a result of using bundler, the list of software packages that + should be installed has changed. On Debian, you can run: + + sudo apt-get install `cut -d " " -f 1 config/packages | grep -v "^#"` + + [This gist](https://gist.github.com/2584766) shows the changes to + `config/packages` since the previous release. + * 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) +* To support invalidating the Varnish cache, ensure that there's a + value for `VARNISH_HOST` in `general.yml` (normally this would be + `localhost`). You will also need to update your Varnish server to + support PURGE requests. The example configuration provided at + `config/varnish-alaveteli.vcl` will work for Varnish 3 and above. If + you leave `VARNISH_HOST` blank, it will have no effect. Finally, + you should install the `purge-varnish` init script that's provided + in `ugly` format at `config/purge-varnish-debian.ugly` to ensure the + purge queue is emptied regularly. + +* Administrators are now assumed to log in using standard user accounts + with superuser privileges (see 'Administrator Privileges' in + `INSTALL.md`). The old-style admin account (using credentials from + `general.yml`) is now known as the "emergency user". Deployments + that previously bypassed admin authentication should set the new + `SKIP_ADMIN_AUTH` config variable to `true`. + +# Version 0.5.2 + +This is a hotfix to fix occasional problems importing public body CSVs + # 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-postfix.md b/doc/INSTALL-postfix.md new file mode 100644 index 000000000..70a2954bd --- /dev/null +++ b/doc/INSTALL-postfix.md @@ -0,0 +1,40 @@ +As an example of how to set up your MTA, in postfix on Ubuntu, you might +add the following to its configuration. + +In /etc/postfix/master.cf: + + alaveteli unix - n n - 50 pipe + flags=R user=ALAVETELI_USER argv=ALAVETELI_HOME/script/mailin + +In /etc/postfix/main.cf + + virtual_alias_maps = regexp:/etc/postfix/regexp + +For example + +ALAVETELI_HOME=/path/to/alaveteli/software +ALAVETELI_USER=www-data + +The user ALAVETELI_USER should have write permissions on ALAVETELI_HOME. + +And, assuming you set `OPTION_INCOMING_EMAIL_PREFIX` in your config at +`config/general` to "foi+", create `/etc/postfix/regexp` with the following +content: + + /^foi.*/ alaveteli + + +You should also configure postfix to discard any messages sent to the `BLACKHOLE_PREFIX` +address, whose default value is 'do-not-reply-to-this-address'. For example, add the +following to /etc/aliases: + + # We use this for envelope from for some messages where we don't care about delivery + do-not-reply-to-this-address: :blackhole: + +# Troubleshooting + +To test mail delivery, run: + + $ /usr/sbin/sendmail -bv foi+requrest-1234@localhost + +This tells you if sending the emails to 'foi\+.*localhost' is working. diff --git a/doc/INSTALL.md b/doc/INSTALL.md index 8c4ed505b..2ebc21dab 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 @@ -19,8 +19,9 @@ Next, get hold of the Alaveteli source code from github: git clone https://github.com/sebbacon/alaveteli.git cd alaveteli -This will get the current stable release. If you are a developer and want to -add or try new features, you might want to swap to the development +This will get the current stable release from the master branch (which +always contains the latest release). If you are a developer and want +to add or try new features, you might want to swap to the development branch: git checkout develop @@ -37,7 +38,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.: @@ -45,10 +50,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. # Install Ruby dependencies @@ -248,7 +250,7 @@ component so you should really try to get this working. Make sure everything looks OK: - rake spec + 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 @@ -281,23 +283,26 @@ the site in action. # Administrator privileges -By default, anyone can access the administrator pages without authentication. -They are under the URL `/admin`. +The administrative interface is at 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. +Only users with the `super` admin level can access the admin +interface. Users create their own accounts in the usual way, and then +administrators can give them `super` privileges. -Alternatively, update the code so that: +There is an emergency user account which can be accessed via +`/admin?emergency=1`, using the credentials `ADMIN_USERNAME` and +`ADMIN_PASSWORD`, which are set in `general.yml`. To bootstrap the +first `super` level accounts, you will need to log in as the emergency +user. -* By default, admin pages use normal site authentication (checking user admin -level 'super'). -* Create an option in `config/general` which lets us override that -behaviour. - -And send us the patch! +Users with the superuser role also have extra privileges in the +website frontend, such as being able to categorise any request, being +able to view items that have been hidden from the search, and being +presented with "admin" links next to individual requests and comments +in the front end. +It is possible completely to override the administrator authentication +by setting `SKIP_ADMIN_AUTH` to `true` in `general.yml`. # Cron jobs @@ -324,7 +329,14 @@ One of the cron jobs refers to a script at `/etc/init.d/foi-alert-tracks`. This is an init script, a copy of which lives in `config/alert-tracks-debian.ugly`. As with the cron jobs above, replace the variables (and/or bits near the variables) -with paths to your software. +with paths to your software. `config/purge-varnish-debian.ugly` is a +similar init script, which is optional and not required if you choose +not to run your site behind Varnish (see below). + +The cron jobs refer to a program `run-with-lockfile`. See +[this issue](https://github.com/sebbacon/alaveteli/issues/112) for a +discussion of where to find this program, and how you might replace +it. # Set up production web server @@ -347,6 +359,25 @@ Some [production server best practice notes](https://github.com/sebbacon/alaveteli/wiki/Production-Server-Best-Practices) are evolving on the wiki. +# Upgrading Alaveteli + +The developer team policy is that the master branch in git should +always contain the latest stable release. Therefore, in production, +you should usually have your software deployed from the master branch, +and an upgrade can be simply `git pull`. + +Patch version increases (e.g. 1.2.3 -> 1.2.4) should not require any +further action on your part. + +Minor version increases (e.g. 1.2.4 -> 1.3.0) will usually require +further action. You should read the `CHANGES.md` document to see +what's changed since your last deployment, paying special attention to +anything in the "Updgrading" sections. + +You should always run the script `scripts/rails-post-deploy` after +each deployment. This runs any database migrations for you, plus +various other things that can be automated for deployment. + # Troubleshooting * **Incoming emails aren't appearing in my Alaveteli install** |