Merge branch 'gh-pages-deploy-docs' into gh-pages

5 files changed, 328 insertions, 12 deletions

diff --git a/_layouts/page.html b/_layouts/page.html
index d2952cec4..495a7cd93 100644
--- a/_layouts/page.html
+++ b/_layouts/page.html
@@ -21,6 +21,7 @@ layout: default
           <li><a href="{{ site.baseurl }}getting_started">Getting Started</a></li>
           <li><a href="{{ site.baseurl }}installing/">Installing</a>
             <ul>
+              <li><a href="{{ site.baseurl }}installing/deploy">Deploying</a></li>
               <li><a href="{{ site.baseurl }}installing/script">Install script</a></li>
               <li><a href="{{ site.baseurl }}installing/ami">Alaveteli AMI for EC2</a></li>
               <li><a href="{{ site.baseurl }}installing/manual_install">Installing by hand</a></li>
diff --git a/customising/config.md b/customising/config.md
index 259ba7f00..ef3cb720d 100644
--- a/customising/config.md
+++ b/customising/config.md
@@ -637,15 +637,27 @@ THEME_URLS:
     <a name="staging_site"><code>STAGING_SITE</code></a>
   </dt>
   <dd>
-     Is this a staging or development site (1) or a live (production) site (0)?
-     This controls whether or not the <code>rails-post-deploy</code> script
-     will create the file <code>config/rails_env.rb</code> file to force
+     Is this a
+     <a href="{{site.baseurl}}glossary/#staging" class="glossary">staging</a> or
+     <a href="{{site.baseurl}}glossary/#development" class="glossary">development</a> site?
+     If not, it's a live <a href="{{site.baseurl}}glossary/#production" class="glossary">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.
     <div class="more-info">
-      <p>Example:</p>
+      <p>Examples:</p>
       <ul class="examples">
         <li>
-            <code>STAGING_SITE: 1</code>
+            For staging or development:
+            <p>
+              <code>STAGING_SITE: 1</code>
+            </p>
+        </li>
+        <li>
+            For production:
+            <p>
+              <code>STAGING_SITE: 0</code>
+            </p>
         </li>
       </ul>
     </div>
diff --git a/glossary.md b/glossary.md
index d641f7451..25a3034bc 100644
--- a/glossary.md
+++ b/glossary.md
@@ -18,15 +18,19 @@ Definitions
   <li><a href="#alaveteli">Alaveteli</a></li>
   <li><a href="#agnostic">asker agnostic</a></li>
   <li><a href="#authority">authority</a></li>
+  <li><a href="#capistrano">Capistrano</a></li>
+  <li><a href="#development">development site</a></li>
   <li><a href="#foi">freedom of information</a></li>
   <li><a href="#git">git</a></li>
   <li><a href="#holding_pen">holding pen</a></li>
   <li><a href="#mta">MTA</a></li>
+  <li><a href="#production">production site</a></li>
   <li><a href="#publish">publish</a></li>
   <li><a href="#request">request</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>
+  <li><a href="#staging">staging site</a></li>
   <li><a href="#state">state</a></li>
   <li><a href="#theme">theme</a></li>
 </ul>
@@ -107,6 +111,46 @@ Definitions
   </dd>
 
   <dt>
+    <a name="capistrano">Capistrano</a>
+  </dt>
+  <dd>
+	  <strong>Capistrano</strong> is a remote server automation and deployment tool written in Ruby.
+    Alaveteli's deployment mechanism, which is optional, uses it. 
+    <div class="more-info">
+      <p>More information:</p>
+      <ul>
+        <li>
+          how to <a href="{{ site.baseurl }}installing/deploy">deploy Alaveteli</a> (and why it's
+          a good idea)
+        </li>
+        <li>
+         The <a href="http://capistranorb.com/">Capistrano website</a> has thorough documentation
+         about the tool
+        </li>
+      </ul>
+    </div>
+  </dd>
+
+  <dt>
+    <a name="development">development site</a> (also: dev, development server)
+  </dt>
+  <dd>
+    A <strong>dev server</strong> is one that is running your Alaveteli site
+    so you can <a href="{{ site.baseurl }}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
+    users actually visit running with live data, or a
+    <a href="#staging" class="glossary">staging server</a>,
+    which is used for testing code before it goes live.
+    <p>
+      On your dev server, you should set
+      <code><a href="{{site.baseurl}}customising/config/#staging_site">STAGING_SITE</a></code>
+      to <code>1</code>.
+    </p>
+  </dd>
+
+  <dt>
     <a name="foi">Freedom of Information</a> (also FOI)
   </dt>
   <dd>
@@ -203,6 +247,37 @@ Definitions
   </dd>
 
   <dt>
+    <a name="production">production site</a> (also: live, production server)
+  </dt>
+  <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
+    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
+    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
+      this for you: set
+      <code><a href="{{site.baseurl}}customising/config/#staging_site">STAGING_SITE</a></code>
+      to <code>0</code>. Note that if you <em>change</em> this setting after you've
+      deployed, the <code>rails_env.rb</code> file that enables Rails's production
+      mode won't be created until you run <code>rails-post-deploy</code>.
+    <p>
+      If you have a staging server, the system environment of your staging and
+      production servers should be identical.
+    </p>
+    <p>
+      You should never need to edit code directly on your production server.
+      We strongly recommend you use Alaveteli's 
+      <a href="{{ site.baseurl }}installing/deploy/">deployment mechanism</a>
+      (using Capistrano) to make changes to your production site.
+    </p>
+  </dd>
+
+  <dt>
     <a name="publish">publish</a>
   </dt>
   <dd>
@@ -286,6 +361,33 @@ Definitions
   </dd>
 
   <dt>
+    <a name="staging">staging server</a> (also: staging site)
+  </dt>
+  <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
+    make everything work, or the
+    <a href="#production" class="glossary">production server</a>, which is the
+    site your users visit running with live data.
+    <p>
+      On your staging server, you should set
+      <code><a href="{{site.baseurl}}customising/config/#staging_site">STAGING_SITE</a></code>
+      to <code>1</code>.
+    </p>
+    <p>
+      If you have a staging server, the system environment of your staging and
+      production servers should be identical.
+    </p>
+    <p>
+      You should never need to edit code directly on your production or staging servers.
+      We strongly recommend you use Alaveteli's 
+      <a href="{{ site.baseurl }}installing/deploy/">deployment mechanism</a>
+      (using Capistrano) to make changes to these sites.
+    </p>
+  </dd>
+
+  <dt>
     <a name="state">state</a>
   </dt>
   <dd>
diff --git a/installing/deploy.md b/installing/deploy.md
new file mode 100644
index 000000000..32755a71d
--- /dev/null
+++ b/installing/deploy.md
@@ -0,0 +1,167 @@
+---
+layout: page
+title: Deploying
+---
+
+# Deploying 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,
+  especially on your <a href="{{ site.baseurl }}glossary/#production">production server</a>.
+  Alaveteli provides a deployment mechanism using Capistrano.
+</p>
+
+## Why deploy?
+
+Although you can [install Alaveteli]({{ site.baseurl }}installing/) in a number
+of ways, once you're running, sooner or later you'll need to make changes to
+the site. A common example is updating your site when we issue a new release.
+
+The deployment mechanism takes care of putting all the right files into the
+right place, so when you need to put changes live, there's no risk of you
+forgetting the update all the files you've changed, or breaking the
+configuration by accident. Instead, deployment does all this for you
+automatically. It's also more efficient because it is faster than making
+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 }}glossary/#production">production server</a> and, if
+you're running one, your 
+<a href="{{ site.baseurl }}glossary/#staging">staging server</a> too.
+
+## Capistrano
+
+<a href="{{site.baseurl}}glossary/#capistrano" class="glossary">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]`
+commands on your local machine, and Capistrano connects to your server (using
+`ssh`) and does the corresponding task there for you.
+
+### Set up
+
+Capistrano requires things to be set up at both ends -- that is, on the server
+where you want Alaveteli to run, and on your own local machine.
+
+* *the server* is the machine that will be running the Alaveteli
+  instance you're deploying
+
+* your *local machine* may be your laptop or similar device -- as well as those
+  belonging to anyone in your team whom you want to be able to deploy
+
+In order to allow the Capistrano deployment mechanism work, you need to set up
+the server so that the Alaveteli app is being served from a directory called
+`current`. Once you've done that, deploying a new version is essentially
+creating a timestamped sister directory to the `current` directory, and
+switching the symlink `current` from the old timestamped directory to the new
+one. Things that need to persist between deployments, like config files, are
+kept in a `shared` directory that is at the same level, and symlinked-to from
+each timestamped deploy directory.
+
+We're [working on making this easier](https://github.com/mysociety/alaveteli/issues/1596),
+but for now, here's the manual process you need to follow to set up this
+deployment mechanism. Remember, you only have to do this once to set it up,
+and thereafter you'll be able to deploy very easily (see [usage, below](#usage)).
+
+First, on the server:
+
+* [install Alaveteli]({{ site.baseurl }}installing/)
+* then move the Alaveteli app to a temporary place on the server, like your home
+  directory (temporarily, your site will be missing, until the deployment puts
+  new files in place)
+
+Next, on your local machine:
+
+* install Capistrano:
+   * 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
+  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`
+* now customise the deployment settings in that file: edit `config/deploy.yml`
+  appropriately -- for example, edit the name of the server. Also, change
+  `deploy_to` to be the path where Alaveteli is currently installed on the
+  server -- if you used the installation script, this will be
+  `/var/www/alaveteli/alaveteli`.
+* `cd` into the Alaveteli repo you checked out (otherwise the `cap` commands you're about to 
+  execute won't work)
+* still on your local machine, run `cap -S stage=staging deploy:setup` to setup capistrano on the server
+* again on your local machine, run `cap -S stage=staging  deploy:update_code` to get a code checkout on the server
+
+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
+  Capistrano just created on the server:
+   * `general.yml`
+   * `database.yml`
+   * `rails_env.rb`
+   * `newrelic.yml`
+   * `aliases` &larr; if you're using Exim as your MTA
+* if you're using Exim as your MTA, edit the `aliases` file you just copied across
+  so that the path to Alaveteli includes the `current` element. If it was
+  `/var/www/alaveteli/alaveteli/script/mailin`, it should now be
+  `/var/www/alaveteli/alaveteli/current/script/mailin`.
+* copy the following directories from your temporary copy of Alaveteli to the
+  `shared` directory created by Capistrano on the server:
+   * `cache/`
+   * `files/`
+
+Now, back on your local machine:
+
+* make sure you're still in the Alaveteli repo (if not, `cd` back into it)
+* create a deployment directory on the server by running *one* of these commands:
+   * `cap deploy` if you're deploying a <a href="{{site.baseurl}}glossary/#staging" class="glossary">staging site</a>, or...
+   * `cap -S stage=production deploy` for <a href="{{site.baseurl}}glossary/#production" class="glossary">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
+  `/var/www/alaveteli/alaveteli/current` in `etc/nginx/sites-available/default`.
+* edit the server crontab so that the paths in the cron jobs also include the 
+  `current` element. If you used the installation script the crontab will be in
+  `etc/cron.d/alaveteli`.
+* Update the MTA config to include the `current` element in the paths it uses.
+  If you installed using the installation script, the MTA will be postfix,
+  and you will need to edit  `/etc/postfix/master.cf` to replace
+  `argv=/var/www/alaveteli/alaveteli/script/mailin` with
+  `argv=/var/www/alaveteli/alaveteli/current/script/mailin`.
+  If you're using Exim as your MTA, edit `etc/exim4/conf.d/04_alaveteli_options`
+  to update the `ALAVETELI_HOME` variable to the new Alaveteli path. 
+
+Phew, you're done! 
+
+You can delete the temporary copy of Alaveteli (perhaps in your
+home directory) now.
+
+### Usage
+
+Before you issue any Capistrano commands, `cd` into the checkout of the 
+Alaveteli repo on your local machine (because that's where it will look
+for the config that you've set up).
+
+Ensure you've got a `config/deploy.yml` file with the correct settings for your
+site. If there are other people in your team who need to deploy, you'll need to
+share it with them too -- it might be a good idea to keep the latest
+version in a [Gist](http://gist.github.com/).
+
+* to deploy to staging, just run `cap deploy`
+* to deploy to production, run `cap -S stage=production deploy`
+
+You might notice that, after deploying, the old deploy directory is still there
+-- that is, the one that was `current` until you replaced it with the new one.
+By default, the deploy mechanism keeps the last five deployments there. Run
+`cap deploy:cleanup` to tidy up older versions.
+
+For additional usage instructions, see the [Capistrano
+website](http://capistranorb.com/).
+
+### Whoops, that's not what I expected
+
+If a deployment goes wrong, or you discover after doing it that you're not
+ready for the latest version after all, don't panic! Run `cap deploy:rollback`
+and it will switch `current` back to the previous deployment.
+
diff --git a/installing/index.md b/installing/index.md
index 32ed821ea..09af57a48 100644
--- a/installing/index.md
+++ b/installing/index.md
@@ -6,23 +6,57 @@ title: Installing
 # Installing Alaveteli
 
 <p class="lead">
-
-	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.
+  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 }}glossary/#production">production server</a>.
 </p>
 
+## Before you start
+
+This is important: you need to decide if you are installing Alaveteli for
+[development]({{ site.baseurl }}glossary/#development) or
+[production]({{ site.baseurl }}glossary/#production).
+
+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
+first. In this environment you can see debug messages, and you don't need to
+worry too much about the efficiency and performance of the site (because it's
+not really getting lots of traffic).
+
+A **production** site is different: you want your production site to run as
+efficiently as possible, so things like caching are swiched on, and debug
+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 }}installing/deploying/) too.
+
+Ideally, you should also have a [staging site]({{ site.baseurl }}glossary/#staging),
+which is used solely to test new code in an identical environment to your
+production site but 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
+production server.
+
+## Deployment
+
+If you're running a production server, we **strongly recommend** you
+use the Capistrano [deployment mechanism]({{ site.baseurl }}installing/deploy/)
+that's included with Alaveteli. Set this up and you never have to edit files on
+those servers, because Capistrano takes care of that for you.
+
 ## Installing the core code
 
 * [Install on Amazon EC2]({{ site.baseurl }}installing/ami) using our AMI
 * [Use the installation script]({{ site.baseurl }}installing/script) which does the full installation on your own server
 * [Manual installation]({{ site.baseurl }}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 }}installing/macos).
+If you're setting up a development server on MacOS X, we've also got
+[MacOS installation instructions]({{ site.baseurl }}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.
+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 }}installing/email)
-
-