diff options
| -rw-r--r-- | community/index.md | 2 | ||||
| -rw-r--r-- | docs/customising/config.md | 6 | ||||
| -rw-r--r-- | docs/customising/themes.md | 4 | ||||
| -rw-r--r-- | docs/getting_started.md | 2 | ||||
| -rw-r--r-- | docs/glossary.md | 62 | ||||
| -rw-r--r-- | docs/installing/ami.md | 2 | ||||
| -rw-r--r-- | docs/installing/deploy.md | 18 | ||||
| -rw-r--r-- | docs/installing/index.md | 19 | ||||
| -rw-r--r-- | docs/installing/script.md | 2 | ||||
| -rw-r--r-- | docs/running/admin_manual.md | 6 | ||||
| -rw-r--r-- | docs/running/index.md | 2 | ||||
| -rw-r--r-- | docs/running/states.md | 4 | ||||
| -rw-r--r-- | docs/running/states_informatazyrtare.md | 2 | ||||
| -rw-r--r-- | docs/running/upgrading.md | 2 |
14 files changed, 71 insertions, 62 deletions
diff --git a/community/index.md b/community/index.md index f0497bb07..75ea435dd 100644 --- a/community/index.md +++ b/community/index.md @@ -14,7 +14,7 @@ The Alaveteli Community We actively help people set up and run Alaveteli instances all around the world. Alaveteli is more than just software, it's also a community of people who care enough about <a href="{{ site.baseurl}}docs/glossary/#foi" -class="glossary">Freedom of Information</a> to build and run sites to benefit +class="glossary__link">Freedom of Information</a> to build and run sites to benefit the public. If you're just starting out, or you've already got your site up and running, diff --git a/docs/customising/config.md b/docs/customising/config.md index 8a25e8df6..067c9ec92 100644 --- a/docs/customising/config.md +++ b/docs/customising/config.md @@ -638,9 +638,9 @@ THEME_URLS: </dt> <dd> Is this a - <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary">staging</a> or - <a href="{{site.baseurl}}docs/glossary/#development" class="glossary">development</a> site? - If not, it's a live <a href="{{site.baseurl}}docs/glossary/#production" class="glossary">production</a> + <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary__link">staging</a> or + <a href="{{site.baseurl}}docs/glossary/#development" class="glossary__link">development</a> site? + If not, it's a live <a href="{{site.baseurl}}docs/glossary/#production" class="glossary__link">production</a> site. This setting controls whether or not the <code>rails-post-deploy</code> script will create the file <code>config/rails_env.rb</code> file to force Rails into production environment. diff --git a/docs/customising/themes.md b/docs/customising/themes.md index bad1639d7..7db02f7eb 100644 --- a/docs/customising/themes.md +++ b/docs/customising/themes.md @@ -107,14 +107,14 @@ instead of the core "about us" file. ### Changing the logo Alaveteli uses Rails' [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) to convert and compress stylesheets written in -<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary">Sass</a>, +<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary__link">Sass</a>, the css extension language, to minified concatenated css. Assets are stored in core Alaveteli under `app/assets` - in `fonts`, `images`, `javascripts` and `stylesheets`. The default theme has corresponding asset directories in `alavetelitheme/assets` Asset files placed in these directories will override those in the core directories. As with templates, a file at `lib/themes/alavetelitheme/assets/images/logo.png` will appear on the site instead of the logo from `app/assets/images/logo.png`. ### Changing the colour scheme Alaveteli uses a set of basic -<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary">Sass</a> +<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary__link">Sass</a> modules to define the layout for the site on different device sizes, and some basic styling. These modules are in `app/assets/stylesheets/responsive`. The colours and fonts are added in the theme - alavetelitheme defines them in `lib/themes/alavetelitheme/assets/stylesheets/responsive/custom.scss`. Colours used in the theme are defined as variables at the top of this file and you can edit them here. ### Changing other styling diff --git a/docs/getting_started.md b/docs/getting_started.md index 615d7e818..eddcf78a6 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -141,7 +141,7 @@ can see what requests look like to them. When trying things out, you need to wear several hats -- as a site administrator, an ordinary site user, and as a public authority. This can get confusing with several email addresses, so one quick and easy way to manage -this is to use a throwaway email service like http://mailinator.com. +this is to use a throwaway email service like [Mailinator](http://mailinator.com). <a name="step-2"> </a> diff --git a/docs/glossary.md b/docs/glossary.md index d35454cbf..dd4076020 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -80,12 +80,12 @@ Definitions <a name="agnostic">asker agnostic</a> </dt> <dd> - <a href="#foi" class="glossary">Freedom of Information</a> (FoI) law typically considers - the <a href="#response" class="glossary">responses</a> given by the - <a href="#authority" class="glossary">authorities</a> to be <strong>asker agnostic</strong>. This means + <a href="#foi" class="glossary__link">Freedom of Information</a> (FoI) law typically considers + the <a href="#response" class="glossary__link">responses</a> given by the + <a href="#authority" class="glossary__link">authorities</a> to be <strong>asker agnostic</strong>. This means that the reply should not be any different depending on <em>who</em> asked for the information. One consequence of this is that the response - can be <a href="#publish" class="glossary">published</a>, because in theory <em>everyone</em> + can be <a href="#publish" class="glossary__link">published</a>, because in theory <em>everyone</em> could ask for it and expect, by law, to receive the same information. <p> Despite this, it's still very common all around the world for authorities to reply @@ -101,7 +101,7 @@ Definitions </dt> <dd> An <strong>authority</strong> is the term we use for any of the bodies, organisations, - departments, or companies to which users can send <a href="#request" class="glossary">requests</a>. + departments, or companies to which users can send <a href="#request" class="glossary__link">requests</a>. <div class="more-info"> <p>More information:</p> <ul> @@ -110,7 +110,7 @@ Definitions </li> <li> Authorities are usually, but not always, public bodies that are obliged by the local - <a href="#foi" class="glossary">Freedom of Information</a> (FoI) law to respond. Sometimes an + <a href="#foi" class="glossary__link">Freedom of Information</a> (FoI) law to respond. Sometimes an Alaveteli site is set up in a jurisdiction that does not yet have FoI law. In the UK, we add some authorites to our <a href="https://www.whatdotheyknow.com">WhaDoTheyKnow</a> site that are not subject to FoI law, but which have either voluntarily submitted themselves @@ -173,7 +173,7 @@ Definitions <dd> Alaveteli administrators can define <strong>censor rules</strong> to define which parts of replies or responses should be - <a href="#redact" class="glossary">redacted</a>. + <a href="#redact" class="glossary__link">redacted</a>. </p> <div class="more-info"> <p>More information:</p> @@ -200,9 +200,9 @@ Definitions so you can <a href="{{ site.baseurl }}docs/customising/">customise it</a>, experiment with different settings, and test that it does what you expect. This is different from a - <a href="#production" class="glossary">production server</a>, which is the one your + <a href="#production" class="glossary__link">production server</a>, which is the one your users actually visit running with live data, or a - <a href="#staging" class="glossary">staging server</a>, + <a href="#staging" class="glossary__link">staging server</a>, which is used for testing code before it goes live. <p> On your dev server, you should set @@ -293,7 +293,7 @@ Definitions <dd> A <strong>Mail Tranfer Agent</strong> is the the program which actually sends and receives email. Alaveteli sends email on behalf of its users, and processes - the <a href="#response" class="glossary">responses</a> and replies it receives. + the <a href="#response" class="glossary__link">responses</a> and replies it receives. All this email goes through the MTA, which is a seperate service on your system. <div class="more-info"> <p>More information:</p> @@ -311,7 +311,7 @@ Definitions </dt> <dd> Alaveteli can use <strong>New Relic</strong>'s application monitoring tool to track the - performance of your <a href="#production" class="glossary">production site</a>. If enabled, + performance of your <a href="#production" class="glossary__link">production site</a>. If enabled, data from your application is gathered on the New Relic website, which you can inspect with their visual tools. Basic use is free. <div class="more-info"> @@ -370,14 +370,14 @@ Definitions <dd> A <strong>production server</strong> is one that is running your Alaveteli site for real users, with live data. This is different from a - <a href="#development" class="glossary">development server</a>, which you use make your + <a href="#development" class="glossary__link">development server</a>, which you use make your customisation and environment changes and try to get them to all work OK, or a - <a href="#staging" class="glossary">staging server</a>, which is used for testing code + <a href="#staging" class="glossary__link">staging server</a>, which is used for testing code and configuration after it's been finished but before it goes live. <p> Your production site should be configured to run as efficiently as possible: for example, caching is enabled, and debugging switched off. - <a href="#rails" class="glossary">Rails</a> has a "production mode" which does + <a href="#rails" class="glossary__link">Rails</a> has a "production mode" which does this for you: set <code><a href="{{site.baseurl}}docs/customising/config/#staging_site">STAGING_SITE</a></code> to <code>0</code>. Note that if you <em>change</em> this setting after you've @@ -400,9 +400,9 @@ Definitions </dt> <dd> Alaveteli works by <strong>publishing</strong> the - <a href="#response" class="glossary">responses</a> it recieves to the - <a href="#foi" class="glossary">Freedom of Information</a> - <a href="#request" class="glossary">requests</a> that its users send. + <a href="#response" class="glossary__link">responses</a> it recieves to the + <a href="#foi" class="glossary__link">Freedom of Information</a> + <a href="#request" class="glossary__link">requests</a> that its users send. It does this by processing the emails it receives and presenting them as pages — one per request — on the website. This makes it easy for people to find, read, link to, and share the request and the @@ -459,7 +459,7 @@ Definitions </li> <li> you can do text-only redaction with Alaveteli's - <a href="#censor-rule" class="glossary">censor rules</a> + <a href="#censor-rule" class="glossary__link">censor rules</a> </li> <li> some things are easier to redact than others — especially in PDFs, @@ -477,8 +477,8 @@ Definitions A <strong>regular expression</strong> is a concise way to describe a pattern or sequence of characters, letters or words. As an administrator, you may find regular expressions useful if you need to define <a - href="#censor-rule" class="glossary">censor rules</a>. For example, instead - of <a href="#redact" class="glossary">redacting</a> just one specific + href="#censor-rule" class="glossary__link">censor rules</a>. For example, instead + of <a href="#redact" class="glossary__link">redacting</a> just one specific phrase, you can describe a whole range of <em>similar</em> phrases with one single regular expression. <p> @@ -545,11 +545,11 @@ Definitions </dt> <dd> In Alaveteli, a <strong>request</strong> is the - <a href="#foi" class="glossary">Freedom of Information</a> request + <a href="#foi" class="glossary__link">Freedom of Information</a> request that a user enters, and which the site then emails to the relevant - <a href="#authority" class="glossary">authority</a>. - Alaveteli automatically <a href="#publish" class="glossary">publishes</a> - the <a href="#response" class="glossary">responses</a> + <a href="#authority" class="glossary__link">authority</a>. + Alaveteli automatically <a href="#publish" class="glossary__link">publishes</a> + the <a href="#response" class="glossary__link">responses</a> to all the requests it sends. </dd> @@ -558,8 +558,8 @@ Definitions </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>. + <a href="#authority" class="glossary__link">authority</a> in reply to + a user's <a href="#request" class="glossary__link">requests</a>. </dd> <dt> @@ -591,7 +591,7 @@ Definitions language, and we use it because it's easier to manage than writing CSS directly (for example, Sass lets you easily make a single change that will be applied to many elements across the whole site). - <a href="#rails" class="glossary">Rails</a> notices if you change any of + <a href="#rails" class="glossary__link">Rails</a> notices if you change any of the Sass files, and automatically re-generates the CSS files that the website uses. <div class="more-info"> @@ -614,9 +614,9 @@ Definitions <dd> A <strong>staging server</strong> is one that you use for testing code or configuration before it goes live. This is different from a <a href="#development" - class="glossary">development server</a>, on which you change the code and settings to + class="glossary__link">development server</a>, on which you change the code and settings to make everything work, or the - <a href="#production" class="glossary">production server</a>, which is the + <a href="#production" class="glossary__link">production server</a>, which is the site your users visit running with live data. <p> On your staging server, you should set @@ -639,14 +639,14 @@ Definitions <a name="state">state</a> </dt> <dd> - Each <a href="#request" class="glossary">request</a> passes through different + Each <a href="#request" class="glossary__link">request</a> passes through different <strong>states</strong> as it progresses through the system. States help Alaveteli administrators, as well as the public, understand the current situation with any request and what action, if any, is required. <p> The states available can be customised within - your site's <a href="#theme" class="glossary">theme</a>. + your site's <a href="#theme" class="glossary__link">theme</a>. </p> <div class="more-info"> <p>More information:</p> diff --git a/docs/installing/ami.md b/docs/installing/ami.md index 1f7195761..e63e70023 100644 --- a/docs/installing/ami.md +++ b/docs/installing/ami.md @@ -1,6 +1,6 @@ --- layout: page -title: Installing the easy way +title: Installation from AMI --- # Installation on Amazon EC2 diff --git a/docs/installing/deploy.md b/docs/installing/deploy.md index e51adda31..c71c987bb 100644 --- a/docs/installing/deploy.md +++ b/docs/installing/deploy.md @@ -8,7 +8,8 @@ title: Deploying <p class="lead"> Although you can install Alaveteli and just change it when you need it, we recommend you adopt a way of <strong>deploying</strong> it automatically, - especially on your <a href="{{ site.baseurl }}docs/glossary/#production">production server</a>. + especially on your + <a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production server</a>. Alaveteli provides a deployment mechanism using Capistrano. </p> @@ -27,13 +28,13 @@ changes or copying files by hand, so your site will be down for the shortest possible time. We **strongly recommend** you use the deployment mechanism for your -<a href="{{ site.baseurl }}docs/glossary/#production">production server</a> and, if -you're running one, your -<a href="{{ site.baseurl }}docs/glossary/#staging">staging server</a> too. +<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production server</a> +and, if you're running one, your +<a href="{{ site.baseurl }}docs/glossary/#staging" class="glossary__link">staging server</a> too. ## Capistrano -<a href="{{site.baseurl}}docs/glossary/#capistrano" class="glossary">Capistrano</a> +<a href="{{site.baseurl}}docs/glossary/#capistrano" class="glossary__link">Capistrano</a> is included as part of Alaveteli as a standard deployment system. The basic principle of Capistrano is that you execute `cap [do-something]` @@ -94,7 +95,7 @@ Next, on your local machine: Back on the server: * copy the following config files from the temporary copy of Alaveteli you made at - the begining (perhaps in your home directory) to the `shared` directory that + the beginning (perhaps in your home directory) to the `shared` directory that Capistrano just created on the server: * `general.yml` * `database.yml` @@ -110,14 +111,15 @@ Back on the server: * `cache/` * `files/` * `lib/acts_as_xapian/xapiandbs` (copy this to straight into `shared` so it becomes `shared/xapiandbs`) + * `log/` Now, back on your local machine: * make sure you're still in the Alaveteli repo (if not, `cd` back into it) * run `cap -S stage=staging deploy:update_code` to get a code checkout on the server. * create a deployment directory on the server by running *one* of these commands: - * `cap deploy` if you're deploying a <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary">staging site</a>, or... - * `cap -S stage=production deploy` for <a href="{{site.baseurl}}docs/glossary/#production" class="glossary">production</a> + * `cap deploy` if you're deploying a <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary__link">staging site</a>, or... + * `cap -S stage=production deploy` for <a href="{{site.baseurl}}docs/glossary/#production" class="glossary__link">production</a> * update the webserver config (either apache or nginx) to add the `current` element to the path where it is serving Alaveteli from. If you installed using the installation script, this will be replacing `/var/www/alaveteli/alaveteli/` with diff --git a/docs/installing/index.md b/docs/installing/index.md index c276c3d08..50bcfd25a 100644 --- a/docs/installing/index.md +++ b/docs/installing/index.md @@ -6,17 +6,19 @@ title: Installing # Installing Alaveteli <p class="lead"> - Although you can install Alaveteli and just change it when you need it, we - recommend you adopt a way of <strong>deploying</strong> it automatically. - This has several advantages, especially for your - <a href="{{ site.baseurl }}docs/glossary/#production">production server</a>. + There are a number of ways to install Alaveteli. + We've made an Amazon Machine Image (AMI) so you can quickly deploy on + Amazon EC2 (handy if you just want to evaluate it, for example). + If you prefer to use your own server, there's an installation script + which does most of the work for you, or you can follow the manual + installation instructions. </p> ## Before you start This is important: you need to decide if you are installing Alaveteli for -[development]({{ site.baseurl }}docs/glossary/#development) or -[production]({{ site.baseurl }}docs/glossary/#production). +<a href="{{ site.baseurl }}docs/glossary/#development" class="glossary__link">development</a> or +<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production</a>. A **development** site is one where you're going to change, customise, and perhaps experiment while you get it up and running. You should always do this @@ -30,9 +32,10 @@ messages switched off. It's important to be able to deploy changes to a production site quickly and efficiently, so we recommend you consider using a [deployment mechanism]({{ site.baseurl }}docs/installing/deploy/) too. -Ideally, you should also have a [staging site]({{ site.baseurl }}docs/glossary/#staging), +Ideally, you should also have a +<a href="{{ site.baseurl }}docs/glossary/#staging" class="glossary__link">staging site</a>, which is used solely to test new code in an identical environment to your -production site but before it goes live. +production site before it goes live. If you're in doubt, you're probably running a development site. Get it up and running, play with it, customise it, and -- later -- you can install it as a diff --git a/docs/installing/script.md b/docs/installing/script.md index b8b678a0a..0d826ac8a 100644 --- a/docs/installing/script.md +++ b/docs/installing/script.md @@ -1,6 +1,6 @@ --- layout: page -title: Installing the easy way +title: Installation script --- # Installation script diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md index cde828c9a..567e6cf5e 100644 --- a/docs/running/admin_manual.md +++ b/docs/running/admin_manual.md @@ -6,7 +6,11 @@ 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="https://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__link">Freedom of Information</a> site, <a + href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>. </p> ## What's involved? diff --git a/docs/running/index.md b/docs/running/index.md index 90461fb3e..d6225ac61 100644 --- a/docs/running/index.md +++ b/docs/running/index.md @@ -11,7 +11,7 @@ title: Running </p> Alaveteli is not just software. To run a successful -<a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary">Freedom of Information</a> +<a href="{{ site.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. diff --git a/docs/running/states.md b/docs/running/states.md index 1c3fb217e..40e8a1a5b 100644 --- a/docs/running/states.md +++ b/docs/running/states.md @@ -6,14 +6,14 @@ title: States of requests # Request states <p class="lead"> - A <a href="{{site.baseurl}}docs/glossary/#request" class="glossary">request</a> + A <a href="{{site.baseurl}}docs/glossary/#request" class="glossary__link">request</a> passes through different <strong>states</strong> as it is processed. These may vary from one jurisdiction to another. </p> 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 +class="glossary__link">FOI law</a> in your own jurisdiction). But if you do need to customise them, you can — see <a href="{{ site.baseurl }}docs/customising/themes/">Customising the request states</a> for details. diff --git a/docs/running/states_informatazyrtare.md b/docs/running/states_informatazyrtare.md index bd5ff1a1c..28711643b 100644 --- a/docs/running/states_informatazyrtare.md +++ b/docs/running/states_informatazyrtare.md @@ -14,7 +14,7 @@ title: States of requests (InformataZyrtare) 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). +class="glossary__link">FOI law</a> in your own jurisdiction). ## InformataZyrtare.org (Kosovo) example diff --git a/docs/running/upgrading.md b/docs/running/upgrading.md index 2142bfd47..ab8db2385 100644 --- a/docs/running/upgrading.md +++ b/docs/running/upgrading.md @@ -17,7 +17,7 @@ Upgrading Alaveteli 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 +<a href="{{site.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). |