diff options
Diffstat (limited to 'docs/running')
| -rw-r--r-- | docs/running/admin_manual.md | 55 | ||||
| -rw-r--r-- | docs/running/categories_and_tags.md | 26 | ||||
| -rw-r--r-- | docs/running/holding_pen.md | 24 | ||||
| -rw-r--r-- | docs/running/index.md | 8 | ||||
| -rw-r--r-- | docs/running/redaction.md | 18 | ||||
| -rw-r--r-- | docs/running/requests.md | 32 | ||||
| -rw-r--r-- | docs/running/server.md | 24 | ||||
| -rw-r--r-- | docs/running/upgrading.md | 10 |
8 files changed, 99 insertions, 98 deletions
diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md index 7c112400c..b05ddb5f4 100644 --- a/docs/running/admin_manual.md +++ b/docs/running/admin_manual.md @@ -8,7 +8,8 @@ title: 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" + examples of how mySociety manages their own + <a href="{{ page.baseurl }}/docs/glossary/#foi" class="glossary__link">Freedom of Information</a> site, <a href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>. </p> @@ -57,7 +58,7 @@ WhatDoTheyKnow usually has about 3 active volunteers at any one time managing the support, plus a few other less active people who help out at different times. -Administration tasks can be split into [**maintenance**]({{ site.baseurl }}docs/running/admin_manual/#maintenance) and [**user support**]({{ site.baseurl }}docs/running/admin_manual/#user-support). +Administration tasks can be split into [**maintenance**]({{ page.baseurl }}/docs/running/admin_manual/#maintenance) and [**user support**]({{ page.baseurl }}/docs/running/admin_manual/#user-support). The boundaries of these tasks is in fact quite blurred; the main distinction is that the former happen exclusively through the web admin interface, whereas the latter are mediated by email directly with end users (but often result in @@ -312,13 +313,13 @@ line, and piping the contents of that file into the mail handling script. e.g. ### Administrator privileges and accessing the admin interface -The <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">administrative interface</a> +The <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">administrative interface</a> is at the URL `/admin`. Only users who are -<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">administrators</a> +<a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">administrators</a> can access the admin interface. To make a user an administrator on a brand new site, -[follow these steps]({{ site.baseurl }}docs/installing/next_steps/#create-a-superuser-admin-account). +[follow these steps]({{ page.baseurl }}/docs/installing/next_steps/#create-a-superuser-admin-account). If you're already an administrator, you can grant other users administrator privilege too. Go to `/admin/users` or click on **Users** at the top of @@ -336,20 +337,20 @@ have extra privileges in the main website front end. Administrators can: <div class="attention-box warning"> It is possible completely to override the administrator authentication by setting - <code><a href="{{ site.baseurl }}docs/customising/config/#skip_admin_auth">SKIP_ADMIN_AUTH</a></code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#skip_admin_auth">SKIP_ADMIN_AUTH</a></code> to <code>true</code> in <code>general.yml</code>. Never do this, unless you - are working on a <a href="{{ site.baseurl }}docs/glossary/#development" + are working on a <a href="{{ page.baseurl }}/docs/glossary/#development" class="glossary__link">development</a> server. </div> ### Removing a message from the holding pen Alaveteli puts incoming messages (that is, -<a href="{{ site.baseurl }}docs/glossary/#reponse" class="glossary__link">responses</a>) +<a href="{{ page.baseurl }}/docs/glossary/#reponse" class="glossary__link">responses</a>) into the -<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a> +<a href="{{ page.baseurl }}/docs/glossary/#holding_pen" class="glossary__link">holding pen</a> if their `To:` email addresses can't automatically be associated with a -<a href="{{ site.baseurl }}docs/glossary/#reponse" class="glossary__link">request</a>. +<a href="{{ page.baseurl }}/docs/glossary/#reponse" class="glossary__link">request</a>. The two most common reasons for this are: @@ -361,7 +362,7 @@ When this happens, the messages wait in the holding pen until an administrator redelivers them to the correct request, or else deletes them. To do this, log into the -The <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a> +The <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a> at `/admin`. If there are any messages in the holding pen, you'll see this message under the title *Things to do*: @@ -417,13 +418,13 @@ in the holding pen, and is shown instead on the public request page. ### Rejecting spam that arrives in the holding pen Alaveteli maintains a -<a href="{{ site.baseurl }}docs/glossary/#spam-address-list" class="glossary__link">spam address list</a>. +<a href="{{ page.baseurl }}/docs/glossary/#spam-address-list" class="glossary__link">spam address list</a>. Any incoming message to an email address on that list *that would otherwise be put in the holding pen* will be rejected and won't appear in the admin. If you see spam messages in the -<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a>, +<a href="{{ page.baseurl }}/docs/glossary/#holding_pen" class="glossary__link">holding pen</a>, check if they are being sent to a *specific* email address. If they are, that email address has become a "spam-target" and you should add it to the spam address list. Thereafter, Alaveteli will automatically reject any messages that @@ -434,7 +435,7 @@ messages end up in the holding pen) becomes a spam-target once it's been harvested by spammers. There are several reasons why such an invalid address might exist — perhaps it was mis-spelled in a manual reply, for example. Our experience from running -<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> +<a href="{{ page.baseurl }}/docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> is that you can safely dismiss incoming email to such addresses once they have been targeted in this way. Legitimate emails that arrive in the holding pen tend to be unique errors (for example, missing the last character of the email @@ -471,7 +472,7 @@ this address. Note that if you are seeing consistent spam email in your holding pen, you should also consider implementing (or increasing) the anti-spam measures running in your -<a href="{{ site.baseurl }}docs/glossary/#mta" class="glossary__link">MTA</a>. +<a href="{{ page.baseurl }}/docs/glossary/#mta" class="glossary__link">MTA</a>. ### Creating, changing and uploading public authority data @@ -554,7 +555,7 @@ unrecognised column name, the import will fail. <td><em>yes</em></td> <td> The URL of the authority's - <a href="{{ site.baseurl }}docs/glossary/#publication-scheme" class="glossary__link">publication scheme</a>, + <a href="{{ page.baseurl }}/docs/glossary/#publication-scheme" class="glossary__link">publication scheme</a>, if they have one </td> </tr> @@ -563,7 +564,7 @@ unrecognised column name, the import will fail. <td><em>yes</em></td> <td> The URL of the authority's - <a href="{{ site.baseurl }}docs/glossary/#disclosure-log" class="glossary__link">disclosure log</a>, + <a href="{{ page.baseurl }}/docs/glossary/#disclosure-log" class="glossary__link">disclosure log</a>, if they have one </td> </tr> @@ -588,10 +589,10 @@ unrecognised column name, the import will fail. changed. This means you only really need to include data you want to update. * Columns with "i18n suffix" can accept - <a href="{{ site.baseurl }}docs/glossary/#i18n" class="glossary__link">internationalised</a> + <a href="{{ page.baseurl }}/docs/glossary/#i18n" class="glossary__link">internationalised</a> names. Add a full stop followed by the language code, for example: `name.es` for Spanish (`es`). This *must* be a locale you've declared in - [`AVAILABLE_LOCALES`]({{ site.baseurl }}docs/customising/config/#available_locales). + [`AVAILABLE_LOCALES`]({{ page.baseurl }}/docs/customising/config/#available_locales). If you don't specify an i18n suffix, the default language for your site is assumed. * You can specify a blank entry in the CSV file by having no character @@ -689,14 +690,14 @@ Enter some text in the in the ‘Ban text’ box to explain why they have been b ### Allowing a user to make more requests -Alaveteli has a config setting <code><a href="{{ site.baseurl }}docs/customising/config/#max_requests_per_user_per_day">MAX_REQUESTS_PER_USER_PER_DAY</a></code>, +Alaveteli has a config setting <code><a href="{{ page.baseurl }}/docs/customising/config/#max_requests_per_user_per_day">MAX_REQUESTS_PER_USER_PER_DAY</a></code>, which determines the maximum number of requests that a normal user can make in a day. If they try to make more than this number of requests within a 24 hour period, they will see a message telling them that they have hit the limit, and encouraging them to use the contact form if they feel they have a good reason to ask for the request limit to be lifted. -To lift the request limit for a particular user, go to the <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin +To lift the request limit for a particular user, go to the <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Users**, then click on the name of the user you want to lift the request limit for. Click the **Edit** button. Tick the checkbox **No rate limit**, and click the **Save** button. @@ -716,12 +717,12 @@ Users can choose which authorities to include in a batch requests. They can eve </div> To enable batch requests on your site, first you must set -<code><a href="{{ site.baseurl }}docs/customising/config/#allow_batch_requests">ALLOW_BATCH_REQUESTS</a></code> +<code><a href="{{ page.baseurl }}/docs/customising/config/#allow_batch_requests">ALLOW_BATCH_REQUESTS</a></code> to <code>true</code> in <code>general.yml</code>. This does not allow anyone to make batch requests yet. You must still enable this for each user on an individual basis. To do this, go to the -<a href="{{ site.baseurl }}docs/glossary/#admin" +<a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Users**, then click on the name of the user who wants to make batch requests. Click the **Edit** button. Tick the checkbox **Can make batch requests**, and @@ -740,18 +741,18 @@ an existing request to that authority to the new email address. Alternatively, a user may send a request to the wrong authority. In that situation, you can change the authority on the request and then resend it to the correct authority. For instructions, see -[resending a request or sending it to a different authority]({{ site.baseurl }}docs/running/requests/#resending-a-request-or-sending-it-to-a-different-authority). +[resending a request or sending it to a different authority]({{ page.baseurl }}/docs/running/requests/#resending-a-request-or-sending-it-to-a-different-authority). ### Hiding a request If a request contains vexatious or inappropriate content, is libellous, or is not a valid -<a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary__link">Freedom of Information</a> +<a href="{{ page.baseurl }}/docs/glossary/#foi" class="glossary__link">Freedom of Information</a> request at all, you may want to hide it. A hidden request is still visible to you and the other administrators, and (optionally) the requester themselves. For instructions, see -[hiding a request]({{ site.baseurl }}docs/running/requests/#hiding-a-request). +[hiding a request]({{ page.baseurl }}/docs/running/requests/#hiding-a-request). Responses to a hidden request will be accepted in the normal way, but because they are added to the request's page, they too will be hidden. @@ -759,7 +760,7 @@ they are added to the request's page, they too will be hidden. ### Deleting a request You can delete a request from the site. For instructions, see -[deleting a request]({{ site.baseurl }}docs/running/requests/#deleting-a-request). +[deleting a request]({{ page.baseurl }}/docs/running/requests/#deleting-a-request). Responses to a deleted request will be sent to the holding pen. diff --git a/docs/running/categories_and_tags.md b/docs/running/categories_and_tags.md index 8f36ae472..e1192f84d 100644 --- a/docs/running/categories_and_tags.md +++ b/docs/running/categories_and_tags.md @@ -8,12 +8,12 @@ title: Categories & tags <p class="lead"> Use tags to arrange - <a href="{{ site.baseurl }}docs/glossary/#authority" + <a href="{{ page.baseurl }}/docs/glossary/#authority" class="glossary__link">authorities</a> into categories, or to associate related authorities with each other. This helps your users find the right authority for the - <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a> - (or <a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">response</a>) + <a href="{{ page.baseurl }}/docs/glossary/#request" class="glossary__link">request</a> + (or <a href="{{ page.baseurl }}/docs/glossary/#response" class="glossary__link">response</a>) they are interested in. </p> @@ -26,7 +26,7 @@ Admin interface introduced in Alaveteli version 0.20 Alaveteli lets you organise your authorities into *categories*. Categories can themselves belong to *category headings*. For example, some of the categories and headings on -<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>'s +<a href="{{ page.baseurl }}/docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>'s <a href="https://www.whatdotheyknow.com/body/list/all">View authorities</a> page look like this: > * **Media and culture** @@ -57,7 +57,7 @@ users find the specific authorities they are looking for. Try to use simple but descriptive words for tags. Tags cannot contain spaces (use an underscore if you need to, <code>like_this</code>). Remember that tags will be seen and used by the public (for example, in the - <a href="{{ site.baseurl }}docs/glossary/#advanced-search" class="glossary__link">advanced search</a>). + <a href="{{ page.baseurl }}/docs/glossary/#advanced-search" class="glossary__link">advanced search</a>). </div> ### Adding a new category @@ -113,7 +113,7 @@ of these tags. <td> This is a test/dummy authority. It is not displayed to the public on your main site, and it is not included when you - <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">export authorities in CSV format</a>. + <a href="{{ page.baseurl }}/docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">export authorities in CSV format</a>. </td> </tr> <tr> @@ -130,7 +130,7 @@ of these tags. <code>not_apply</code> </td> <td> - <a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary__link">Freedom of Information</a> + <a href="{{ page.baseurl }}/docs/glossary/#foi" class="glossary__link">Freedom of Information</a> law does not apply to this authority: new requests cannot be sent to an authority with this tag. </td> @@ -142,7 +142,7 @@ of these tags. <td> <em>Custom example:</em> (see below)<br> On our UK installation of Alaveteli, - <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>, + <a href="{{ page.baseurl }}/docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>, this tag indicates that the authority is subject to an alternative law (Environment Information Regulations, rather than the Freedom of Information), which means Alaveteli must change the wording of these @@ -155,7 +155,7 @@ of these tags. </td> <td> <em>Custom example:</em> (see below)<br> - <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> + <a href="{{ page.baseurl }}/docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> applies a different definition of "late" if an authority has the <code>school</code> tag. </td> </tr> @@ -169,10 +169,10 @@ categories. If you are a developer, and you want to add special behaviour to your site based on your own tags, you need to add custom code, which should probably go in your own -<a href="{{ site.baseurl}}docs/glossary/#theme" class="glossary__link">theme</a>. +<a href="{{ page.baseurl }}/docs/glossary/#theme" class="glossary__link">theme</a>. For example, in the UK, schools are granted special concession in the law to allow for requests that are made out of term-time. Alaveteli handles this by using the -[`SPECIAL_REPLY_VERY_LATE_AFTER_DAYS`]({{ site.baseurl }}docs/customising/config/#special_reply_very_late_after_days) +[`SPECIAL_REPLY_VERY_LATE_AFTER_DAYS`]({{ page.baseurl }}/docs/customising/config/#special_reply_very_late_after_days) config value if the authority has the `school` tag. See [`is_school?`](https://github.com/mysociety/alaveteli/blob/f0bbeb4abf4bf07e5cfb46668f39bbff72ed7210/app/models/public_body.rb#L391) @@ -183,7 +183,7 @@ for the source code. ## Searching with tags Alaveteli's -<a href="{{ site.baseurl }}docs/glossary/#advanced-search" class="glossary__link">advanced search</a> +<a href="{{ page.baseurl }}/docs/glossary/#advanced-search" class="glossary__link">advanced search</a> feature (which is available to all your users) can search for specific tags. So if you add useful tags and publicise them, your users can use them to find related authorities. For example, see the <a @@ -191,7 +191,7 @@ href="https://www.whatdotheyknow.com/advancedsearch">advanced search on WhatDoTheyKnow</a> to see this at work. You can add reference numbers or specific values to tags using a colon. On -<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> +<a href="{{ page.baseurl }}/docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> we tag all authorities that are charities with the tag `charity:123456` (where 123456 is the authority's registered charity number). diff --git a/docs/running/holding_pen.md b/docs/running/holding_pen.md index 5b7f08bec..535c17dd8 100644 --- a/docs/running/holding_pen.md +++ b/docs/running/holding_pen.md @@ -8,15 +8,15 @@ title: The holding pen <p class="lead"> The <em>holding pen</em> is where Alaveteli puts any incoming - <a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">responses</a> + <a href="{{ page.baseurl }}/docs/glossary/#response" class="glossary__link">responses</a> that can't be matched to a - <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a> + <a href="{{ page.baseurl }}/docs/glossary/#request" class="glossary__link">request</a> automatically. </p> Alaveteli works by emailing requests to the correct target -<a href="{{ site.baseurl }}docs/glossary/#authority" class="glossary__link">authority</a>. +<a href="{{ page.baseurl }}/docs/glossary/#authority" class="glossary__link">authority</a>. That email message is sent from a unique email address — that is, an email address that is associated with that single request (technically, Alaveteli hashes the request ID to generate a unique address and uses this as @@ -25,7 +25,7 @@ the `Reply-to:` address). So whenever an authority replies (by email) to a request that Alaveteli has sent, that response will be addressed to that request's unique email address. The email is received by your installation's -<a href="{{ site.baseurl}}docs/glossary/#mta" class="glossary__link">MTA</a>, +<a href="{{ page.baseurl }}/docs/glossary/#mta" class="glossary__link">MTA</a>, and is passed on to Alaveteli. In this way, incoming messages are easily matched with the request they are responses to — this is important because your site displays the responses underneath their original request, on @@ -34,11 +34,11 @@ the request's page. Normally, this works fine. But sometimes things go wrong, and a message comes in that can't be matched with a request. When this happens, Alaveteli puts the message in the -<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding +<a href="{{ page.baseurl }}/docs/glossary/#holding_pen" class="glossary__link">holding pen </a>. Messages wait in the holding pen until an -<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a> +<a href="{{ page.baseurl }}/docs/glossary/#super" class="glossary__link">administrator</a> redelivers them to the correct request, or else deletes them. ## Why messages end up in the holding pen @@ -61,7 +61,7 @@ There are several reasons why a message might end up in the holding pen: deliberate attempt to send spam. * **the response is to a request that has been deleted**<br> - If you [delete a request]({{ site.baseurl }}docs/running/requests/#deleting-a-request), + If you [delete a request]({{ page.baseurl }}/docs/running/requests/#deleting-a-request), Alaveteli cannot deliver responses to it. * **the response has been rejected and rejections are set to go to the holding pen**<br> @@ -72,12 +72,12 @@ There are several reasons why a message might end up in the holding pen: reasons — for example, if a response is sent from an unrecognised email address for a request whose *Allow new responses from* setting is `authority_only`. See instructions on - [how to manage requests]({{site.baseurl}}docs/running/requests/) for details. + [how to manage requests]({{ page.baseurl }}/docs/running/requests/) for details. ## What to do: redeliver or delete You need to be an -<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a> +<a href="{{ page.baseurl }}/docs/glossary/#super" class="glossary__link">administrator</a> to modify the holding pen. There are two things you can do to a message in the holding pen: @@ -90,12 +90,12 @@ There are two things you can do to a message in the holding pen: If the message is not a response, you can delete it. For instructions, see -[removing a message from the holding pen]({{ site.baseurl }}docs/running/admin_manual/#removing-a-message-from-the-holding-pen). +[removing a message from the holding pen]({{ page.baseurl }}/docs/running/admin_manual/#removing-a-message-from-the-holding-pen). If the `To:` address does not belong to a valid request and the message is clearly spam you can add that email address to Alaveteli's -<a href="{{site.baseurl}}#spam-address-list" class="glossary__link">spam address list</a>. +<a href="{{ page.baseurl }}/#spam-address-list" class="glossary__link">spam address list</a>. Subsequent messages to that address will be automatically rejected — for instructions see -[rejecting spam that arrives in the holding pen]({{ site.baseurl }}docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen). +[rejecting spam that arrives in the holding pen]({{ page.baseurl }}/docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen). diff --git a/docs/running/index.md b/docs/running/index.md index bbf30d3b9..c84a74427 100644 --- a/docs/running/index.md +++ b/docs/running/index.md @@ -11,19 +11,19 @@ title: Running </p> Alaveteli is not just software. To run a successful -<a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary__link">Freedom of Information</a> +<a href="{{ page.baseurl }}/docs/glossary/#foi" class="glossary__link">Freedom of Information</a> 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]({{ page.baseurl }}/docs/running/admin_manual/) describes what you need to do and know to run your site -* The [redaction guide]({{ site.baseurl }}docs/running/redaction/) includes some +* The [redaction guide]({{ page.baseurl }}/docs/running/redaction/) includes some examples of Alaveteli's ability to redact sensitive information * We've prepared a checklist of - [things to consider]({{ site.baseurl }}docs/running/server/) + [things to consider]({{ page.baseurl }}/docs/running/server/) when setting up your production server diff --git a/docs/running/redaction.md b/docs/running/redaction.md index 6ab8fed86..1e6542873 100644 --- a/docs/running/redaction.md +++ b/docs/running/redaction.md @@ -7,7 +7,7 @@ title: Redacting Sensitive Information In some countries, local requirements mean that requests need to contain personal information such as the address or ID number of the person asking for information. Usually requesters do not want this information to be displayed to the general public. -Alaveteli has some ability to deal with this through the use of <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rules</a>. +Alaveteli has some ability to deal with this through the use of <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rules</a>. The [theme](https://github.com/mysociety/derechoapreguntar-theme) we'll use as an example requires a National Identity Card Number and what's known as General Law in Nicaragua (Date of Birth, Domicile, Occupation and Marital Status). @@ -30,13 +30,13 @@ When a request is made the user's ID Number is now added to the footer of the ou  -At this point we haven't added any <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rules</a>. When the authority replies it is unlikely that the responder will remove the quoted section of the email: +At this point we haven't added any <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rules</a>. When the authority replies it is unlikely that the responder will remove the quoted section of the email:  -We could add a <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> for the individual request, but as every request will contain a user's ID Number its better to add some code to do do it automatically. +We could add a <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> for the individual request, but as every request will contain a user's ID Number its better to add some code to do do it automatically. -To illustrate this we'll patch the `User` model with a callback that creates a <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> when the user is created and updated. +To illustrate this we'll patch the `User` model with a callback that creates a <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> when the user is created and updated. # THEME_ROOT/lib/model_patches.rb User.class_eval do @@ -54,7 +54,7 @@ To illustrate this we'll patch the `User` model with a callback that creates a < end end -You can see the new <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> in the admin interface: +You can see the new <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> in the admin interface:  @@ -66,9 +66,9 @@ It also gets redacted if the public body use the ID Number in the main email bod  -A <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">censor rule</a> added to a user only gets applied to correspondence on requests created by that user. It does not get applied to annotations made by the user. +A <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">censor rule</a> added to a user only gets applied to correspondence on requests created by that user. It does not get applied to annotations made by the user. -**Warning:** Redaction in this way requires the sensitive text to be in exactly the same format as the <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a>. If it differs even slightly, the redaction can fail. If the public body was to remove the hyphens from the number it would not be redacted: +**Warning:** Redaction in this way requires the sensitive text to be in exactly the same format as the <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a>. If it differs even slightly, the redaction can fail. If the public body was to remove the hyphens from the number it would not be redacted:  @@ -102,7 +102,7 @@ Note that the information is now contained in a specially formatted block of tex  -This allows a <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> to match the special formatting and remove anything contained within. This <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> is global, so it will act on matches in all requests. +This allows a <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> to match the special formatting and remove anything contained within. This <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> is global, so it will act on matches in all requests. # THEME_ROOT/lib/censor_rules.rb # If not already created, make a CensorRule that hides personal information @@ -126,7 +126,7 @@ In this case the authority has revealed the user's Date of Birth and Domicile:  -Its really difficult to add a <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> to remove this type of information. One suggestion might be to remove all mentions of the user's Date of Birth, but you would have to account for [every type of date format](http://en.wikipedia.org/wiki/Calendar_date#Date_format). Likewise, you could redact all occurrences of the user's Domicile, but if they a question about their local area (very likely) the request would become unintelligible. +Its really difficult to add a <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> to remove this type of information. One suggestion might be to remove all mentions of the user's Date of Birth, but you would have to account for [every type of date format](http://en.wikipedia.org/wiki/Calendar_date#Date_format). Likewise, you could redact all occurrences of the user's Domicile, but if they a question about their local area (very likely) the request would become unintelligible.  diff --git a/docs/running/requests.md b/docs/running/requests.md index e554fe763..3b4c6e44e 100644 --- a/docs/running/requests.md +++ b/docs/running/requests.md @@ -8,17 +8,17 @@ title: Managing requests <p class="lead"> Alaveteli makes it easy for a user to make a - <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a>. + <a href="{{ page.baseurl }}/docs/glossary/#request" class="glossary__link">request</a>. As an - <a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a>, + <a href="{{ page.baseurl }}/docs/glossary/#super" class="glossary__link">administrator</a>, there are some things about that request you can change once it’s been created. </p> A request is automatically created when a user submits and (where necessary) confirms it. Alaveteli sends it to the -<a href="{{ site.baseurl }}docs/glossary/#authority" class="glossary__link">authority</a> +<a href="{{ page.baseurl }}/docs/glossary/#authority" class="glossary__link">authority</a> responsible and handles any -<a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">responses</a>. +<a href="{{ page.baseurl }}/docs/glossary/#response" class="glossary__link">responses</a>. Usually this process runs without needing any intervention from an administrator. But sometimes you'll want to change some aspect of the request, or the way Alaveteli is handling it. @@ -35,7 +35,7 @@ or the way Alaveteli is handling it. ## What state is the request in? Every request moves through a series of -<a href="{{ site.baseurl }}docs/glossary/#state" class="glossary__link">states</a>, +<a href="{{ page.baseurl }}/docs/glossary/#state" class="glossary__link">states</a>, indicating its progress. Usually a new request will be in the `waiting_response` state until something happens to change that — for example, a response is received. @@ -87,7 +87,7 @@ for how to change these settings. ## Changing things about a request To change any of these settings, go to the -<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>, +<a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Requests**, then click on the title of the request you want to affect. Click the **Edit metadata** button. @@ -179,12 +179,12 @@ Click the **Edit metadata** button. </li> <li> <code>holding pen</code>: responses are put in the - <a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a> + <a href="{{ page.baseurl }}/docs/glossary/#holding_pen" class="glossary__link">holding pen</a> for an administrator to deal with </li> <li> <code>blackhole</code>: responses are destroyed by being sent to a - <a href="{{ site.baseurl }}docs/glossary/#blackhole" class="glossary__link">black hole</a> + <a href="{{ page.baseurl }}/docs/glossary/#blackhole" class="glossary__link">black hole</a> </li> </ul> </td> @@ -194,7 +194,7 @@ Click the **Edit metadata** button. What state is it in? </td> <td> - See <a href="{{ site.baseurl }}docs/customising/states/">more about + See <a href="{{ page.baseurl }}/docs/customising/states/">more about request states</a>, which can be customised for your installation. <p> You can force the state of the request by choosing it explicitly. @@ -240,10 +240,10 @@ Click the **Edit metadata** button. </p> <p> Although it’s a little more complex than tags on requests, - <a href="{{ site.baseurl }}docs/glossary/#category" class="glossary__link">categories</a> + <a href="{{ page.baseurl }}/docs/glossary/#category" class="glossary__link">categories</a> also use tags: see - <a href="{{ site.baseurl }}docs/running/categories_and_tags/">more about tags</a> + <a href="{{ page.baseurl }}/docs/running/categories_and_tags/">more about tags</a> for a little more information. </p> </td> @@ -258,12 +258,12 @@ a user may send a request to the wrong authority. In that situation, you can change the authority on the request and then resend it to the correct authority. To resend a request, go to -the <a href="{{ site.baseurl }}docs/glossary/#admin" +the <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Requests**, then click on the name of the request you want to change. Go to the **Outgoing messages** heading. Click the chevron next to the first outgoing message, which is the initial request. A panel of information about that message will appear. Click on the **Resend** button. To send a request to a different authority, go to -the <a href="{{ site.baseurl }}docs/glossary/#admin" +the <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Requests**, then click on the name of the request you want to change. In the **Request metadata** section, there is a line which shows the authority. Click the @@ -285,7 +285,7 @@ You can hide an entire request. Typically you do this if it's not a valid Freedom of Information request (for example, a request for personal information), or if it is vexatious. -Go to the <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>, +Go to the <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Requests**, then click on the title of the request you want. You can hide it in one of two ways: @@ -344,12 +344,12 @@ destroyed as well. <a href="#hiding-a-request">hide the request</a> instead. </div> -Go to the <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>, +Go to the <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Requests**, then click on the title of the request you want to delete. Click the **Edit metadata** button. Click on the red **Destroy request entirely** button at the bottom of the page. Responses to a deleted request will be sent to the -<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a>. +<a href="{{ page.baseurl }}/docs/glossary/#holding_pen" class="glossary__link">holding pen</a>. diff --git a/docs/running/server.md b/docs/running/server.md index da1312ac3..4a36aff41 100644 --- a/docs/running/server.md +++ b/docs/running/server.md @@ -25,7 +25,7 @@ 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/). +[installation instructions]({{ page.baseurl }}/docs/installing/manual_install/). ## Webserver configuration @@ -34,7 +34,7 @@ We recommend running your site behind [Passenger](https://www.phusionpassenger.com) or [Nginx](http://wiki.nginx.org/Main) + [Thin](http://code.macournoyer.com/thin/). If you're using Passenger, refer to the -[installation instructions]({{ site.baseurl }}docs/installing/manual_install/) +[installation instructions]({{ page.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 @@ -47,23 +47,23 @@ 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]({{ page.baseurl }}/docs/customising/config/) in `general.yml` from their default values. This includes (but may not be limited to!) these settings: -* [`INCOMING_EMAIL_SECRET`]({{ site.baseurl }}docs/customising/config/#incoming_email_secret) -* [`ADMIN_USERNAME`]({{ site.baseurl }}docs/customising/config/#admin_username) -* [`ADMIN_PASSWORD`]({{ site.baseurl }}docs/customising/config/#admin_password) -* [`COOKIE_STORE_SESSION_SECRET`]({{ site.baseurl }}docs/customising/config/#cookie_store_session_secret) -* [`RECAPTCHA_PUBLIC_KEY`]({{ site.baseurl }}docs/customising/config/#recaptcha_public_key) -* [`RECAPTCHA_PRIVATE_KEY`]({{ site.baseurl }}docs/customising/config/#recaptcha_private_key) +* [`INCOMING_EMAIL_SECRET`]({{ page.baseurl }}/docs/customising/config/#incoming_email_secret) +* [`ADMIN_USERNAME`]({{ page.baseurl }}/docs/customising/config/#admin_username) +* [`ADMIN_PASSWORD`]({{ page.baseurl }}/docs/customising/config/#admin_password) +* [`COOKIE_STORE_SESSION_SECRET`]({{ page.baseurl }}/docs/customising/config/#cookie_store_session_secret) +* [`RECAPTCHA_PUBLIC_KEY`]({{ page.baseurl }}/docs/customising/config/#recaptcha_public_key) +* [`RECAPTCHA_PRIVATE_KEY`]({{ page.baseurl }}/docs/customising/config/#recaptcha_private_key) You should consider running the admin part of the site over HTTPS. This can be achieved with rewrite rules that redirect URLs beginning with `/admin`. ## Email configuration -See the [configuration for exim or postfix]({{ site.baseurl }}docs/installing/email/) for +See the [configuration for exim or postfix]({{ page.baseurl }}/docs/installing/email/) for setting up your Mail Transfer Agent (MTA). It is possible to use other MTAs — if you use a different one, the documentation there should provide you with enough information to get started. If this applies to you, please add to the @@ -77,7 +77,7 @@ deliverability of your email: 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]( {{ page.baseurl }}/docs/installing/ami/) for more suggestions. ## Backup @@ -85,7 +85,7 @@ deliverability of your email: Most of the data for the site lives in the production database. The exception is the raw incoming email data, which is stored on the filesystem, as specified in the setting -[`RAW_EMAILS_LOCATION`]({{ site.baseurl }}docs/customising/config/#raw_emails_location) +[`RAW_EMAILS_LOCATION`]({{ page.baseurl }}/docs/customising/config/#raw_emails_location) setting in `config/general.yml`. Refer to the [Postgres diff --git a/docs/running/upgrading.md b/docs/running/upgrading.md index 81af8289f..39c18163c 100644 --- a/docs/running/upgrading.md +++ b/docs/running/upgrading.md @@ -8,14 +8,14 @@ Upgrading Alaveteli <p class="lead"> Alaveteli is under active development — 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>. + <a href="{{ page.baseurl }}/docs/glossary/#release" class="glossary__link">release</a>. This page describes how to keep your site up to date. </p> ## How to upgrade the code * If you're using Capistrano for deployment, - simply [deploy the code]({{site.baseurl}}docs/installing/deploy/#usage): + simply [deploy the code]({{ page.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 @@ -24,7 +24,7 @@ Upgrading Alaveteli ## Run the post-deploy script -Unless you're [using Capistrano for deployment]({{site.baseurl}}docs/installing/deploy/), +Unless you're [using Capistrano for deployment]({{ page.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. @@ -55,7 +55,7 @@ version numbering when it reaches `1.0.0`. 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__link">production +<a href="{{ page.baseurl }}/docs/glossary/#production" class="glossary__link">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). @@ -76,7 +76,7 @@ Patch version increases (e.g. 0.1.2.3 → 0.1.2.**4**) should not require any Minor version increases (e.g. 0.1.2.4 → 0.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. 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 <a href="{{ site.baseurl }}docs/glossary/#transifex" class="glossary__link">Transifex</a> +to the user that need translating to your locale. You should visit <a href="{{ page.baseurl }}/docs/glossary/#transifex" class="glossary__link">Transifex</a> 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 your website in English by default. If your translations didn't make it to the |