docs: automation

fixes: #1

docs/admin/install.rst

@@ -0,0 +1,25 @@
+Installation
+============
+
+The current installation method is to use a Python virtual envrionment.
+Many of the dependencies needed by the portal can be installed from PyPI, although some
+dependencies will need to be satisfied in other ways:
+
+* A cron daemon - probably available in your system package manager
+* Terraform binary - static binaries available from Hashicorp
+* PostgreSQL server - probably available in your system package manager
+
+Create and activate a virtual environment with:
+
+.. code-block:: shell
+
+   cd /installation/directory
+   python -m venv env
+   . env/bin/activate
+
+You will need to install an entry into the portal user's crontab:
+
+.. code-block:: crontab
+
+   */1 * * * * (cd /path/to/portal ; /path/to/env/bin/python -m app.cli automate --all) &>/dev/null
+

docs/index.rst

@@ -15,11 +15,13 @@ Documentation Home
    user/eotk.rst
    user/bridges.rst
    user/lists.rst
+   user/automation.rst
 
 .. toctree::
    :maxdepth: 2
    :caption: Admin Guide:
 
+   admin/install.rst
    admin/conf.rst
    admin/external.rst
    admin/eotk.rst

docs/user/automation.rst

@@ -0,0 +1,19 @@
+Automation
+==========
+
+When changes are made in the portal, the effects usually do not take place immediately, but rather
+are stored in the database for an automation job to action shortly after.
+There are many automation jobs that run in the portal, and you can find an overview of them
+on the "Automation" page, under "Monitoring" in the sidebar:
+
+.. image:: /_static/automation/list.png
+   :width: 800
+
+This page lists all the automation jobs, their current status, if they are enabled, their last,
+and their next run times.
+The last run time is updated after the completion of a run, and the next run time indicates the earliest
+time that a job may be started by the scheduler, although it may not start for up to a minute after this time.
+
+Once a task has started, the status will change from idle (🕰️) to running (🏃). If the run completes successfully,
+it will revert to idle again until the next run.
+If an error occurred (💥) then the module will automatically be disabled to allow for an administrator to investigate.