aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/customising/config.md10
-rw-r--r--docs/customising/index.md10
-rw-r--r--docs/customising/themes.md10
-rw-r--r--docs/customising/translation.md108
-rw-r--r--docs/developers/directory_structure.md6
-rw-r--r--docs/developers/i18n.md161
-rw-r--r--docs/developers/index.md17
-rw-r--r--docs/developers/overview.md2
-rw-r--r--docs/getting_started.md24
-rw-r--r--docs/glossary.md121
-rw-r--r--docs/index.md16
-rw-r--r--docs/installing/ami.md8
-rw-r--r--docs/installing/deploy.md2
-rw-r--r--docs/installing/index.md10
-rw-r--r--docs/installing/macos.md36
-rw-r--r--docs/installing/manual_install.md51
-rw-r--r--docs/installing/script.md2
-rw-r--r--docs/running/admin_manual.md8
-rw-r--r--docs/running/index.md6
-rw-r--r--docs/running/server.md15
-rw-r--r--docs/running/states.md6
-rw-r--r--docs/running/states_informatazyrtare.md4
-rw-r--r--docs/running/upgrading.md54
23 files changed, 507 insertions, 180 deletions
diff --git a/docs/customising/config.md b/docs/customising/config.md
index 2528adefc..8a25e8df6 100644
--- a/docs/customising/config.md
+++ b/docs/customising/config.md
@@ -14,7 +14,7 @@ title: Configuration
The alaveteli code ships with an example configuration file: `config/general.yml-example`.
-As part of the [installation process]({{ site.baseurl }}docs/installing ), the
+As part of the [installation process]({{ site.baseurl }}docs/installing/ ), the
example file gets copied to `config/general.yml`. You **must** edit this file to
suit your needs.
@@ -230,7 +230,7 @@ indentation correct. If in doubt, look at the examples already in the file, and
<p>Example:</p>
<ul class="examples">
<li>
- <code>BLOG_FEED: 'http://www.mysociety.org/category/projects/whatdotheyknow/feed/'</code>
+ <code>BLOG_FEED: 'https://www.mysociety.org/category/projects/whatdotheyknow/feed/'</code>
</li>
</ul>
</div>
@@ -372,7 +372,7 @@ indentation correct. If in doubt, look at the examples already in the file, and
<a name="theme_urls"><code>THEME_URLS</code></a>
</dt>
<dd>
- URLs of <a href="{{ site.baseurl }}docs/customising/themes">themes</a> to download and use
+ URLs of <a href="{{ site.baseurl }}docs/customising/themes/">themes</a> to download and use
(when running the <code>rails-post-deploy</code> script). The earlier in the list means
the templates have a higher priority.
<div class="more-info">
@@ -392,7 +392,7 @@ THEME_URLS:
<a name="theme_branch"><code>THEME_BRANCH</code></a>
</dt>
<dd>
- When <code>rails-post-deploy</code> installs the <a href="{{ site.baseurl }}docs/customising/themes">themes</a>,
+ When <code>rails-post-deploy</code> installs the <a href="{{ site.baseurl }}docs/customising/themes/">themes</a>,
it will try the theme branch first, but only if you've set <code>THEME_BRANCH</code>
to be true. If the branch doesn't exist it will fall back to using a tagged version
specific to your installed alaveteli version, and if that doesn't exist it will
@@ -951,7 +951,7 @@ EXCEPTION_NOTIFICATIONS_TO:
<p>Example:</p>
<ul class="examples">
<li>
- <code>DONATION_URL: "http://www.mysociety.org/donate/"</code>
+ <code>DONATION_URL: "https://www.mysociety.org/donate/"</code>
</li>
</ul>
</div>
diff --git a/docs/customising/index.md b/docs/customising/index.md
index 4b8cf9fda..19100ad20 100644
--- a/docs/customising/index.md
+++ b/docs/customising/index.md
@@ -15,7 +15,7 @@ title: Customising
## Configuration settings
You can customise much of Alaveteli's behaviour just by editing the configuration
-file. This [complete list of Alaveteli's config settings]({{ site.baseurl }}docs/customising/config)
+file. This [complete list of Alaveteli's config settings]({{ site.baseurl }}docs/customising/config/)
shows the sort of things you can control in this way.
<!-- TODO key settings -->
@@ -24,7 +24,7 @@ shows the sort of things you can control in this way.
It's common to want to change the basic appearance of the site. Although you
can simply edit the default templates and CSS to do this, we **strongly
-recommend** that you [create a theme]({{ site.baseurl }}docs/customising/themes).
+recommend** that you [create a theme]({{ site.baseurl }}docs/customising/themes/).
Themes do not need to be especially complex, but they allow your changes to
work alongside the core code, which you can then update (when new releases or
@@ -32,13 +32,13 @@ updates become available).
## Need Alaveteli in a different language?
-No problem! See the [information about translating Alaveteli]({{ site.baseurl }}docs/customising/translation).
+No problem! See the [information about translating Alaveteli]({{ site.baseurl }}docs/customising/translation/).
## Complex changes
If you are a developer (or you have a team of programmers available) you can
add any customisation that you want. But it's important to do this without
breaking the core code, so that you can accept new releases with updates.
-There's more detail in the [page about themes]({{ site.baseurl }}docs/customising/themes).
+There's more detail in the [page about themes]({{ site.baseurl }}docs/customising/themes/).
-See also the [documentation for developers]({{ site.baseurl }}docs/developers).
+See also the [documentation for developers]({{ site.baseurl }}docs/developers/).
diff --git a/docs/customising/themes.md b/docs/customising/themes.md
index 65410ece2..bad1639d7 100644
--- a/docs/customising/themes.md
+++ b/docs/customising/themes.md
@@ -13,13 +13,13 @@ title: Themes
</p>
When you customise your Alaveteli site, there is a lot you can change just
-by editing the [config settings]({{ site.baseurl }}docs/customising/config).
+by editing the [config settings]({{ site.baseurl }}docs/customising/config/).
But if you want to change the way the site looks, or add more specific
behaviour, you'll need to make a **theme**.
You don't need to be a programmer in order to make simple changes, but you will
need to be confident enough to copy and change some files. If you're not sure
-about this, [ask for help](/community)!
+about this, [ask for help](/community/)!
## What you might want to change
@@ -28,7 +28,7 @@ The most common requirement is to brand the site: at a minimum,
the different states that a request can go through. You'll also want
to edit the categories that public bodies can appear in (i.e. the
groupings on the left hand side of the
-"[View authorities](http://www.whatdotheyknow.com/body/list/all)" page
+"[View authorities](https://www.whatdotheyknow.com/body/list/all)" page
on WhatDoTheyKnow.
There may also be other things you want to customise -- drop a line on
@@ -49,7 +49,7 @@ code.
We try to encapsulate all site-specific functionality in one of these
places:
-* Site [configuration]({{ site.baseurl }}docs/customising/config)
+* Site [configuration]({{ site.baseurl }}docs/customising/config/)
(e.g., the name of your site, the available
languages, and so on &mdash; all in `config/general.yml`)
* Data (e.g. the public bodies to whom requests should be addressed)
@@ -137,7 +137,7 @@ locale you support.
## Customising the request states
As mentioned above, if you can possibly live with the
-[default Alaveteli request statuses]({{ site.baseurl }}docs/running/states),
+[default Alaveteli request statuses]({{ site.baseurl }}docs/running/states/),
it would be good to do so. Note that you can set how many days counts
as "overdue" in the main site config file &mdash;
see [`REPLY_LATE_AFTER_DAYS`]({{ site.baseurl }}docs/customising/config/#reply_late_after_days).
diff --git a/docs/customising/translation.md b/docs/customising/translation.md
index 4f3c39270..d4ccedfa7 100644
--- a/docs/customising/translation.md
+++ b/docs/customising/translation.md
@@ -12,39 +12,85 @@ title: Translation
it. This page explains how.
</p>
+## Alaveteli already contains translations!
+
+Alaveteli ships ready to run in a number of different languages.
+If Alaveteli has already been translated into the language (or languages) you
+need, you just need to configure it -- see
+[`AVAILABLE_LOCALES`]({{ site.baseurl }}docs/customising/config/#available_locales).
+
+[Look in the `locale/` directory](https://github.com/mysociety/alaveteli/tree/master/locale)
+to see what translations are already available. Some are complete
+translations of the site. Others are only partial -- either because the translations
+have not been finished yet, or else because the translators have not updated the
+texts since developers changed or added text on the site.
+
+There are two reasons the translations may need more work before you can use them:
+
+* **the language you want is not one of those we already have** <br> In this
+ case, there will be no entry in ``locale/`` for it, because nobody has yet
+ translated Alaveteli into your language. See the rest of this page to learn
+ how to add a new translation.
+
+* **the translation for your language is incomplete, or lagging behind** <br>
+ This might simply be because it is a work in progress. Furthermore, sometimes
+ an incomplete translation already covers all the areas of the site you need
+ anyway. Of course, you can add to a partial translation, but it's a good idea
+ to check with us first, since we'll probably know who is working on the
+ current translation and what state it's in.
+
+Translators are members of the Alaveteli
+[community]({{site.baseurl}}community/), and often work separately from the
+developers. This means translations can lag a little behind the code. However,
+our release process includes a "translation freeze", which gives the
+translators a chance to catch up -- read the rest of this page for details.
+
## Alaveteli's translations
-The software translations are implemented using GNU gettext, and the resource
-files are managed in Transifex.
+You don't need to be a programmer to translate Alaveteli -- we use an external
+website called Transifex to help manage translations. This makes it easy for
+translators to get to work, but it does mean you (or your technical team)
+need to do a little extra work to get those translations back into Alaveteli
+when they are ready.
The Transifex project is at
-[https://www.transifex.net/projects/p/alaveteli](https://www.transifex.net/proje
-cts/p/alaveteli) -- you'll probably want an account there (ask on the mailing
-list). It has a fairly easy-to-use interface for contributing translations.
+[https://www.transifex.net/projects/p/alaveteli](https://www.transifex.net/projects/p/alaveteli)
+-- you'll probably want an account there (ask on the mailing list). It has a
+fairly easy-to-use interface for contributing translations.
+
+Alaveteli localises strings using GNU gettext and
+<a href="{{site.baseurl}}docs/glossary/#po" class="glossary__link"><code>.pot</code> &amp; <code>.po</code> files</a>.
+If you're a developer, you should read
+[internationalising Alaveteli]({{ site.baseurl }}docs/developers/i18n/).
-There are three roles in the translation process, and each one is described
-below: **translator**, **developer**, and **release manager**. You probably only
-need to know about the one that applies to you.
-## Translation process: translator's view
+## What a translator needs to do
**If you're just working on translating Alaveteli into a language you know, then
this section is for you.**
+> Remember that Alaveteli
+> [already comes with some translations](#alaveteli-already-contains-translations),
+> so check first that you really need to do this. Maybe someone has already
+> translated Alaveteli into the language you need!
+
When a developer adds a new feature to the user interface in Alaveteli, they
use some code to mark sentences or words ("strings") that they think will need
to be translated.
-When the Alaveteli release manager is planning a release, they will upload a
-template containing all the strings to be translated (called a POT) to
-Transifex. This causes your own translations in Transifex to be updated with
+When the Alaveteli
+<a href="{{site.baseurl}}docs/glossary/#release" class="glossary__link">release manager</a>
+is planning a release, they will upload a
+template containing all the strings to be translated (called a
+<a href="{{site.baseurl}}docs/glossary/#po" class="glossary__link"><code>.pot</code> file</a>)
+to Transifex. This causes your own translations in Transifex to be updated with
the latest strings.
When you visit Transifex, it will prompt you to fill out values for all new
strings, and all strings that have been modified. In the case where a string
has only been slightly modified, such as with punctuation ("Hello" has become
"Hello!"), Transifex will suggest a suitable translation for you (look for the
-"suggestions" tab under the source string).
+*Suggestions* tab under the source string).
In order for this feature to work properly, the release manager has to download
your translations, run a program that inserts the suggestions, and then upload
@@ -60,11 +106,12 @@ 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 strings 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
+application — these comments will appear under the *Details* tab for the text
in Transifex.
Some strings will have **placeholders** in them to indicate that Alaveteli
@@ -105,19 +152,24 @@ 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 that comes *after* the `|`.
-## Translation process: developers' view
-**If you're writing new code for Alaveteli, then you're a developer, and you
+## How the translations get into Alaveteli
+
+In order to get the translated strings from Transifex into Alaveteli, follow
+the instructions in these [deployment notes]({{ site.baseurl }}docs/developers/i18n/#deployment-notes).
+This will be the job of the technical people on your team (or
+even mySociety's release manager). If translators aren't technical, they can
+use Transifex without needing to worry about this.
+
+
+## Developers and internationalisation
+
+If you're writing new code for Alaveteli, then you're a developer, and you
need to understand how to make any text you add easy for translators to work
-with.**
-
-Please read our [internationalisation
-guide](http://mysociety.github.io/internationalization.html) for our advice on
-using strings that will need translation. This applies across all mySociety
-projects, not just Alaveteli.
-
-The release manager will enforce a translation freeze just before a new release
-is cut. During such time, you must not introduce new strings to the code if
-your work is due for inclusion in this release. This is necessary to allow
-translators time to complete and check their translations against all the known
-strings.
+with -- see the page about
+[internationalising Alaveteli]({{site.baseurl}}docs/developers/i18n/).
+
+If you are a developer or translator actively working on internationalising
+Alaveteli code, you should talk to us to find out when the next release is due,
+so your translations can be prepared in time to be included in it.
+
diff --git a/docs/developers/directory_structure.md b/docs/developers/directory_structure.md
index e073a96ce..9dbe06789 100644
--- a/docs/developers/directory_structure.md
+++ b/docs/developers/directory_structure.md
@@ -13,7 +13,7 @@ directories.</p>
Alaveteli -- this is really more useful if you're a developer planning on
making more substantive changes to the code. You don't need to be familiar with
Ruby to install or make basic [customisations to your
-installation](/docs/customising).
+installation](/docs/customising/).
<!-- (and if you do,
remember to read the page about [feeding your changes back](/feeding-back)).-->
@@ -140,7 +140,7 @@ website](http://guides.rubyonrails.org/getting_started.html).
<p><em>documentation</em></p>
<p>
These are technical notes. This is in addition to the <a
- href="http://code.fixmystreet.com">core documentation</a> &mdash; which
+ href="http://code.alaveteli.org/docs/">core documentation</a> &mdash; which
you are reading now &mdash; which is actually stored in the git
repository in the <code>gh-pages</code> branch, and published as GitHub
pages.
@@ -215,7 +215,7 @@ website](http://guides.rubyonrails.org/getting_started.html).
<dd>
<p><em>tests</em></p>
<p>
- Alaveteli's test suite runs under <a href="TODO">spec</a>.
+ Alaveteli's test suite runs under <a href="http://rspec.info/">rspec</a>.
</p>
</dd>
<dt>
diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md
new file mode 100644
index 000000000..deabc99a1
--- /dev/null
+++ b/docs/developers/i18n.md
@@ -0,0 +1,161 @@
+---
+layout: page
+title: Internationalisation (for devs)
+---
+
+# Internationalisation in the code
+
+<p class="lead">
+ This page describes some technical aspects of internationalising the
+ Alaveteli code. It's mostly aimed at devs who are working on the
+ codebase &mdash; if you just want to translate Alaveteli into your
+ own language, see
+ <a href="{{ site.baseurl }}docs/customising/translation">translating Alaveteli</a>
+ instead.
+</p>
+
+## Deployment notes
+
+Deployed translations for the project live in ``locale/``.
+
+We encourage translations to be done on
+[Transifex](https://www.transifex.net/projects/p/alaveteli/)
+because translators can work through its web interface rather than needing to edit the
+<a href="{{ site.baseurl }}docs/glossary/#po" class="glossary__link">`.po` and `.pot` files</a>
+directly. Ultimately, Transifex just captures translators'
+work and turns it into the files that Alaveteli needs (using gettext).
+
+### How to get the latest translations onto your site
+
+For example, to deploy English and Spanish translations at once:
+
+ * Ensure their `.po` files are at ```locale/en/app.po``` and ```locale/es/app.po```
+ (for example, by downloading them from Transifex)
+ * Set <code><a href="{{ site.baseurl }}docs/customising/config/#available_locales">AVAILABLE_LOCALES</a></code>
+ to <code>en&nbsp;es</code>
+
+### How to add new strings to the translations
+
+You need to do this if you've added any new strings to the code that need
+translations (or if you change an existing one).
+
+To update the
+<a href="{{ site.baseurl }}docs/glossary/#po" class="glossary__link">`.po` or `.pot` files</a>
+for each language, run:
+
+ bundle exec rake gettext:store_model_attributes
+
+followed by:
+
+ bundle exec rake gettext:find
+
+If `gettext:find` only creates the file `locale/im-config.pot` then you need to
+unset the `TEXTDOMAIN` environment variable and try again.
+
+For more details about the translations, see the page about
+[translating Alaveteli]({{ site.baseurl }}docs/customising/translation/).
+
+
+## Technical implementation details
+
+### Getting the current locale
+
+This is complicated by the fact that there are two competing ways to define a
+locale+territory combination. The POSIX (and gettext and Transifex) way is
+like `en_GB`; the Rails way is like `en-US`. Because we are using gettext and
+Transifex for translations, we must deal with both.
+
+ * for the Rails version of the currently selected locale, use `I18n.locale`
+ * for the POSIX version of the locale, use `FastGettext.locale`
+
+## I18n in templates
+
+Before you add i18n strings to the source, you should read
+[internationalisation guidelines](http://mysociety.github.io/internationalization.html)
+that apply to all our projects.
+
+Some hints for adding the strings into the Alaveteli code:
+
+* Simple strings: ```<% = _("String to translate") %>```
+* Strings that include variables: give the translator a hand by inserting
+ strings that can be interpolated, so the variable has meaning. For example,
+ ```<%= "Nothing found for '" + h(@query) + "'" %>``` might become ```<%=
+ _("Nothing found for '{{search_terms}}'", :search_terms => h(@query)) %>```
+* Strings containing numbers: ```<%= n_('%d request', '%d requests', @quantity) % @quantity %>```
+* We allow some inline HTML where it helps with meaningful context, for example:
+
+```
+_('<a href="{{browse_url}}">Browse all</a> or <a href="{{add_url}}">ask us to add it</a>.',
+ :browse_url => @browse_url, :add_url => @add_url)
+```
+
+Similar rules can apply to strings in the Ruby source code.
+
+## Programmatic access of translated PublicBodies
+
+Apart from the templates, the only other area of i18n currently implemented is
+in the PublicBodies.
+
+The implementation allows for getting different locales of a PublicBody like so:
+
+```ruby
+ PublicBody.with_locale("es") do
+ puts PublicBody.find(230).name
+ end
+```
+
+Usually, that's all the code you need to know about. There's a method
+```self.locale_from_params()``` available on all models which returns a locale
+specified as ```locale=xx``` in the query string, and which falls back to the
+default locale, that you can use in conjunction with the ```with_locale```
+method above. All the joining on internal translation tables should usually be
+handled automagically -- but there are some exceptions, that follow below.
+
+### Overriding model field setters
+
+Internally, we use the [Globalize plugin](https://github.com/globalize/globalize)
+to localize model fields. Where column "foo" has been marked in the model as
+```:translates```, globalize overrides ```foo.baz = 12``` to actually set the
+value in column ```baz``` of table ```foo_translations```.
+
+A side effect of the way it does this is that if you wish to override a
+specific attribute setter, you will need to explicitly call the Globalize
+machinery; something like:
+
+```ruby
+ def name=(name)
+ globalize.write(self.class.locale || I18n.locale, "name", name)
+ self["name"] = short_name
+ # your other stuff here
+ end
+```
+
+### Searching
+
+The ```find_first_by_<attr>``` and ```find_all_by_<attr>``` magic methods
+should work. If you want to do a more programmatic search, you will need to
+join on the translation table. For example:
+
+```ruby
+ query = "#{translated_attr_name(someattr) = ? AND #{translated_attr_name('locale')} IN (?)"
+ locales = Globalize.fallbacks(locale || I18n.locale).map(&:to_s)
+ find(
+ :first,
+ :joins => :translations,
+ :conditions => [query, value, locales],
+ :readonly => false
+ )
+```
+
+You may also need to do some lower-level SQL joins or conditions. See
+```PublicBodyController.list``` for an example of a query that has a condition
+that is explicitly locale-aware (look for the ```locale_condition``` variable)
+
+## Translation and releases
+
+The release manager will enforce a translation freeze just before a new release
+is cut. During such time, you must not introduce new strings to the code if
+your work is due for inclusion in this release. This is necessary to allow
+translators time to complete and check their translations against all the known
+strings. See more about [translating Alaveteli]({{ site.baseurl }}docs/customising/translation/).
+
diff --git a/docs/developers/index.md b/docs/developers/index.md
index f98261a77..22390f236 100644
--- a/docs/developers/index.md
+++ b/docs/developers/index.md
@@ -12,14 +12,14 @@ title: For developers
* The software is written in **Ruby on Rails 3.x**. We support postgresql as
the backend database. A configured mail transfer agent (MTA) like exim,
postfix or sendmail is necessary to parse incoming emails. We have production
- sites deployed on Debian (Squeeze and Wheezy) and Ubuntu (10.04 and 12.04 LTS). For performance
+ sites deployed on Debian (Squeeze and Wheezy) and Ubuntu (12.04 LTS). For performance
reasons, we recommend the use of [Varnish](https://www.varnish-cache.org).
* To help you understand what the code is doing, read this [high-level
- overview]({{ site.baseurl }}docs/developers/overview), which includes a diagram of
+ overview]({{ site.baseurl }}docs/developers/overview/), which includes a diagram of
the models and how they are related.
-* See the [API documentation]({{ site.baseurl }}docs/developers/api) for how to get
+* See the [API documentation]({{ site.baseurl }}docs/developers/api/) for how to get
data into or out of Alaveteli.
* If you need to change or add strings in the interface, see our [guidelines
@@ -49,14 +49,14 @@ title: For developers
for help.
* A standard initial step for customising your deployment is [writing a
- theme]({{ site.baseurl }}docs/customising/themes). **If you only read one thing,
+ theme]({{ site.baseurl }}docs/customising/themes/). **If you only read one thing,
it should be this!**
* Like many Ruby on Rails sites, the software is not hugely performant (see
- some notes about [[performance issues]] gathered over time with
+ [these notes about performance issues](https://github.com/mysociety/alaveteli/wiki/Performance-issues) gathered over time with
WhatDoTheyKnow). The site will run on a server with 512MB RAM but at least
2GB is recommended. Deployment behind [Varnish](https://www.varnish-cache.org) is also fairly essential. See
- [[Production Server Best Practices]] for more.
+ [production server best practices]({{site.baseurl}}docs/running/server/) for more.
* There's a number of [proposals for enhancements](https://github.com/mysociety/alaveteli/wiki/Proposals-for-enhancements),
such as more user-focused features, but see also...
@@ -74,10 +74,9 @@ title: For developers
* If you're experiencing memory issues, [this blog post about some strategies
used in the
- past](http://www.mysociety.org/2009/09/17/whatdotheyknow-growing-pains-and-rub
- y-memory-leaks/) might be useful.
+ past](https://www.mysociety.org/2009/09/17/whatdotheyknow-growing-pains-and-ruby-memory-leaks/) might be useful.
-* If you're coding on a mac, see these [MacOS X installation notes]({{ site.baseurl }}docs/installing/macos). <!-- [[OS X Quickstart]] -->
+* If you're coding on a mac, see these [MacOS X installation notes]({{ site.baseurl }}docs/installing/macos/). <!-- [[OS X Quickstart]] -->
* We try to adhere to similar good practice across all our projects: see
[mysociety.github.io](http://mysociety.github.io/) for things like our
diff --git a/docs/developers/overview.md b/docs/developers/overview.md
index ca2d27985..af312f997 100644
--- a/docs/developers/overview.md
+++ b/docs/developers/overview.md
@@ -43,7 +43,7 @@ ensure they have an envelope-from header set (to combat spam).
## Schema diagram
-<a name="schema-diagram" href="{{ site.baseurl }}images/railsmodels.png"><img src="{{ site.baseurl }}images/railsmodels.png"></a>
+<a href="{{ site.baseurl }}assets/img/railsmodels.png"><img src="{{ site.baseurl }}assets/img/railsmodels.png"></a>
This schema for the Rails models was generated from the code on 19 Dec 2012 using
[Railroad](http://railroad.rubyforge.org/).
diff --git a/docs/getting_started.md b/docs/getting_started.md
index c51847b69..5c5a7437d 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -1,6 +1,7 @@
---
layout: page
title: Getting started
+redirect_from: /getting_started/
---
# Getting started with Alaveteli
@@ -12,8 +13,8 @@ title: Getting started
For inspiration, take a look at some of the existing Alaveteli websites, like
[tuderechoasaber.es](http://tuderechoasaber.es) (Spain),
-[AskTheEU](http://asktheeu.org) (EU), or
-[WhatDoTheyKnow](http://www.whatdotheyknow.com) (UK). These sites all use the
+[AskTheEU](http://www.asktheeu.org) (EU), or
+[WhatDoTheyKnow](https://www.whatdotheyknow.com) (UK). These sites all use the
Alaveteli software, plus their own custom themes installed on top to make them
look different.
@@ -28,7 +29,7 @@ available time.
You can get a feeling for how things might turn out by reading [how an
Alaveteli was set up in
-Spain](http://www.alaveteli.org/2012/04/a-right-to-know-site-for-spain/)
+Spain]({{ site.baseurl }}2012/04/16/a-right-to-know-site-for-spain/)
(remember that this was with an experienced developer in charge). You will also
need to think about how you will run the website; a successful Alaveteli
requires lots of ongoing effort to moderate and publicise (see Step 6 and Step
@@ -68,7 +69,7 @@ Alaveteli.
>
> -- _Pedro Markun, Queremos Saber_
-[AskTheEU](http://asktheeu.org), a much more complete and polished version with
+[AskTheEU](http://www.asktheeu.org), a much more complete and polished version with
a custom theme and several other customisations, took a team of 2 or 3 people
about 3 months (part time) to complete.
@@ -98,7 +99,7 @@ third parties, and to do so we're happy to help host low-volume sites for two
or three partners. However, you will have no service level agreement, no
warranties, and no guarantee on our time: if the website goes down when we're
on holiday, you'll have to wait until we're back! If you want to try this
-route, please [get in touch](http://alaveteli.org/contact-us) to find out if
+route, please [get in touch](mailto:international@mysociety.org) to find out if
we have capacity.
### Install your own copy
@@ -112,11 +113,11 @@ with this. The minimum spec for running a low traffic website is 512MB RAM and
a 20GB disk. 2GB RAM would be ideal. We recommend Debian Squeeze 64-bit as the
operating system, though any sort of Linux should do. Rackspace offer suitable
cloud servers, which start out at around $25 / month. Then your tech person
-should follow the [installation documentation]({{ site.baseurl }}docs/installing).
+should follow the [installation documentation]({{ site.baseurl }}docs/installing/).
Alternatively, you could use Amazon Web Services. This has the
added advantage that you can use our preconfigured [Alaveteli EC2
-AMI]({{ site.baseurl }}docs/installing/ami) to get you
+AMI]({{ site.baseurl }}docs/installing/ami/) to get you
started almost instantly. However, it's more expensive than Rackspace,
especially if you want more RAM.
@@ -156,7 +157,7 @@ If you email possible supporters asking for help, in addition to helping make
your job easier, it will also help you identify eager people who might be
interested in helping you maintain and run the website. We have written [a
blog post about
-this](http://www.alaveteli.org/2011/07/you-need-volunteers-to-make-your-website-work/).
+this]({{ site.baseurl }}2011/07/29/you-need-volunteers-to-make-your-website-work/).
The admin interface includes a page where you can upload a CSV file (that's a
file containing comma-separated values) to create or edit authorities. CSV is a
@@ -310,7 +311,7 @@ review the untranslated strings.
## Step five: Test drive the site
For launch, the tech person should review the [Production Server Best
-Practices]({{ site.baseurl }}docs/running/server).
+Practices]({{ site.baseurl }}docs/running/server/).
A low-key launch, where you tell just a few trusted people about the site, is a
very good idea. You can then track how things work, and gauge the responses of
@@ -345,8 +346,7 @@ This will be easier to do with a small team of people sharing jobs. Hopefully
you have been lucky enough to get funding to pay people to do these tasks.
However, you are also likely to have to rely on volunteers. We've written [a
blog post about the importance of
-volunteers](http://www.alaveteli.org/2011/07/you-need-volunteers-to-make-your-we
-bsite-work/), which you should read.
+volunteers]({{ site.baseurl }}2011/07/29/you-need-volunteers-to-make-your-website-work/), which you should read.
You'll need to set up a group email address for all the people who will manage
the website. All site user queries will go here, as will automatic
@@ -370,7 +370,7 @@ website is. To ensure its success, you should be doing things like:
* Recruiting volunteers to help with the site
* Categorising uncategorised requests
-See also the [Administrator's Manual](/docs/running/admin_manual), which describes
+See also the [Administrator's Manual](/docs/running/admin_manual/), which describes
some of the typical tasks you'll need to perform when your site is up and
running.
diff --git a/docs/glossary.md b/docs/glossary.md
index 29f307ca6..d35454cbf 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -27,12 +27,14 @@ Definitions
<li><a href="#holding_pen">holding pen</a></li>
<li><a href="#newrelic">New Relic</a></li>
<li><a href="#mta">MTA</a></li>
+ <li><a href="#po">.po files</a></li>
<li><a href="#production">production site</a></li>
<li><a href="#publish">publish</a></li>
<li><a href="#recaptcha">recaptcha</a></li>
<li><a href="#redact">redacting</a></li>
<li><a href="#regexp">regular expression</a></li>
<li><a href="#request">request</a></li>
+ <li><a href="#release">release</a></li>
<li><a href="#response">response</a></li>
<li><a href="#rails">Ruby&nbsp;on&nbsp;Rails</a></li>
<li><a href="#sass">Sass</a></li>
@@ -49,11 +51,11 @@ Definitions
</dt>
<dd>
<strong>Alaveteli</strong> is the name of the open source software platform created
- by <a href="http://www.mysociety.org">mySociety</a> for submitting,
+ by <a href="https://www.mysociety.org">mySociety</a> for submitting,
managing and archiving Freedom of Information requests.
<p>
It grew from the successful FOI UK project
- <a href="http://www.whatdotheyknow.com">WhatDoTheyKnow</a>.
+ <a href="https://www.whatdotheyknow.com">WhatDoTheyKnow</a>.
We use the name <em>Alaveteli</em> to distinguish the software
that runs the platform from any specific website that it is powering.
</p>
@@ -154,7 +156,7 @@ Definitions
<p>More information:</p>
<ul>
<li>
- how to <a href="{{ site.baseurl }}docs/installing/deploy">deploy Alaveteli</a> (and why it's
+ how to <a href="{{ site.baseurl }}docs/installing/deploy/">deploy Alaveteli</a> (and why it's
a good idea)
</li>
<li>
@@ -184,7 +186,7 @@ Definitions
<li>
censor rules may simply redact text that exactly matches a
particular sentence or phrase, or may use
- <a href="regexp">regular expressions</a>
+ <a href="#regexp">regular expressions</a>
</li>
</ul>
</div>
@@ -224,7 +226,7 @@ Definitions
<p>More information:</p>
<ul>
<li>
- Wikipedia summary of <a href="http://http://en.wikipedia.org/wiki/Freedom_of_information_laws_by_country">FOI laws by country</a>.
+ Wikipedia summary of <a href="http://en.wikipedia.org/wiki/Freedom_of_information_laws_by_country">FOI laws by country</a>.
</li>
</ul>
</div>
@@ -238,7 +240,7 @@ Definitions
helps us track changes to the code, and also makes it easy for other people
to duplicate and even contribute to our software.
<p>
- The website <a href="http://github.com/mysociety">github.com</a> is a central, public
+ The website <a href="https://github.com/mysociety">github.com</a> is a central, public
place where we make our software available. Because it's Open Source, you can
inspect the code there (Alaveteli is mostly written in the programming language
Ruby), report bugs, suggest features and many other useful things.
@@ -253,15 +255,15 @@ Definitions
<p>More information:</p>
<ul>
<li>
- See the <a href="{{ site.baseurl }}docs/installing">installation instructions</a> which will
+ See the <a href="{{ site.baseurl }}docs/installing/">installation instructions</a> which will
clone the Alaveteli repo.
</li>
<li>
Everything about git from the <a
- href="//http://git-scm.com">official website</a>.
+ href="http://git-scm.com">official website</a>.
</li>
<li>
- See <a href="http://github.com/mysociety">the mySociety projects on
+ See <a href="https://github.com/mysociety">the mySociety projects on
github</a>.
</li>
</ul>
@@ -269,7 +271,7 @@ Definitions
</dd>
<dt>
- <a name="holding pen">holding pen</a>
+ <a name="holding_pen">holding pen</a>
</dt>
<dd>
The <strong>holding pen</strong> is the conceptual place where responses that
@@ -278,7 +280,7 @@ Definitions
<p>More information:</p>
<ul>
<li>
- see the <a href="{{ site.baseurl }}docs/running/admin_manual">admin manual</a> for
+ see the <a href="{{ site.baseurl }}docs/running/admin_manual/">admin manual</a> for
information on dealing with emails in the holding pen
</li>
</ul>
@@ -297,7 +299,7 @@ Definitions
<p>More information:</p>
<ul>
<li>
- see these instructions for <a href="{{ site.baseurl }}docs/installing/email">configuring your MTA</a>
+ see these instructions for <a href="{{ site.baseurl }}docs/installing/email/">configuring your MTA</a>
(examples are for exim4 and postfix, two of the most common)
</li>
</ul>
@@ -318,7 +320,7 @@ Definitions
<li>
use the <code>agent_enabled:</code> setting in the
the <code>newrelic.yml</code> config file to enable the New Relic analytics.
- See the <a href="{{ site.baseurl }}docs/installing/manual_install">manual installation</a> instructions.
+ See the <a href="{{ site.baseurl }}docs/installing/manual_install/">manual installation</a> instructions.
</li>
<li>
see also the New Relic Ruby Agent <a href="https://github.com/newrelic/rpm">github repo</a> and
@@ -333,6 +335,36 @@ Definitions
</dd>
<dt>
+ <a name="po"><code>.po</code> file</a> (and <code>.pot</code> file)
+ </dt>
+ <dd>
+ These are the files needed by the gettext mechanism Alaveteli uses for
+ localisation. A <code>.pot</code> file is effectively a list of all the
+ strings in the application that need translating. Each <code>.po</code>
+ file contains the mapping between those strings, used as keys, and their
+ translations for one particular language. The key is called the
+ <em>msgid</em>, and its corresponding translation is the <em>msgstr</em>.
+ <div class="more-info">
+ <p>More information:</p>
+ <ul>
+ <li>
+ See <a href="{{ site.baseurl }}docs/customising/translation/">translating
+ Alaveteli</a> for an overview from a translator's point of view.
+ </li>
+ <li>
+ See <a href="{{ site.baseurl }}docs/developers/i18n/">Internationalising
+ Alaveteli</a> for more technical details.
+ </li>
+ <li>
+ Alaveteli is on the <a href="https://www.transifex.net/projects/p/alaveteli/">Transifex</a>
+ website, which lets translators work on Alaveteli in a browser, without needing
+ to worry about this underlying structure.
+ </li>
+ </ul>
+ </div>
+ </dd>
+
+ <dt>
<a name="production">production site</a> (also: live, production server)
</dt>
<dd>
@@ -378,15 +410,6 @@ Definitions
</dd>
<dt>
- <a name="response">response</a>
- </dt>
- <dd>
- A <strong>response</strong> is the email sent by an
- <a href="#authority" class="glossary">authority</a> in reply to
- a user's <a href="#request" class="glossary">requests</a>.
- </dd>
-
- <dt>
<a name="recaptcha">recaptcha</a>
</dt>
<dd>
@@ -482,6 +505,42 @@ Definitions
</dd>
<dt>
+ <a name="release">release</a> (also: release manager)
+ </dt>
+ <dd>
+ We issue new <strong>releases</strong> of the Alaveteli code whenever key
+ work (new features, improvements, bugfixes, and so on) have been added to
+ the core code. Releases are identified by their tag, which comprises two or
+ three numbers: major, minor, and &mdash; if necessary &mdash; a patch
+ number. We recommend you always use the latest version. The process is
+ handled by the Alaveteli <strong>release manager</strong>, who decides what
+ changes are to be included in the current release, and the cut-off date for
+ the work. Currently this is Alaveteli's lead developer at mySociety.
+ <div class="more-info">
+ <p>More information:</p>
+ <ul>
+ <li>
+ The latest stable release is on the
+ <a href="https://github.com/mysociety/alaveteli/tree/master">master branch</a>.
+ </li>
+ <li>
+ See a <a href="https://github.com/mysociety/alaveteli/releases">list of all releases</a>
+ and their explicit tags.
+ </li>
+ <li>
+ We try to coordinate releases with any active translation work too.
+ See <a href="http://localhost:4000/docs/customising/translation/">translating
+ Alaveteli</a> for more information.
+ </li>
+ <li>
+ We encourage you use the <a href="{{site.baseurl}}docs/installing/deploy/">deployment
+ mechanism</a>, which makes it easier to keep your production server up-to-date.
+ </li>
+ </ul>
+ </div>
+ </dd>
+
+ <dt>
<a name="request">request</a>
</dt>
<dd>
@@ -495,6 +554,15 @@ Definitions
</dd>
<dt>
+ <a name="response">response</a>
+ </dt>
+ <dd>
+ A <strong>response</strong> is the email sent by an
+ <a href="#authority" class="glossary">authority</a> in reply to
+ a user's <a href="#request" class="glossary">requests</a>.
+ </dd>
+
+ <dt>
<a name="rails">Ruby on Rails</a> (also Rails)
</dt>
<dd>
@@ -584,15 +652,15 @@ Definitions
<p>More information:</p>
<ul>
<li>
- <a href="{{ site.baseurl }}docs/running/states">example states for WhatDoTheyKnow</a>
+ <a href="{{ site.baseurl }}docs/running/states/">example states for WhatDoTheyKnow</a>
(Alaveteli site running in the UK)
</li>
<li>
- for comparison, <a href="{{ site.baseurl }}docs/running/states_informatazyrtare">example states for InformataZyrtare</a>
+ for comparison, <a href="{{ site.baseurl }}docs/running/states_informatazyrtare/">example states for InformataZyrtare</a>
(Alaveteli site running in Kosovo)
</li>
<li>
- to customise or add your own states, see <a href="{{ site.baseurl }}docs/customising/themes">Customising the request states</a>
+ to customise or add your own states, see <a href="{{ site.baseurl }}docs/customising/themes/">Customising the request states</a>
</li>
</ul>
</div>
@@ -610,8 +678,7 @@ Definitions
<p>More information:</p>
<ul>
<li>
- <a href="{{ site.baseurl }}docs/customising
-/themes">about themes</a>
+ <a href="{{ site.baseurl }}docs/customising/themes/">about themes</a>
</li>
</ul>
</div>
diff --git a/docs/index.md b/docs/index.md
index 8cf85e8c2..b8cc66b48 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -8,7 +8,7 @@ title: Welcome
<p class="lead">
This is the documentation for Alaveteli,
an open source Freedom of Information platform
- created by <a href="http://www.mysociety.org">mySociety</a>.
+ created by <a href="https://www.mysociety.org">mySociety</a>.
</p>
## New to Alaveteli?
@@ -17,18 +17,18 @@ You've found the documentation for Alaveteli.
* Learn about the project at [www.alaveteli.org](http://www.alaveteli.org).
-* Read [Turbo Transparency](http://www.alaveteli.org/files/2012/10/Turbo-Transparency-v1.0.pdf), a paper about how and why to use Alaveteli for Freedom of Information systems
+* Read [Turbo Transparency](/assets/files/Turbo-Transparency-v1.0.pdf), a paper about how and why to use Alaveteli for Freedom of Information systems
-* Read the [Getting Started guide]({{ site.baseurl }}docs/getting_started)
+* Read the [Getting Started guide]({{ site.baseurl }}docs/getting_started/)
**The documentation covers
-[installing]({{ site.baseurl }}docs/installing),
-[customising]({{ site.baseurl }}docs/customising), and
-[running]({{ site.baseurl }}docs/running) your own Alaveteli site.**
+[installing]({{ site.baseurl }}docs/installing/),
+[customising]({{ site.baseurl }}docs/customising/), and
+[running]({{ site.baseurl }}docs/running/) your own Alaveteli site.**
If you're making changes to the source code, we have
-[documentation for developers]({{ site.baseurl }}docs/developers) too.
+[documentation for developers]({{ site.baseurl }}docs/developers/) too.
If you are an organisation who wants to use Alaveteli in your jurisdiction, or a developer who is interested in collaborating on the software, please
-[get in touch]({{ site.baseurl }}community).
+[get in touch]({{ site.baseurl }}community/).
diff --git a/docs/installing/ami.md b/docs/installing/ami.md
index 42f2907cb..1f7195761 100644
--- a/docs/installing/ami.md
+++ b/docs/installing/ami.md
@@ -9,7 +9,7 @@ title: Installing the easy way
We've made an Amazon Machine Image (AMI) so you can quickly deploy on Amazon EC2. This is handy if you just want to evaluate Alaveteli, for example.
</p>
-Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing).
+Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing/).
## Installing from our AMI
@@ -24,10 +24,10 @@ instance due to the low amount of memory available on those
instances; you will need to use at least a Small instance, which
Amazon will charge for.
-The AMI can be found in the EU West (Ireland) region, with the ID ami-8603f4f1
-and name “Basic Alaveteli installation 2014-01-29”. You can launch an instance
+The AMI can be found in the EU West (Ireland) region, with the ID ami-23519f54
+and name “Basic Alaveteli installation 2014-06-12”. You can launch an instance
based on that AMI with [this
-link](https://console.aws.amazon.com/ec2/home?region=eu-west-1#launchAmi=ami-8603f4f1).
+link](https://console.aws.amazon.com/ec2/home?region=eu-west-1#launchAmi=ami-23519f54).
When you create an EC2 instance based on that AMI, make sure that you choose
Security Groups that allows at least inbound HTTP, HTTPS, SSH and, if you want
diff --git a/docs/installing/deploy.md b/docs/installing/deploy.md
index 5378b89d6..4bbc91a9d 100644
--- a/docs/installing/deploy.md
+++ b/docs/installing/deploy.md
@@ -78,7 +78,7 @@ Next, on your local machine:
* Capistrano requires Ruby 1.9 or more, and can be installed using rubygems
* do: `gem install capistrano`
* install Bundler if you don't have it already -- do: `gem install bundler`
-* checkout the [Alaveteli repo](http://github.com/mysociety/alaveteli/) (you
+* checkout the [Alaveteli repo](https://github.com/mysociety/alaveteli/) (you
need some of the files available locally even though you might not be running
Alaveteli on this machine)
* copy the example file `config/deploy.yml.example` to `config/deploy.yml`
diff --git a/docs/installing/index.md b/docs/installing/index.md
index 98efa7b8a..c276c3d08 100644
--- a/docs/installing/index.md
+++ b/docs/installing/index.md
@@ -47,16 +47,16 @@ those servers, because Capistrano takes care of that for you.
## Installing the core code
-* [Install on Amazon EC2]({{ site.baseurl }}docs/installing/ami) using our AMI
-* [Use the installation script]({{ site.baseurl }}docs/installing/script) which does the full installation on your own server
-* [Manual installation]({{ site.baseurl }}docs/installing/manual_install) -- step-by-step instructions
+* [Install on Amazon EC2]({{ site.baseurl }}docs/installing/ami/) using our AMI
+* [Use the installation script]({{ site.baseurl }}docs/installing/script/) which does the full installation on your own server
+* [Manual installation]({{ site.baseurl }}docs/installing/manual_install/) -- step-by-step instructions
If you're setting up a development server on MacOS X, we've also got
-[MacOS installation instructions]({{ site.baseurl }}docs/installing/macos).
+[MacOS installation instructions]({{ site.baseurl }}docs/installing/macos/).
## Other installation information
Alaveteli needs to be able to send and receive email, so you need to setup your
MTA (Mail Transfer Agent) appropriately.
-* [Installing the MTA]({{ site.baseurl }}docs/installing/email)
+* [Installing the MTA]({{ site.baseurl }}docs/installing/email/)
diff --git a/docs/installing/macos.md b/docs/installing/macos.md
index 181057fda..e93ea452f 100644
--- a/docs/installing/macos.md
+++ b/docs/installing/macos.md
@@ -11,7 +11,7 @@ title: Installing on MacOS X
help.
</p>
-Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing).
+Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing/).
## MacOS X 10.7
@@ -25,7 +25,7 @@ If you are using OS X Lion, download *Command Line Tools for Xcode* from [Apple]
**Note:** As of Xcode 4.2, a non-LLVM version of GCC is no longer included. Homebrew has dealt with it by [switching to Clang](https://github.com/mxcl/homebrew/issues/6852). However, you may encounter errors installing RVM. *Please report these on the [mailing list](https://groups.google.com/group/alaveteli-dev).* The following instructions have been tested with Xcode 4.1. If necessary, you can install GCC from Xcode 4.1 by running:
- brew install http://github.com/adamv/homebrew-alt/raw/master/duplicates/apple-gcc42.rb
+ brew install https://github.com/adamv/homebrew-alt/raw/master/duplicates/apple-gcc42.rb
## Homebrew
@@ -88,17 +88,27 @@ The following is mostly from [the manual installation process]({{ site.baseurl}}
### Configure database
-Creates Alaveteli databases and an `foi` user with password `foi`.
-
- echo "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 -h localhost template1
+Create a database for your Mac user as homebrew doesn't create one by default:
+
+ createdb
+
+Create a `foi` user from the command line, like this:
+
+ createuser -s -P foi
+
+_Note:_ Leaving the password blank will cause great confusion if you're new to
+PostgreSQL.
+
+We'll create a template for our Alaveteli databases:
+
+ createdb -T template0 -E UTF-8 template_utf8
+ echo "update pg_database set datistemplate=true where datname='template_utf8';" | psql
+
+Then create the databases:
+
+ createdb -T template_utf8 -O foi alaveteli_production
+ createdb -T template_utf8 -O foi alaveteli_test
+ createdb -T template_utf8 -O foi alaveteli_development
### Clone Alaveteli
diff --git a/docs/installing/manual_install.md b/docs/installing/manual_install.md
index 4a98c9be2..8d6403b73 100644
--- a/docs/installing/manual_install.md
+++ b/docs/installing/manual_install.md
@@ -10,21 +10,32 @@ title: Manual installation
The following instructions describe the step-by-step process for
installing Alaveteli. <em>You don't necessarily need to do it this
way:</em> it's usually easier to use the
- <a href="{{ site.baseurl }}docs/installing/script">installation script</a>
+ <a href="{{ site.baseurl }}docs/installing/script/">installation script</a>
or the
- <a href="{{ site.baseurl }}docs/installing/ami">Amazon EC2 AMI</a>.
+ <a href="{{ site.baseurl }}docs/installing/ami/">Amazon EC2 AMI</a>.
</p>
-Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing).
+Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing/).
## Target operating system
These instructions assume Debian Squeeze (64-bit) or Ubuntu 12.04 LTS
(precise). Debian Squeeze is the best supported deployment platform. We also
-have instructions for [installing on MacOS]({{ site.baseurl }}docs/installing/macos).
+have instructions for [installing on MacOS]({{ site.baseurl }}docs/installing/macos/).
Commands are intended to be run via the terminal or over ssh.
+## Set the locale
+
+**Debian Squeeze**
+
+Follow the [Debian guide](https://wiki.debian.org/Locale#Standard) for configuring the locale of the operating system.
+
+Generate the locales you wish to make available. When the interactive screen asks you to pick a default locale, choose "None", as the SSH session will provide the locale required.
+
+ # dpkg-reconfigure locales
+
+Start a new SSH session to use your SSH locale.
## Get Alaveteli
@@ -164,20 +175,20 @@ Create a `foi` user from the command line, like this:
_Note:_ Leaving the password blank will cause great confusion if you're new to
PostgreSQL.
-Then create the databases:
+We'll create a template for our Alaveteli databases:
- # sudo -u postgres createdb -T template0 -E SQL_ASCII -O foi foi_production
- # sudo -u postgres createdb -T template0 -E SQL_ASCII -O foi foi_test
- # sudo -u postgres createdb -T template0 -E SQL_ASCII -O foi foi_development
+ # sudo -u postgres createdb -T template0 -E UTF-8 template_utf8
+ # echo "update pg_database set datistemplate=true where datname='template_utf8';" > /tmp/update-template.sql
+ # sudo -u postgres psql -f /tmp/update-template.sql
-We create using the ``SQL_ASCII`` encoding, because in postgres this is means
-"no encoding"; and because we handle and store all kinds of 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.
+Then create the databases:
-Now you need to set up the database config file to contain the name, username
-and password of your postgres database.
+ # sudo -u postgres createdb -T template_utf8 -O foi alaveteli_production
+ # sudo -u postgres createdb -T template_utf8 -O foi alaveteli_test
+ # sudo -u postgres createdb -T template_utf8 -O foi alaveteli_development
+
+Now you need to set up the database config file so that the application can
+connect to the postgres database.
* Copy `database.yml-example` to `database.yml` in `alaveteli/config`
* Edit it to point to your local postgresql database in the development
@@ -187,7 +198,8 @@ Example `development` section of `config/database.yml`:
development:
adapter: postgresql
- database: foi_development
+ template: template_utf8
+ database: alaveteli_development
username: foi
password: secure-password-here
host: localhost
@@ -206,7 +218,7 @@ to the test config in `database.yml` (as seen in `database.yml-example`)
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 -- see this
-[example config for Exim4]({{ site.baseurl }}docs/installing/email).
+[example config for Exim4]({{ site.baseurl }}docs/installing/email/).
Note that in development mode mail is handled by mailcatcher by default so
that you can see the mails in a browser - see [http://mailcatcher.me/](http://mailcatcher.me/) for more
@@ -380,11 +392,6 @@ by your deploy user (named `deploy` in this case):
deploy ALL = NOPASSWD: /etc/init.d/foi-alert-tracks, /etc/init.d/foi-purge-varnish
-The cron jobs refer to a program `run-with-lockfile`. See [this
-issue](https://github.com/mysociety/alaveteli/issues/112) for a discussion of
-where to find this program, and how you might replace it. This [one line
-script](https://gist.github.com/3741194) can install this program system-wide.
-
## Set up production web server
It is not recommended to run the website using the default Rails web server.
diff --git a/docs/installing/script.md b/docs/installing/script.md
index 173243dcb..b8b678a0a 100644
--- a/docs/installing/script.md
+++ b/docs/installing/script.md
@@ -9,7 +9,7 @@ title: Installing the easy way
If you prefer to use your own server, we've provided an installation script which does most of the work for you.
</p>
-Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing).
+Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing/).
## Installing with the installation script
diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md
index 1e749f845..cde828c9a 100644
--- a/docs/running/admin_manual.md
+++ b/docs/running/admin_manual.md
@@ -6,14 +6,14 @@ title: Administrator's guide
# Alaveteli administrator's guide
<p class="lead">
- What is it like running an Alaveteli site? This guide explains what you can expect, and the types of problem that you might encounter. It includes examples of how mySociety manages their own <a href="/docs/glossary/#foi" class="glossary">Freedom of Information</a> site, <a href="http://www.whatdotheyknow.com">whatdotheyknow.com</a>.
+ What is it like running an Alaveteli site? This guide explains what you can expect, and the types of problem that you might encounter. It includes examples of how mySociety manages their own <a href="/docs/glossary/#foi" class="glossary">Freedom of Information</a> site, <a href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>.
</p>
## What's involved?
The overhead in managing a successful FOI website is quite high. Richard, a
volunteer, wrote a [blog
-post](http://www.mysociety.org/2009/10/13/behind-whatdotheyknow/) about some of
+post](https://www.mysociety.org/2009/10/13/behind-whatdotheyknow/) about some of
this in 2009.
WhatDoTheyKnow usually has about 3 active volunteers at any one time managing
@@ -141,7 +141,7 @@ user of the site who later develops "Google remorse".
material down against the public interest in publishing / continuing to
publish the material. "Sensitive" personal data will typically require a
much higher level of public interest.
-* [WhatDoTheyKnow considers](http://www.whatdotheyknow.com/help/privacy#takedown) there to be a
+* [WhatDoTheyKnow considers](https://www.whatdotheyknow.com/help/privacy#takedown) there to be a
strong public interest in retaining the names of officers or servants of
public authorities
* For users who want their name removed entirely from the site, in the first
@@ -213,7 +213,7 @@ Respond to user and point them in the right direction.
> in public, via our site. To get started click "make a new freedom of
> information request" at:
>
-> http://www.whatdotheyknow.com/body/&lt;authority_name&gt;
+> https://www.whatdotheyknow.com/body/&lt;authority_name&gt;
### Wants advice
diff --git a/docs/running/index.md b/docs/running/index.md
index 3db94f713..90461fb3e 100644
--- a/docs/running/index.md
+++ b/docs/running/index.md
@@ -16,13 +16,13 @@ site, you need to make sure day-to-day tasks get done too. Most Alaveteli sites
are run by a team who allocate some time every day to user support and generally keeping
the project up to date.
-* the [administrator's guide]({{ site.baseurl }}docs/running/admin_manual) describes
+* the [administrator's guide]({{ site.baseurl }}docs/running/admin_manual/) describes
what you need to do and know to run your site
* we've prepared a checklist of
- [things to consider]({{ site.baseurl }}docs/running/server)
+ [things to consider]({{ site.baseurl }}docs/running/server/)
when setting up your production server
-* see the [different states a request can be in]({{ site.baseurl }}docs/running/states)
+* see the [different states a request can be in]({{ site.baseurl }}docs/running/states/)
diff --git a/docs/running/server.md b/docs/running/server.md
index 63ec1800f..1de0ce595 100644
--- a/docs/running/server.md
+++ b/docs/running/server.md
@@ -25,18 +25,14 @@ ask us about hosting.
## Cron jobs
Don't forget to set up the cron jobs as outlined in the
-[installation instructions]({{ site.baseurl }}docs/installing/manual_install).
-As of October 2011, they rely on a small program created by mySociety called
-`run-with-lockfile`. A discussion of where the source for this can be found,
-and possible alternatives, lives in
-[Alaveteli issue #112](https://github.com/mysociety/alaveteli/issues/112).
+[installation instructions]({{ site.baseurl }}docs/installing/manual_install/).
## Webserver configuration
We recommend running your site behind
[Apache](https://httpd.apache.org) +
[Passenger](https://www.phusionpassenger.com). Refer to the
-[installation instructions]({{ site.baseurl }}docs/installing/manual_install)
+[installation instructions]({{ site.baseurl }}docs/installing/manual_install/)
regarding `PassengerMaxPoolSize`, which you should
experiment with to match your available RAM. It is very unlikely that you'll
ever need a pool larger than [Passenger's
@@ -49,7 +45,7 @@ Alaveteli ships with a
## Security
-You _must_ change all key-related [config settings]({{ site.baseurl }}docs/customising/config)
+You _must_ change all key-related [config settings]({{ site.baseurl }}docs/customising/config/)
in `general.yml` from their default values. This includes (but may not be limited to!)
these settings:
@@ -76,11 +72,10 @@ deliverability of your email:
* Set up [SPF records](http://www.openspf.org/) for your domain
* Set up <a
- href="http://en.wikipedia.org/wiki/Feedback_loop_(email)#Feedback_loop_links_f
- or_some_email_providers">feedback loops</a> with the main email providers
+ href="http://wiki.asrg.sp.am/wiki/Feedback_loop_links_for_some_email_providers">feedback loops</a> with the main email providers
(Hotmail and Yahoo! are recommended)
* Especially if deploying from Amazon EC2, use an external SMTP relay for
- sending outgoing mail. See [Alaveteli EC2 AMI]( {{ site.baseurl }}docs/installing/ami)
+ sending outgoing mail. See [Alaveteli EC2 AMI]( {{ site.baseurl }}docs/installing/ami/)
for more suggestions.
## Backup
diff --git a/docs/running/states.md b/docs/running/states.md
index 73e49eba7..1c3fb217e 100644
--- a/docs/running/states.md
+++ b/docs/running/states.md
@@ -15,16 +15,16 @@ The request states are defined in the Alaveteli code, and we recommend you use
them (provided they match the <a href="{{ site.baseurl }}docs/glossary/#foi"
class="glossary">FOI law</a> in your own jurisdiction). But if you do need to
customise them, you can &mdash; see
-<a href="{{ site.baseurl }}docs/customising/themes">Customising the request states</a> for details.
+<a href="{{ site.baseurl }}docs/customising/themes/">Customising the request states</a> for details.
## WhatDoTheyKnow example
-Requests made on the UK's Alaveteli instance, [WhatDoTheyKnow](http://www.whatdotheyknow.com),
+Requests made on the UK's Alaveteli instance, [WhatDoTheyKnow](https://www.whatdotheyknow.com),
may be in any of the states described below.
Note that your site doesn't need to use the same states as WhatDoTheyKnow does. For example,
Kosovo's instance uses slightly different states: see
-[this comparison of their differences]({{ site.baseurl }}docs/running/states_informatazyrtare).
+[this comparison of their differences]({{ site.baseurl }}docs/running/states_informatazyrtare/).
### States
diff --git a/docs/running/states_informatazyrtare.md b/docs/running/states_informatazyrtare.md
index 8097244c5..bd5ff1a1c 100644
--- a/docs/running/states_informatazyrtare.md
+++ b/docs/running/states_informatazyrtare.md
@@ -29,7 +29,7 @@ facilitates this by allowing you to customise the states that are used.
This example is to show clearly that you can use different states depending on
your local requirements, and how that might look. See [Customising the request
-states]({{ site.baseurl }}docs/customising/themes) for details on how to do this.
+states]({{ site.baseurl }}docs/customising/themes/) for details on how to do this.
### States used by InformataZyrtare but not WDTK
@@ -45,7 +45,7 @@ states]({{ site.baseurl }}docs/customising/themes) for details on how to do this
* <a href="{{ site.baseurl }}docs/running/states/#user_withdrawn">user_withdrawn</a>
* <a href="{{ site.baseurl }}docs/running/states/#waiting_response_very_overdue">waiting_response_very_overdue</a>
-For more details, see all the [states used by WhatDoTheyKnow]({{site.baseurl}}docs/running/states)) for details.
+For more details, see all the [states used by WhatDoTheyKnow]({{site.baseurl}}docs/running/states/)) for details.
---
diff --git a/docs/running/upgrading.md b/docs/running/upgrading.md
index a3b292cf0..2142bfd47 100644
--- a/docs/running/upgrading.md
+++ b/docs/running/upgrading.md
@@ -5,20 +5,53 @@ title: Upgrading
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`.
+<p class="lead">
+ Alaveteli is under active development &mdash; don't let the
+ version you're running get too far behind our latest
+ <a href="{{site.baseurl}}docs/glossary/#release" class="glossary__link">release</a>.
+ This page describes how to keep your site up-to-date
+</p>
+
+## Master branch contains the latest stable release
+
+The developer team policy is that the `master` branch in git should always
+contain the latest stable release -- so you'll be up to date if you pull from
+the `master` branch. However, on your
+<a href="{{site.baseurl}}docs/glossary/#production" class="glossary">production
+site</a>, you should know precisely what version you're running, and deploy
+Alaveteli from a [*specific* release
+tag](https://github.com/mysociety/alaveteli/releases).
+
+Upgrading may just require pulling in the latest code -- but it may also require
+other changes ("further action"). For this reason, for anything other than a
+*patch* (see below), always read the
+[`CHANGES.md`](https://github.com/mysociety/alaveteli/blob/master/doc/CHANGES.md)
+document **before** doing an uprade. This way you'll be able to prepare for any
+other changes that might be needed to make the new code work.
+
+## How to upgrade the code
+
+* If you're using Capistrano for deployment,
+ simply [deploy the code]({{site.baseurl}}docs/installing/deploy/#usage):
+ set the repo and branch in `deploy.yml` to be the version you want.
+ We recommend you set this to the explicit tag name (for example,
+ `0.18`, and not `master`) so there's no risk of you accidentally deploying
+ a new version before you're aware it's been released.
+* otherwise, you can simply upgrade by running `git pull`
+
+## Patches
Patch version increases (e.g. 1.2.3 &rarr; 1.2.**4**) should not require any further
action on your part.
+## Minor version increases
+
Minor version increases (e.g. 1.2.4 &rarr; 1.**3**.0) will usually require further
-action. You should read the [`CHANGES.md`](https://github.com/mysociety/alaveteli/blob/master/doc/CHANGES.md) document to see what's changed since
-your last deployment, paying special attention to anything in the "Upgrade notes"
-sections.
+action. You should read the [`CHANGES.md`](https://github.com/mysociety/alaveteli/blob/master/doc/CHANGES.md)
+document to see what's changed since your last deployment, paying special attention
+to anything in the "Upgrade notes" sections.
-Any upgrade may include new translations strings, i.e. new or altered messages
+Any upgrade may include new translations strings, that is, new or altered messages
to the user that need translating to your locale. You should visit Transifex
and try to get your translation up to 100% on each new release. Failure to do
so means that any new words added to the Alaveteli source code will appear in
@@ -26,7 +59,10 @@ your website in English by default. If your translations didn't make it to the
latest release, you will need to download the updated `app.po` for your locale
from Transifex and save it in the `locale/` folder.
-Unless you're using Capistrano for deployment, you should always run the script `scripts/rails-post-deploy` after each
+## Run the post-deploy script
+
+Unless you're [using Capistrano for deployment]({{site.baseurl}}docs/installing/deploy/),
+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.
generated by cgit v1.2.3 (git 2.25.1) at 2025-09-10 11:50:17 +0000