diff options
| -rw-r--r-- | docs/glossary.md | 67 | ||||
| -rw-r--r-- | docs/installing/manual_install.md | 7 | ||||
| -rw-r--r-- | docs/installing/next_steps.md | 4 | ||||
| -rw-r--r-- | docs/running/admin_manual.md | 41 |
4 files changed, 103 insertions, 16 deletions
diff --git a/docs/glossary.md b/docs/glossary.md index b5239a32a..3ae5e6a3c 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -16,6 +16,7 @@ Definitions <ul class="definitions"> <li><a href="#alaveteli">Alaveteli</a></li> + <li><a href="#admin">admin interface</a></li> <li><a href="#agnostic">asker agnostic</a></li> <li><a href="#authority">authority</a></li> <li><a href="#blackhole">black hole</a></li> @@ -42,6 +43,7 @@ Definitions <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="#super">superuser</a></li> <li><a href="#theme">theme</a></li> </ul> @@ -79,6 +81,40 @@ Definitions </dd> <dt> + <a name="admin">admin interface</a> (also: admin) + </dt> + <dd> + The <strong>admin interface</strong> allows users who have + <a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">super</a> + administrator privilege to manage some aspects of how your + Alaveteli site runs. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + You can access your installation's <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a> + at <code>/admin</code>. + </li> + <li> + To grant a user admin privilege, log into the admin and change + their <em>Admin level</em> to "super" (or revoke the privilege + by changing it to "none"). + </li> + <li> + On a newly-installed Alaveteli system, you can grant yourself + admin privilege by using the + <a href="{{ site.baseurl }}docs/glossary/#emergency" class="glossary__link">emergency + user</a>. + </li> + <li> + For lots more about running an Alaveteli site, see the + <a href="{{ site.baseurl }}running/admin_manual">adminstrator's guide</a>. + </li> + </ul> + </div> + </dd> + + <dt> <a name="agnostic">asker agnostic</a> </dt> <dd> @@ -266,7 +302,7 @@ Definitions </dd> <dt> - <a name="foi">Freedom of Information</a> (also FOI) + <a name="foi">Freedom of Information</a> (also: FOI) </dt> <dd> <strong>Freedom of information</strong> laws allow access by the general public @@ -287,7 +323,7 @@ Definitions </dd> <dt> - <a name="git">git</a> (also github, git repository, and git repo) + <a name="git">git</a> (also: github, git repository, and git repo) </dt> <dd> We use a popular source code control system called <strong>git</strong>. This @@ -617,7 +653,7 @@ Definitions </dd> <dt> - <a name="rails">Ruby on Rails</a> (also Rails) + <a name="rails">Ruby on Rails</a> (also: Rails) </dt> <dd> Alaveteli is written in the Ruby programming language, using @@ -721,6 +757,31 @@ Definitions </dd> <dt> + <a name="super">superuser</a> (also: super privilege) + </dt> + <dd> + A <strong>superuser</strong> is an Alaveteli user who has been granted + the privilege to use all features of the + <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + To grant a user admin privilege, log into the admin and change + their <em>Admin level</em> to "super" (or revoke the privilege + by changing it to "none"). + </li> + <li> + On a newly-installed Alaveteli system, you can grant yourself + admin privilege by using the + <a href="{{ site.baseurl }}docs/glossary/#emergency" class="glossary__link">emergency + user</a>. + </li> + </ul> + </div> + </dd> + + <dt> <a name="theme">theme</a> </dt> <dd> diff --git a/docs/installing/manual_install.md b/docs/installing/manual_install.md index 8c9e2a8d6..9cad6b5b9 100644 --- a/docs/installing/manual_install.md +++ b/docs/installing/manual_install.md @@ -351,7 +351,12 @@ Example `development` section of `config/database.yml`: Make sure that the user specified in `database.yml` exists, and has full permissions on these databases. -As the user needs the ability to turn off constraints whilst running the tests they also need to be a superuser. If you don't want your database user to be a superuser, you can add this line to the `test` section in `database.yml` (as seen in `config/database.yml-example`): +As the user needs the ability to turn off constraints whilst running the tests +they also need to be a superuser (clarification: a <em>Postgres</em> superuser, +not an Alaveteli +<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">superuser</a>). +If you don't want your database user to be a superuser, you can add this line +to the `test` section in `database.yml` (as seen in `config/database.yml-example`): constraint_disabling: false diff --git a/docs/installing/next_steps.md b/docs/installing/next_steps.md index 4199daabf..20c69a504 100644 --- a/docs/installing/next_steps.md +++ b/docs/installing/next_steps.md @@ -14,7 +14,9 @@ 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. +user to promote your new account to be an administrator with +<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">super</a> +privilege. 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. diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md index d166cb859..a846732f3 100644 --- a/docs/running/admin_manual.md +++ b/docs/running/admin_manual.md @@ -7,12 +7,23 @@ 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" + expect, and the types of problem that you might encounter. At mySociety, + we've been running our own <a href="/docs/glossary/#foi" class="glossary__link">Freedom of Information</a> site, <a - href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>. + href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>, since 2008, + so we've included lots of examples from our own experience. + </p> +<div class="attention-box helpful-hint"> + <p> + <b>Before you start...</b> + This admin guide assumes your Alaveteli site is already up and running. + If it's not, you need to follow the steps for + <a href="{{ site.baseurl }}docs/getting_started/">getting started with Alaveteli</a>. + </p> +</div> + In this guide: <ul class="toc"> @@ -55,7 +66,8 @@ 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). 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 +that the former happen exclusively through the web +<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>, whereas the latter are mediated by email directly with end users (but often result in actions through the web admin interface). @@ -308,17 +320,24 @@ line, and piping the contents of that file into the mail handling script. e.g. ### Administrator privileges and accessing the admin interface -The administrative interface is at the URL `/admin`. +The +<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">administrative interface</a> +is at the URL `/admin`. -Only users with the `super` admin level can access the admin interface. Users -create their own accounts in the usual way, and then administrators can give -them `super` privileges. +Only users with the +<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">super</a> +admin level can access the admin interface. To make a new administrator, +create a user account in the usual way (signing in using the web front-end), +and then have an existing administrator to grant them *super* privileges. -There is an emergency user account which can be accessed via -`/admin?emergency=1`, using the credentials `ADMIN_USERNAME` and +Obviously, you can't do this for the very first administrator on a brand +new Alavetlei installation. So there is an emergency user account which can be +accessed via `/admin?emergency=1`, using the credentials `ADMIN_USERNAME` and `ADMIN_PASSWORD`, which are set in `general.yml`. To bootstrap the first `super` level accounts, you will need to log in as the emergency -user. You can disable the emergency user account by setting `DISABLE_EMERGENCY_USER` to `true` in `general.yml`. +user. When you have granted *super* privileges to at least one existing user, +you can disable the emergency user account by setting `DISABLE_EMERGENCY_USER` +to `true` in `general.yml`. Users with the superuser role also have extra privileges in the website front end, such as being able to categorise any request, being able to view |