Merge branch 'gh-pages' of ssh://git.mysociety.org/data/git/public/alaveteli into gh-pages

1 files changed, 43 insertions, 18 deletions

diff --git a/docs/installing/deploy.md b/docs/installing/deploy.md
index 4bbc91a9d..74c7a8560 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]`
@@ -68,7 +69,11 @@ and thereafter you'll be able to deploy very easily (see [usage, below](#usage))
 First, on the server:
 
 * [install Alaveteli]({{ site.baseurl }}docs/installing/)
-* then move the Alaveteli app to a temporary place on the server, like your home
+* give the Unix user that runs Alaveteli the ability to ssh to your server. Either give them a password or, preferably, set up ssh keys for them so they can ssh from your local machine to the server:
+   * to give them a password (if they don't already have one) - `sudo passwd [UNIX-USER]`. Store this password securely on your local machine e.g in a password manager
+   * to set up ssh keys for them, follow the instructions in the [capistrano documentation](http://capistranorb.com/documentation/getting-started/authentication-and-authorisation/). There's no need to set up ssh keys to the git repository as it is public.
+* make sure the Unix user that runs Alaveteli has write permissions on the parent directory of your Alaveteli app
+* 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)
 
@@ -82,20 +87,28 @@ Next, on your local machine:
   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`.
+* 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/[HOST or alaveteli]/alaveteli`. Set
+  `daemon_name` to the name you used in setting up the [application
+  daemon]({{ site.baseurl }}docs/installing/manual_install/#generate-application-daemon). The
+  default should be `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
+
+If you get an error `SSH::AuthenticationFailed`, and are not prompted for the password of the deployment user, you may have run into [a bug](http://stackoverflow.com/questions/21560297/capistrano-sshauthenticationfailed-not-prompting-for-password) in the net-ssh gem version 2.8.0. Try installing version 2.7.0 instead:
+
+    gem uninstall net-ssh
+
+    gem install net-ssh -v 2.7.0
 
 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,17 +123,23 @@ Back on the server:
   `shared` directory created by Capistrano 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>
+
+Back on the server:
+
 * 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`.
+  `/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`.
@@ -130,7 +149,13 @@ Now, back on your local machine:
   `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.
+  to update the `ALAVETELI_HOME` variable to the new Alaveteli path. Restart the MTA after you've made these changes.
+
+* You will also need to update the path to Alaveteli in your [init scripts]({{site.baseurl}}docs/installing/manual_install/#cron-jobs-and-init-scripts).
+  You should have a script for running the alert tracks
+  (`/etc/init.d/foi-alert-tracks`), and possibly scripts for purging the
+  varnish cache (`/etc/init.d/foi-purge-varnish`), and restarting the
+  app server (`/etc/init.d/alaveteli`).
 
 Phew, you're done!
 
@@ -146,7 +171,7 @@ 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/).
+version in a private [Gist](http://gist.github.com/).
 
 * to deploy to staging, just run `cap deploy`
 * to deploy to production, run `cap -S stage=production deploy`