diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ADMIN.md | 21 | ||||
| -rw-r--r-- | doc/CHANGES.md | 74 | ||||
| -rw-r--r-- | doc/INSTALL.md | 74 | ||||
| -rw-r--r-- | doc/TRANSLATE.md | 15 |
4 files changed, 140 insertions, 44 deletions
diff --git a/doc/ADMIN.md b/doc/ADMIN.md new file mode 100644 index 000000000..07fe9398d --- /dev/null +++ b/doc/ADMIN.md @@ -0,0 +1,21 @@ +Doing development work on the administration interface +====================================================== + +The Alaveteli admin interface uses Twitter's Bootstrap project to prettify it. + +If you want to work on the CSS, you'll want to use +[bootstrap-sass](https://github.com/thomas-mcdonald/bootstrap-sass). Do something like: + + + $ gem install bootstrap-sass + $ gem install compass + $ compass compile --config .compass/config.rb + +The javascript is included in a funky way +[for reasons explained in this commit](https://github.com/sebbacon/adminbootstraptheme/commit/45a73d53fc9e8f0b728933ff58764bd8d0612dab). +To change it, edit the coffeescript at +`lib/view/general/admin.coffee`, and then do something like: + + $ coffee -o /tmp/ -c app/views/admin_general/admin.coffee + $ mv /tmp/admin.js app/views/admin_general/admin_js.erb + diff --git a/doc/CHANGES.md b/doc/CHANGES.md index 2c8692bb5..debf9d7c7 100644 --- a/doc/CHANGES.md +++ b/doc/CHANGES.md @@ -1,11 +1,43 @@ +# Version 0.8 +## Highlighted features +* Support for running the site over SSL/TLS only and corresponding removal of support for a proxied admin interface, including the deprecation of the main_url and admin_url helpers. +* Merging of the adminbootstrap theme into core Alaveteli, replacing the existing admin theme. (Matthew Landauer) +* Move to HTML 5 (Matthew Landauer) +* More consistent UI for links in the admin interface +* [Security] Upgrades the Rails version to 2.3.17 to get fixes for CVE-2013-0277, CVE-2013-0276 (Although core Alaveteli does not use serialize or attr_protected), upgrade JSON gem to get fix for CVE-2013-0269. +* A bugfix for Chrome's autofilling of signup fields (Vaughan Rouesnel) +* Improvements to the accessibility of the search boxes (Nathan Jenkins) +* Only one email sent when asking for admin attention to a request [issue #789](https://github.com/mysociety/alaveteli/pull/864) (Matthew Landauer) +* A number of XSS escaping fixes for Version 0.7 (Matthew Landauer) +* The emergency admin account can now be disabled + +## Upgrade notes +* Check out this version and run `rails-post-deploy` as usual. +* Remove adminbootstrap from the THEME_URLS or THEME_URL config variable, and remove vendor/plugins/adminbootstraptheme, and the softlink public/adminbootstraptheme. +* There is a new config variable FORCE_SSL, which defaults to true, meaning that Alaveteli will redirect all "http" requests to "https", set the Strict-Transport-Security header and flag all cookies as "secure". For more information about running your install over SSL/TLS, see the [install guide](https://github.com/mysociety/alaveteli/blob/develop/doc/INSTALL.md#set-up-production-web-server). If you don't want to run over SSL/TLS, add the config variable FORCE_SSL to your config/general.yml and set it to false. +* If you would like to disable the emergency user account, set DISABLE_EMERGENCY_USER to true in you config/general.yml + +# Version 0.7 +## Highlighted features +* [Security] Upgrades the Rails version from 2.3.15 to 2.3.16 to get fix for a critical security flaw in Rails (CVE-2013-0333). +* Adds rails_xss gem to make HTML escaping the default behaviour in views. +* Allows cap rake:themes:install to be run standalone and in the context of a deploy. +* Gem bundle is always installed in the vendor directory, even in development mode. +* Interlock plugin removed. +* Models have named validation methods, and don't overwrite validate anymore. + +## Upgrade notes +* Check out this version and run `rails-post-deploy` as usual. +* Check your themes for any strings that are now being escaped but shouldn't be and either use raw or .html_safe to resolve them. Don't do this with strings from user input! + # Version 0.6.9 ## Highlighted features * [Security] Fix for security issue where image files from HTML conversion on hidden/requester-only requests were accessible without authentication [issue #739](https://github.com/mysociety/alaveteli/issues/739). * [Security] Fix for issue where the zip file download function was available for logged-in users even on hidden/requester-only requests [issue #743](https://github.com/mysociety/alaveteli/issues/743) * [Security] Upgrades to Rails 2.3.15 to get fixes for Rails security flaws CVE-2012-5664 and CVE-2013-0156. In addition, switches to use Rails pulled from a clone in the mySociety github account, which has had the CVE-2013-0155 2.3 series patch applied to it. -* Isolation of mail handling code in the MailHandler module in lib/mail_handler -* Tests run under Ruby 1.9.3 - *running the app under 1.9 not yet advised*. -* Routes without a locale part can be enabled for the default locale - see upgrade notes +* Isolation of mail handling code in the MailHandler module in lib/mail_handler +* Tests run under Ruby 1.9.3 - *running the app under 1.9 not yet advised*. +* Routes without a locale part can be enabled for the default locale - see upgrade notes * Fixes to support themed error pages, and allow responsive themes (Matthew Landauer, Brendan Molloy) * Migrations run under sqlite (Stefan Langenmaier) * Time zone fixes (Henare Degan) @@ -15,7 +47,7 @@ ## Upgrade notes * Note the new config variable INCLUDE_DEFAULT_LOCALE_IN_URLS (if not set defaults to true, which should replicate existing behaviour) -* Check out this version and run `rails-post-deploy` as usual. +* Check out this version and run `rails-post-deploy` as usual. # Version 0.6.8 ## Highlighted features @@ -36,10 +68,10 @@ * TIME_ZONE (if not set, defaults to UTC) * TWITTER_WIDGET_ID (no Twitter widget is displayed if not set) * THEME_BRANCH (defaults to tagged version specific to your version of alaveteli or, failing that, to master) - * MTA_LOG_PATH + * MTA_LOG_PATH * MTA_LOG_TYPE (defaults to Exim) * IMPORTANT - Copy config/newrelic.yml-example to config/newrelic.yml - by default monitoring is switched off, see https://github.com/newrelic/rpm for instructions on switching on local and remote performance analysis. -* Check out this version and run `rails-post-deploy` as usual. +* Check out this version and run `rails-post-deploy` as usual. * Note that mailcatcher is now used in development - see http://mailcatcher.me/ for details # Version 0.6.7 @@ -56,7 +88,7 @@ ## Upgrade notes * Themes created for 0.6.6 and below should be updated to use the new Configuration module wherever they used Config.get directly previously. -* Check out this version and run `rails-post-deploy` as usual. +* Check out this version and run `rails-post-deploy` as usual. # Version 0.6.6 @@ -68,13 +100,13 @@ ## Upgrade notes -* Check out this version and run `rails-post-deploy` as usual. -* Run `rake temp:populate_request_classifications` to populate the new request_classifications table which is used in generating the request categorisation game league tables and progress widget. +* Check out this version and run `rails-post-deploy` as usual. +* Run `rake temp:populate_request_classifications` to populate the new request_classifications table which is used in generating the request categorisation game league tables and progress widget. # Version 0.6.5 -* This is a minor release, to update all documentation and example files to reflect the move of the official repository to http://github.com/mysociety/alaveteli and the alavetelitheme and adminbootstraptheme themes to http://github.com/mysociety/alavetelitheme and http://github.com/mysociety/adminbootstraptheme respectively. -* Some basic versioning has been added for themes. An ALAVETELI_VERSION constant has been added in config/environment.rb. When loading themes, `rails-post-deploy` now looks for a tag on the theme repository in the form 'use-with-alaveteli-0.6.5' that matches the ALAVETELI_VERSION being deployed - if it finds such a tag, the theme will be checked out from that tag, rather than from the HEAD of the theme repository. If no such tag is found, HEAD is used, as before [issue #573](https://github.com/mysociety/alaveteli/issues/573). -* Apache has been configured to serve cached HTML versions of attached files (and associated images) directly from the file cache, as well as the original versions [issue #580](https://github.com/mysociety/alaveteli/issues/580). +* This is a minor release, to update all documentation and example files to reflect the move of the official repository to http://github.com/mysociety/alaveteli and the alavetelitheme and adminbootstraptheme themes to http://github.com/mysociety/alavetelitheme and http://github.com/mysociety/adminbootstraptheme respectively. +* Some basic versioning has been added for themes. An ALAVETELI_VERSION constant has been added in config/environment.rb. When loading themes, `rails-post-deploy` now looks for a tag on the theme repository in the form 'use-with-alaveteli-0.6.5' that matches the ALAVETELI_VERSION being deployed - if it finds such a tag, the theme will be checked out from that tag, rather than from the HEAD of the theme repository. If no such tag is found, HEAD is used, as before [issue #573](https://github.com/mysociety/alaveteli/issues/573). +* Apache has been configured to serve cached HTML versions of attached files (and associated images) directly from the file cache, as well as the original versions [issue #580](https://github.com/mysociety/alaveteli/issues/580). * PublicBodyCategories have a couple of new methods for more easily working with headings [issue #575](https://github.com/mysociety/alaveteli/issues/575). * [List of issues on github](https://github.com/mysociety/alaveteli/issues?milestone=21&state=closed) @@ -84,10 +116,10 @@ * Please update your `THEME_URLS` to point to http://github.com/mysociety/alavetelitheme and http://github.com/mysociety/adminbootstraptheme if you are using the alavetelitheme or adminbootstraptheme themes. * Check out this version and run `rails-post-deploy` as usual. - + # Version 0.6.4 ## Highlighted features -* This is a minor bugfix release, mainly to fix bugs related to external request handling. +* This is a minor bugfix release, mainly to fix bugs related to external request handling. * [List of issues on github](https://github.com/mysociety/alaveteli/issues?milestone=18&state=closed) * [List of commits since last release](https://github.com/mysociety/alaveteli/compare/master...release/0.6.4) @@ -152,7 +184,7 @@ * Support for invalidating accelerator cache -- this makes it much less likely, when using Varnish, that users will be presented with stale content. Fixes - + * 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 @@ -184,7 +216,7 @@ 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. @@ -217,7 +249,7 @@ `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`. - + * If you want to try out the new administrator theme, copy the sample `THEME_URLS` config from `general.yml-example` and run `./script/rails-post-deploy`. If you don't like it, turn it off @@ -225,7 +257,7 @@ (`adminbootstraptheme`) -- but email the mailing list first, explaining why! The intention is to merge this theme into the Alaveteli core in a future release. - + * If you are already using Google Analytics, you are probably including the tracking code manually in your theme. If you'd like to use Alaveteli's support for Google Analytics, set the `GA_CODE` @@ -254,7 +286,7 @@ in 0.5, which was causing deployment problems: production environments * It should now be safe to run `rake spec` on a production server -There is one minor new feature in this release: +There is one minor new feature in this release: * Administrators can follow the auto-login URLs forwarded in emails from users who want support, and they will remain logged in as @@ -275,9 +307,9 @@ As usual, there is a [full list of changes on github](https://github.com/mysocie # Version 0.5 ## Highlighted features -* It should now be possible to develop the software on OSX +* It should now be possible to develop the software on OSX * Base design refactored: CSS simplified and reduced, base design colours removed, now provided in example Alaveteli theme override -* It is now possible to rebuild the xapian index for specific terms, rather than having to drop and rebuild the entire database every time (as previously). See rake xapian:rebuild_index for more info. +* It is now possible to rebuild the xapian index for specific terms, rather than having to drop and rebuild the entire database every time (as previously). See rake xapian:rebuild_index for more info. * When listing authorities, show all authorities in default locale, rather than only those in the currently selected locale. * Ensure incoming emails are only ever parsed once (should give a performance boost) * Added a simple rate-limiting feature: restrict the number of requests users can make per day, except if explicitly unrestricted in the admin interface diff --git a/doc/INSTALL.md b/doc/INSTALL.md index 3a911cbc8..2156f4c4a 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -14,7 +14,7 @@ with all these steps configured. It is *not* production-ready. To start with, you may need to install git, e.g. with `sudo apt-get install git-core` -Next, get hold of the Alaveteli source code from github: +Next, get hold of the Alaveteli source code from github: git clone https://github.com/mysociety/alaveteli.git cd alaveteli @@ -27,7 +27,7 @@ master branch (which always contains the latest stable release): # Package pinning -You need to configure [apt-pinning](http://wiki.debian.org/AptPreferences#Pinning-1) preferences in order to prevent packages being pulled from the debian testing distribution in preference to the stable distribution once you have added the testing repository as described below. +You need to configure [apt-pinning](http://wiki.debian.org/AptPreferences#Pinning-1) preferences in order to prevent packages being pulled from the debian testing distribution in preference to the stable distribution once you have added the testing repository as described below. In order to configure apt-pinning and to keep most packages coming from the Debian stable repository while installing the ones required from testing and the mySociety repository you need to run the following commands: @@ -36,7 +36,7 @@ In order to configure apt-pinning and to keep most packages coming from the Debi echo "Pin-Priority: 50" >> /tmp/preferences sudo cp /tmp/preferences /etc/apt/ rm /tmp/preferences - + # Install system dependencies These are packages that the software depends on: third-party software @@ -74,14 +74,14 @@ explanation): wget http://rubyforge.org/frs/download.php/74445/rubygems-1.6.2.tgz -O /tmp/rubygems-1.6.2.tgz tar zxvf /tmp/rubygems-1.6.2.tgz -C /tmp/ sudo ruby1.8 /tmp/rubygems-1.6.2/setup.rb - + To install Alaveteli's Ruby dependencies, we also need to install bundler. In Debian, this is provided as a package (installed as part of the package install process above). You could also install it as a gem: sudo gem1.8 install bundler - + # Install mySociety libraries You will also want to install mySociety's common ruby libraries and the Rails @@ -118,7 +118,7 @@ use the Debian package compiled by mySociety (see link in [issue 305](https://github.com/mysociety/alaveteli/issues/305)) -# 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 currently supported database is @@ -139,12 +139,12 @@ Make sure that the user specified in database.yml exists, and has full 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) - + You can create a `foi` user from the command line, thus: # su - postgres $ createuser -s -P foi - + And you can create a database thus: $ createdb -T template0 -E SQL_ASCII -O foi foi_production @@ -157,15 +157,15 @@ data that may not be valid UTF (for example, data originating from various broken email clients that's not 8-bit clean), it's safer to be able to store *anything*, than reject data at runtime. -# Configure email +# Configure email You will need to set up an email server (MTA) to send and receive emails. Full configuration for an MTA is beyond the scope of this document, though we describe an example configuration for Exim in `INSTALL-exim4.md`. -Note that in development mode, mail is handled by default by mailcatcher -so that you can see the mails in a browser - see http://mailcatcher.me/ +Note that in development mode, mail is handled by default by mailcatcher +so that you can see the mails in a browser - see http://mailcatcher.me/ for more details. ## Minimal @@ -230,7 +230,7 @@ for instructions on switching on local and remote performance analysis. In the 'alaveteli' directory, run: - ./script/rails-post-deploy + ./script/rails-post-deploy (This will need execute privs so `chmod 755` if necessary.) This sets up directory structures, creates logs, installs/updates themes, runs @@ -301,7 +301,7 @@ 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. +user. You can disable the emergency user account by setting `DISABLE_EMERGENCY_USER` to `true` in `general.yml`. Users with the superuser role also have extra privileges in the website frontend, such as being able to categorise any request, being @@ -328,7 +328,7 @@ like `!!(*= $this *)!!`. The variables are: port with a path to the directory where your Alaveteli software installation lives, e.g. `/var/www/` * `vhost_dir`: the entire path to the directory where the software is - served from. -- you should replace this with a path to the + served from. -- you should replace this with a path to the directory where your Alaveteli software installation lives, e.g. `/var/www/` * `vcspath`: the name of the alaveteli checkout, e.g. `alaveteli`. @@ -378,6 +378,34 @@ Under all but light loads, it is strongly recommended to run the server behind an http accelerator like Varnish. A sample varnish VCL is supplied in `../conf/varnish-alaveteli.vcl`. +It's strongly recommended that you run the site over SSL. (Set FORCE_SSL to true in +config/general.yml). For this you will need an SSL certificate for your domain and you will +need to configure an SSL terminator to sit in front of Varnish. If you're already using Apache +as a web server you could simply use Apache as the SSL terminator. A minimal configuration +would look something like this: + +<VirtualHost *:443> + ServerName www.yourdomain + + ProxyRequests Off + ProxyPreserveHost On + ProxyPass / http://localhost:80/ + ProxyPassReverse / http://localhost:80/ + RequestHeader set X-Forwarded-Proto 'https' + + SSLEngine on + SSLProtocol all -SSLv2 + SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:RC4+RSA:+HIGH:+MEDIUM + + SSLCertificateFile /etc/apache2/ssl/ssl.crt + SSLCertificateKeyFile /etc/apache2/ssl/ssl.key + SSLCertificateChainFile /etc/apache2/ssl/sub.class2.server.ca.pem + SSLCACertificateFile /etc/apache2/ssl/ca.pem + SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown +</VirtualHost> + +Notice the line "RequestHeader" that sets the X-Forwarded-Proto header. This is important. This ultimately tells Rails that it's serving a page over https and so it knows to include that in any absolute urls it serves. + Some [production server best practice notes](https://github.com/mysociety/alaveteli/wiki/Production-Server-Best-Practices) are evolving on the wiki. @@ -413,14 +441,14 @@ various other things that can be automated for deployment. # Troubleshooting * **Incoming emails aren't appearing in my Alaveteli install** - + First, you need to check that your MTA is delivering relevant incoming emails to the `script/mailin` command. There are various ways of setting your MTA up to do this; we have documented one way of doing it in Exim at `doc/INSTALL-exim4.conf`, including a command you can use to check that the email routing is set up correctly. - + Second, you need to test that the mailin script itself is working correctly, by running it from the command line, First, find a valid "To" address for a request in your system. You can do this @@ -431,7 +459,7 @@ various other things that can be automated for deployment. Loading development environment (Rails 2.3.14) >> InfoRequest.find_by_url_title("why_do_you_have_such_a_fancy_dog").incoming_email => "request-101-50929748@localhost" - + Now take the source of a valid email (there are some sample emails in `spec/fixtures/files/`); edit the `To:` header to match this address; and then pipe it through the mailin script. A non-zero exit code @@ -447,7 +475,7 @@ various other things that can be automated for deployment. `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/`. - + * **Various tests fail with "*Your PostgreSQL connection does not support unescape_bytea. Try upgrading to pg 0.9.0 or later.*"** @@ -470,17 +498,17 @@ various other things that can be automated for deployment. Normally, the encoding should just work, but under some circumstances it appears that `elinks` ignores the parameters passed to it from Alaveteli. - + To force `elinks` always to treat input as UTF8, add the following to `/etc/elinks/elinks.conf`: - + set document.codepage.assume = "utf-8" set document.codepage.force_assumed = 1 - You should also check that your locale is set up correctly. See + You should also check that your locale is set up correctly. See [https://github.com/mysociety/alaveteli/issues/128#issuecomment-1814845](this issue followup) for further discussion. - + * **I'm getting lots of `SourceIndex.new(hash) is deprecated` errors when running the tests** The latest versions of rubygems contain a large number of noisy @@ -488,7 +516,7 @@ various other things that can be automated for deployment. 2.x isn't under active development so isn't going to get fixed (in the sense of using a non-deprecated API). So the only vaguely sensible way to avoid this noisy output is to downgrade rubygems. - + For example, you might do this by uninstalling your system-packaged rubygems, and then installing the latest rubygems from source, and finally executing `sudo gem update --system diff --git a/doc/TRANSLATE.md b/doc/TRANSLATE.md index abf47add3..f8b4adbcb 100644 --- a/doc/TRANSLATE.md +++ b/doc/TRANSLATE.md @@ -39,6 +39,21 @@ The release manager will also give you a **translation deadline**. After this date, you can continue to contribute new translations, but they won't make it into the release. +## General notes on translation in Transifex + +Some bits of text will have comments attached to them from the Alaveteli +application developers about the context in which the text appears in the +application - these comments will appear under the 'Details' tab for the +text in Transifex. + +Some bits of text are in the form of two bits of text separated by a `|` +character e.g. `IncomingMessage|Subject`. These represent attribute names, so +`IncomingMessage|Subject` is the subject attribute of an incoming message on +the site. You should not prioritise these types of text when translating - +they do not appear on the site anywhere at the moment, and when they do, +they will only be used in the admin interface. If you do translate them, only +translate the text after the `|`. + # Translation process: release manager's view Before the Alaveteli release manager cuts a new release branch, they |