Merge branch 'dave-mexico-install-docs' into gh-pages

4 files changed, 275 insertions, 55 deletions

diff --git a/docs/customising/config.md b/docs/customising/config.md
index 906af3702..8778b2edd 100644
--- a/docs/customising/config.md
+++ b/docs/customising/config.md
@@ -71,7 +71,7 @@ indentation correct. If in doubt, look at the examples already in the file, and
 
 <code><a href="#admin_username">ADMIN_USERNAME</a></code>
 <br> <code><a href="#admin_password">ADMIN_PASSWORD</a></code>
-<br> <code><a href="#admin_username">DISABLE_EMERGENCY_USER</a></code>
+<br> <code><a href="#disable_emergency_user">DISABLE_EMERGENCY_USER</a></code>
 <br> <code><a href="#skip_admin_auth">SKIP_ADMIN_AUTH</a></code>
 
 ### Email management:
@@ -499,10 +499,25 @@ THEME_URLS:
     &amp;
     <a name="admin_password"><code>ADMIN_PASSWORD</code></a>
     <br>
-    <a name="admin_username"><code>DISABLE_EMERGENCY_USER</code></a>
+    <a name="disable_emergency_user"><code>DISABLE_EMERGENCY_USER</code></a>
   </dt>
   <dd>
-      The emergency user.
+      Details for the 
+      <a href="{{site.baseurl}}docs/glossary/#emergency" class="glossary__link">emergency user</a>.
+      <p>
+        This is useful for creating the initial admin users for your site:
+        <ul>
+          <li>Create a new user (using regular sign up on the site)</li>
+          <li>Log in as the emergency user</li>
+          <li>Promote the new account</li>
+          <li>Disable the emergency user</li>
+        </ul>
+      </p>
+      <p>
+        For details of this process, see
+        <a href="{{site.baseurl}}docs/installing/next_steps/#create-a-superuser-admin-account">creating
+          a superuser account</a>.
+      </p>
     <div class="more-info">
       <p>Examples:</p>
       <ul class="examples">
diff --git a/docs/glossary.md b/docs/glossary.md
index 0029cdc24..b5239a32a 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -23,6 +23,7 @@ Definitions
   <li><a href="#capistrano">Capistrano</a></li>
   <li><a href="#censor-rule">censor rule</a></li>
   <li><a href="#development">development site</a></li>
+  <li><a href="#emergency">emergency user</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>
@@ -231,6 +232,40 @@ Definitions
   </dd>
 
   <dt>
+    <a name="emergency">emergency user</a>
+  </dt>
+  <dd>
+    Alaveteli ships with a configuration setting for an <strong>emergency user</strong>.
+    This provides a username and password you can use to access the admin, even though
+    the user doesn't appear in the database.
+    <p>
+      When the system has been bootstrapped (that is, you've used the emergency user to
+      grant a user account full <em>super</em> privileges), you must disable the emergency
+      user.
+    </p>
+    <div class="more-info">
+      <p>More information:</p>
+      <ul>
+        <li>
+          The username and password are defined by the configuration settings
+          <code><a href="{{site.baseurl}}docs/customising/config/#admin_username">ADMIN_USERNAME</a></code>
+          and 
+          <code><a href="{{site.baseurl}}docs/customising/config/#admin_password">ADMIN_PASSWORD</a></code>.
+        </li>
+        <li>
+          For an example of using the emergency user, see
+          <a href="{{site.baseurl}}docs/installing/next_steps/#create-a-superuser-account-for-yourself">creating
+            a superuser account</a>.
+        </li>
+        <li>
+          Disable the emergency user by setting
+          <code><a href="{{site.baseurl}}docs/customising/config/#disable_emergency_user">DISABLE_EMERGENCY_USER:</a> true</code>
+        </li>
+      </ul>
+    </div>
+  </dd>
+
+  <dt>
     <a name="foi">Freedom of Information</a> (also FOI)
   </dt>
   <dd>
diff --git a/docs/installing/ami.md b/docs/installing/ami.md
index 774b48133..7008155f9 100644
--- a/docs/installing/ami.md
+++ b/docs/installing/ami.md
@@ -6,58 +6,155 @@ title: Installation from AMI
 # Installation on Amazon EC2
 
 <p class="lead">
-  We've made an Amazon Machine Image (AMI) so you can quickly deploy on Amazon EC2. This is handy if you just want to evaluate Alaveteli, for example.
+  We've made an Amazon Machine Image (AMI) so you can quickly deploy on Amazon
+  EC2. This is handy if you just want to evaluate Alaveteli, for example.
 </p>
 
 Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing/).
 
 ## Installing from our AMI
 
-To help people try out Alaveteli, we have created an AMI (Amazon Machine
-Image) with a basic installation of Alaveteli (installed using the
-[installation script]({{ site.baseurl }}docs/installing/script/)), which
-you can use to create a running server on an Amazon EC2 instance. This
-creates an instance that runs in development mode, so we wouldn't
-recommend you use it for a production system without changing the
-configuration.
-
-Unfortunately, Alaveteli will not run properly on a free Micro
-instance due to the low amount of memory available on those
-instances; you will need to use at least a Small instance, which
-Amazon will charge for.
-
-The AMI can be found in the EU West (Ireland) region, with the ID `ami-baf351cd`
-and name “Basic Alaveteli installation 2014-10-06”. You can launch an instance
-based on that AMI with [this
-link](https://console.aws.amazon.com/ec2/home?region=eu-west-1#launchAmi=ami-baf351cd).
-
-When you create an EC2 instance based on that AMI, make sure that you choose
-Security Groups that allows at least inbound HTTP, HTTPS, SSH and, if you want
-to test incoming mail as well, SMTP.
-
-When your EC2 instance is launched, you will be able to log in as the `ubuntu`
-user. This user can `sudo` freely to run commands as root. However, the code is
-actually owned by (and runs as) the `alaveteli` user. After creating the
-instance, you may want to edit a configuration file to customize the site's
-configuration. That configuration file is
-`/var/www/alaveteli/alaveteli/config/general.yml`, which can be edited with:
+To help you try out Alaveteli, we have created an AMI with a basic installation
+of Alaveteli, which you can use to create a running server on an Amazon EC2
+instance. This creates an instance that runs as a
+<a href="{{ site.baseurl }}docs/glossary/#development" class="glossary__link">development site</a>.
+If you want to use this for a 
+<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production site</a>,
+you must
+[change the configuration]({{ site.baseurl }}docs/customising/config/#staging_site).
+
+<div class="attention-box">
+  <p>
+    <strong>What's in the AMI?</strong>
+    The AMI gives you exactly the same thing as the 
+    <a href="{{ site.baseurl}}docs/installing/script/">installation script</a>
+    does. You get an Alaveteli website powered by Rails running the Thin
+    application server under nginx, using a postgreSQL database. All this
+    running on Amazon's EC2 servers, ready to be
+    <a href="{{ site.baseurl }}docs/customising/">configured and customised</a>.
+  </p>
+</div>
+
+Amazon instances are graded by size. Unfortunately, the *Micro* instance does
+not have enough memory for Alaveteli to run -- and that's the only size
+available on Amazon's free usage tier. You need to use a *Small* instance or
+larger, which Amazon will charge you for.
+
+### Using Amazon web services
+
+To do this, you'll need:
+
+   * an account with Amazon
+   * a SSL key pair (the Amazon web service screens guide you through this)
+
+If you don't have these already, you'll need to create them. See Amazon's
+introduction on
+[running a Virtual Server on AWS](http://docs.aws.amazon.com/gettingstarted/latest/awsgsg-intro/gsg-aws-virtual-server.html).
+
+### Launch the instance
+
+Once you're logged in to Amazon's service, and navigated to the **EC2
+Management Console**, you can launch the instance. If you prefer to do this
+manually, you can find the AMI in the "EU West (Ireland)" region, with the ID
+`ami-baf351cd` and name “Basic Alaveteli installation 2014-10-06”.
+Alternatively, use this link:
+
+<p class="action-buttons">
+  <a href="https://console.aws.amazon.com/ec2/home?region=eu-west-1#launchAmi=ami-baf351cd" class="button">launch
+  instance with Alaveteli installation AMI</a> 
+</p>
+
+When the instance launches, the first thing you need to choose is the instance
+*type*. Remember that the *Micro* type does not have enough memory to run
+Alaveteli, so you must choose at least *Small* or *Medium* -- note that these
+are not available on Amazon's free usage tier.
+
+When the instance is created, the Amazon interface presents you with a lot of
+choices about its configuration. You can generally accept the defaults for
+everything, except the Security Groups. It's safe to click on **Review and
+Launch** right away (rather than manually configuring all the instance details)
+because you still get an opportunity to configure the security groups. Click on
+**Edit Security Groups** on the summary page before you hit the big **Launch**
+button.
+
+You must choose Security Groups that allow at least inbound HTTP, HTTPS, SSH
+and, if you want to test incoming mail as well, SMTP. Amazon's settings here
+let you specify the IP address(es) from which your instance will accept
+requests. It's good practice to restrict these (if in doubt, choose a *Source*
+of "My IP" for them all -- except incoming HTTP: for that, simpy to set
+*Source* to "Anywhere"). You can change any of these settings later if you need
+to.
+
+### Log into the server (shell)
+
+You need access to the server's command line shell to control and configure
+your Alaveteli site.
+
+To access the server, use `ssh` and the `.pem` file from your SSL key pair.
+Change the `.pem` file and instance ID to match your own in this command, which
+connects to your server and logs you in as the user called `ubuntu`. Issue this
+command from your own machine, to log in to the server:
+
+    ssh -i path-to/your-key-pair.pem ubuntu@instance-id.eu-west-1.compute.amazonaws.com
+
+You won't be asked for a password, because the `.pem` file you supply with the
+`-i` option contains the authorisation that matches the one at the other end,
+on the server. You will be logged into the shell on your new Alaveteli server,
+and can issue Unix commands to it.
+
+### Smoke test: start Alavateli
+
+You must configure your Alavateli site, but if you just want to see that you've
+got your instance running OK, you *can* fire it up right away. Ideally, you
+should skip this step and go straight to the configuration... but we know most
+people like to see something in their browser first. ;-)
+
+On the command line shell, as the `ubuntu` user, start Alaveteli by doing:
+
+    sudo service alaveteli start
+
+Find the "public DNS" URL of your EC2 instance from the AWS console, and look
+at it in a browser. It will be of the form
+`http://your-ec2-hostname.eu-west-1.compute.amazonaws.com`. You'll see your
+Alaveteli site there.
+
+Your site isn't configured yet, so *this is insecure* (for example, you haven't
+set your own passwords for access to the administration yet), so once you've
+seen this running, bring the Alaveteli site down with:
+
+    sudo service alaveteli stop
+
+
+### Shell users: `ubuntu` and `alaveteli`
+
+When you log into your instance's command line shell, you must do so as the
+`ubuntu` user. This user can `sudo` freely to run commands as root. However,
+the code is actually owned by (and runs as) the `alaveteli` user.
+
+You will need to 
+[customise the site's configuration]({{ site.baseurl }}docs/customising/config/).
+Do this by logging into your EC2 server and editing the `general.yml`
+configuration file.
+
+The configuration file you need to edit is
+`/var/www/alaveteli/alaveteli/config/general.yml`. For example, use the `nano`
+editor (as the `alaveteli` user) like this:
 
     ubuntu@ip-10-58-191-98:~$ sudo su - alaveteli
     alaveteli@ip-10-58-191-98:~$ cd alaveteli
     alaveteli@ip-10-58-191-98:~/alaveteli$ nano config/general.yml
 
-Then you should restart the Thin webserver with:
+After making changes to that file, you'll need to start the application
+server (use `restart` rather than `start` if it's already running):
 
     alaveteli@ip-10-58-191-98:~/alaveteli$ logout
-    ubuntu@ip-10-58-191-98:~$ sudo /etc/init.d/alaveteli restart
+    ubuntu@ip-10-58-191-98:~$ sudo service alaveteli start
+
+Your site will be running at the public URL again, which is of the form
+`http://your-ec2-hostname.eu-west-1.compute.amazonaws.com`.
 
-If you find the hostname of your EC2 instance from the AWS console, you should
-then be able to see the site at
-`http://your-ec2-hostname.eu-west-1.compute.amazonaws.com`
+If you have any problems or questions, please ask on the [Alaveteli developer mailing list](https://groups.google.com/forum/#!forum/alaveteli-dev) or [report an issue](https://github.com/mysociety/alaveteli/issues?state=open).
 
-If you have any problems or questions, please ask on the [Alaveteli Google
-Group](https://groups.google.com/forum/#!forum/alaveteli-dev) or [report an
-issue](https://github.com/mysociety/alaveteli/issues?state=open).
 
 ##What next?
 
diff --git a/docs/installing/next_steps.md b/docs/installing/next_steps.md
index 146b0dad9..4199daabf 100644
--- a/docs/installing/next_steps.md
+++ b/docs/installing/next_steps.md
@@ -8,36 +8,109 @@ title: Next Steps
     OK, you've installed a copy of Alaveteli, and can see the site in a browser. What next?
 </p>
 
+## Create a superuser admin account
+
+Alaveteli ships with an
+<a href="{{site.baseurl}}docs/glossary/#emergency" class="glossary__link">emergency user</a>
+that has access to the admin. So when you've just created a new site, you
+should sign up to create your own account, then log into admin as the emergency
+user to promote your new account to be an administrator with *super* privileges.
+
+As soon as that's done, disable the emergency user, because you don't need to
+use it any more: you've superseded it with your new admin account.
+
+Alaveteli ships with sample data that includes a dummy admin user called "Joe
+Admin". If the sample data has been loaded into the database (this will depend on
+how you installed), you must revoke Joe's administrator status too, because you
+will be using your own admin account instead.
+
+### Step-by-step:
+
+First, in the browser:
+
+* Go to `/profile/sign_in` and create a user by signing up.
+* Check your email and confirm your account.
+* Go to `/admin?emergency=1`, log in with the username and password you specified in
+  [`ADMIN_USERNAME`]({{site.baseurl}}docs/customising/config/#admin_username)
+  and [`ADMIN_PASSWORD`]({{site.baseurl}}docs/customising/config/#admin_password).
+  You can find these settings in `config/general.yml`.
+* You're now on the Alaveteli admin page.
+* Click on **Users**  (in the navigation menu across the top of the page), and
+  click on your name in the list of users. On *that* page,  click **Edit**.
+* Change your *Admin level* to "super" and click **Save**.
+* From now on, when you are logged into your Alavateli site, you'll have access
+  to the admin (at `/admin`). Furthermore, you'll see links to admin pages off
+  the main site (which don't appear for regular users).
+
+If your installation has loaded the sample data, there will be a dummy user in
+your database called "Joe Admin" who has admin status too. You should remove
+this status so there's no risk of it being used to access your site admin. You
+can either do this while you're still logged in as the emergency user... or
+else, later, logged in as yourself:
+
+* Go to `/admin/users` or click on **Users** in the navigation menu on any
+  admin page.
+* Find "Joe Admin" in the list of users, and click on the name to see the
+  user details. On *that* page, click **Edit**.
+* Change the *Admin level* from "super" to "none" and click **Save**.
+* Joe Admin no longer has admin status.
+
+Now that your account is a superuser admin, you don't need to allow the
+emergency user access to the admin. On the command line shell, edit
+`/var/www/alaveteli/alaveteli/config/general.yml`:
+
+* It's important that you change the emergency user's password (and, ideally,
+  the username too) from the values Alavateli ships with, because they are
+  public and hence insecure. In `general.yml`, change
+  [`ADMIN_PASSWORD`]({{site.baseurl}}docs/customising/config/#admin_password)
+  (and maybe [`ADMIN_USERNAME`]({{site.baseurl}}docs/customising/config/#admin_username)
+  too) to new, unique values.
+* Additionally, you can totally disable the emergency user. Under normal
+  operation you don't need it, because from now on you'll be using the admin
+  user you've just created.
+  Set [`DISABLE_EMERGENCY_USER`]({{site.baseurl}}docs/customising/config/#disable_emergency_user)
+  to `true`.
+* To apply these changes restart the service as a user with root privileges:
+  `sudo service alaveteli restart`
+
+You can use the same process (logged in as your admin account) to add or remove
+superuser admin status to any users that are subsequently added to your site.
+If you accidentally remove admin privilege from all accounts (try not to do
+this, though!), you can enable the emergency user by editing the `general.yml`
+file and restarting Alaveteli.
+
 ## Load sample data
 
 If you want some dummy data to play with, you can try loading the fixtures that
-the test suite uses into your development database. You can do this with:
+the test suite uses into your development database. As the `alaveteli` user, do:
 
     script/load-sample-data
 
-You should then update the Xapian search index for the new data:
-
-    script/update-xapian-index
+If the sample data has already been loaded into the database, this command won't
+do anything, but will instead <abbr
+title='PG::Error: ERROR:  permission denied: "RI_ConstraintTrigger_XXXXXX" is a system trigger'>fail
+with an error</abbr>.
 
-## Create a superuser account for yourself
+If you have added the sample data, update the Xapian search index afterwards:
 
-* Sign up for a new account on the site. You should receive a confirmation email. Click on the link in it to confirm the account.
-
-* Get access to the [admin interface]({{ site.baseurl}}docs/running/admin_manual/#administrator-privileges). You can find the
-`general.yml` file you'll need to get the `ADMIN_USERNAME` and
-`ADMIN_PASSWORD` credentials in the `config` subdirectory of the
-directory Alaveteli was installed into.
+    script/update-xapian-index
 
-* In the admin interface, go to the 'Users' section and find the account you just created. Promote the account you just created to superuser status by clicking the 'Edit' button and setting the 'Admin level' value to 'super'.
+Remember that the sample data includes a user with admin access to your site.
+You should revoke that status so it cannot be used to access your site --
+follow the steps described in the previous section.
 
 ## Test out the request process
 
-* Create a new public authority in the admin interface - give it a name something like 'Test authority'. Set the request email to an address that you will receive.
+* Create a new public authority in the admin interface -- give it a name like
+  "Test authority". Set the request email to an address that you will receive.
 
 * From the main interface of the site, make a request to the new authority.
 
-* You should receive the request email - try replying to it. Your response email should appear in Alaveteli. Not working? Take a look at our [troubleshooting tips]({{ site.baseurl}}docs/installing/manual_install/#troubleshooting). If that doesn't sort it out, [get in touch]({{ site.baseurl}}community/) on the project mailing list or IRC
-for help.
+* You should receive the request email -- try replying to it. Your response
+  email should appear in Alaveteli. Not working? Take a look at our
+  [troubleshooting tips]({{ site.baseurl}}docs/installing/manual_install/#troubleshooting).
+  If that doesn't sort it out, [get in touch]({{ site.baseurl}}community/) on
+  the [developer mailing list](https://groups.google.com/forum/#!forum/alaveteli-dev) or [IRC](http://www.irc.mysociety.org/) for help.
 
 ## Import Public Authorities