documentation updates just before 0.5.0

docs/admin.rst

@@ -110,11 +110,13 @@ The following aspects of a `Resource` can be edited:
 
 By default, when resource is created, owner's email will be added to notifications, however, resource can have arbitrary number or emails to notify.
 
+.. _admin_running:
+
 Running Healthchecks
 --------------------
 
 Healthchecks (Runs) for each Resource can be scheduled via `cron` or
-(since v0.5.0) by running the **GHC Runner** app standalone (as daemon)
+(starting with v0.5.0) by running the **GHC Runner** app standalone (as daemon)
 or within the **GHC Webapp**.
 
 Scheduling via Cron
@@ -139,10 +141,18 @@ GHC Runner as Daemon
 In this mode GHC applies internal scheduling for each individual `Resource`.
 This is the preferred mode as each `Resource` can have its own schedule (configurable
 via Dashboard) and `cron` has dependencies on local environment.
-Later versions may phase out cron-scheduling.
-The **GHC Runner** can be run via the command `paver runner_daemon` or internally within
-the **GHC Webapp** by setting the config variable **GHC_RUNNER_IN_WEBAPP** to True.
+Later versions may phase out cron-scheduling completely.
+
+The **GHC Runner** can be run via the command `paver runner_daemon` or can run internally within
+the **GHC Webapp** by setting the config variable **GHC_RUNNER_IN_WEBAPP** to `True` (the default).
+NB it is still possible to run GHC as in the pre-v0.5.0 mode using cron-jobs: just run the
+**GHC Webapp** with **GHC_RUNNER_IN_WEBAPP** set to `False` and have your cron-jobs scheduled.
+
+In summary there are three options to run GHC and its healthchecks:
 
+* run **GHC Runner** within the **GHC Webapp**: set **GHC_RUNNER_IN_WEBAPP** to `True` and run only the GHC webapp
+* (recommended): run **GHC Webapp** and **GHC Runner** separately (set **GHC_RUNNER_IN_WEBAPP** to `False`)
+* (deprecated): run **GHC Webapp** with **GHC_RUNNER_IN_WEBAPP** set to `False` and schedule healthchecks via external cron-jobs
 
 Build Documentation
 -------------------

docs/config.rst

@@ -25,7 +25,7 @@ You can override these settings in ``instance/config_site.py``:
 - **GHC_USER_PLUGINS**: list of Plugin classes or modules provided by user (you)
 - **GHC_PROBE_DEFAULTS**: Default `Probe` class to assign on "add" per Resource-type
 - **GHC_METADATA_CACHE_SECS**: metadata, "Capabilities Docs", cache expiry time, default 900 secs, -1 to disable
-- **GHC_RUNNER_IN_WEBAPP**: should the GHC Runner Daemon be run in webapp (default: false)
+- **GHC_RUNNER_IN_WEBAPP**: should the GHC Runner Daemon be run in webapp (default: ``True``)
 - **GHC_LOG_LEVEL**: logging level: 10=DEBUG 20=INFO 30=WARN(ING) 40=ERROR 50=FATAL/CRITICAL (default: 30, WARNING)
 - **GHC_MAP**: default map settings
 

docs/install.rst

@@ -74,6 +74,7 @@ Install
   # - GHC_NOTIFICATIONS_EMAIL
   # - GHC_SITE_TITLE
   # - GHC_SITE_URL
+  # - GHC_RUNNER_IN_WEBAPP # see 'running' section below
   # - GHC_SMTP  # if GHC_NOTIFICATIONS is enabled
   # - GHC_MAP  # or use default settings
 
@@ -113,10 +114,17 @@ When running with Docker see the
 `GHC Docker Readme <https://github.com/geopython/GeoHealthCheck/blob/master/docker/README.md>`_
 how to run `paver upgrade` within your Docker Container.
 
+Upgrade notes v0.5.0
+....................
+
+In GHC v0.5.0 a new run-architecture was introduced. By default, healthchecks run under
+the control of an internal scheduler, i.s.o. of external cron-jobs. See also the :ref:`architecture` chapter
+and :ref:`admin_running` and below.
+
 Running
 -------
 
-Start using the built-in ``mod_wsgi`` server:
+Start using Flask's built-in WSGI server:
 
 .. code-block:: bash
 
@@ -125,11 +133,25 @@ Start using the built-in ``mod_wsgi`` server:
   python GeoHealthCheck/app.py 192.168.0.105:8957  # http://192.168.0.105:8957
 
 
+This runs the (Flask) **GHC Webapp**, by default with the **GHC Runner** (scheduled healthchecker) internally.
+See also :ref:`admin_running` for the different options running the **GHC Webapp** and **GHC Runner**. It is
+recommended to run these as separate processes. For this set **GHC_RUNNER_IN_WEBAPP** to `False` in your `site_config.py`.
+From the command-line run both processes, e.g. in background or different terminal sessions:
+
+.. code-block:: bash
+
+  # run GHC Runner, here in background
+  python GeoHealthCheck/scheduler.py &
+
+  # run GHC Webapp for http://localhost:8000
+  python GeoHealthCheck/app.py
+
+
 To enable in Apache, use ``GeoHealthCheck.wsgi`` and configure in Apache
 as per the main Flask documentation.
 
 Running under a sub-path
------------------------------
+------------------------
 
 By default GeoHealthCheck is configured to run under the root directory on the webserver. However, it can be configured to run under a sub-path. The method for doing this depends on the webserver you are using, but the general requirement is to pass Flask's ``SCRIPT_NAME`` environment variable when GeoHealthCheck is started. 
 
@@ -141,10 +163,56 @@ Below is an example of how to use nginx and gunicorn to run GeoHealthCheck in a
  
     location /geohealthcheck {
       proxy_pass http://127.0.0.1:8000/geohealthcheck;
-      }
+    }
       
 - Include the parameter "-e SCRIPT_NAME=/geohealthcheck" in your command for running gunicorn:
 
 .. code-block:: bash
   
     gunicorn -e SCRIPT_NAME=/geohealthcheck app:app
+
+Production Recommendations
+--------------------------
+
+Use Docker!
+...........
+
+When running GHC in long-term production environment the following is recommended:
+
+* use Docker, see the `GHC Docker Readme <https://github.com/geopython/GeoHealthCheck/tree/master/docker>`_
+
+Using Docker, especially with Docker Compose (sample files provided) is our #1 recommendation. It saves
+all the hassle from installing the requirements, upgrades etc. Docker (Compose) is also used to run the GHC demo site
+and almost all of our other deployments.
+
+Use PostgreSQL
+..............
+
+Although GHC will work with `SQLite`, this is not a good option for production use, in particular
+for reliability starting with GHC v0.5.0:
+
+* reliability:  **GHC Runner** will do concurrent updates to the database, this will be unreliable under `SQLite`
+* performance: PostgreSQL has been proven superior, especially in query-performance
+
+Use a WSGI Server
+.................
+
+Although GHC can be run from the commandline using the Flask internal WSGI web-server, this
+is a fragile and possibly insecure option in production use (as also the Flask manual states).
+Best is to use a WSGI-server as stated in the `Flask deployment options <http://flask.pocoo.org/docs/1.0/deploying/#deployment>`_.
+
+See for example the `GHC Docker run.sh <https://github.com/geopython/GeoHealthCheck/blob/master/docker/scripts/run-web.sh>`_
+script to run the GHC Webapp with `gunicorn` and the `GHC Runner run-runner.sh <https://github.com/geopython/GeoHealthCheck/blob/master/docker/scripts/run-runner.sh>`_ script
+to run the scheduled healthchecks.
+
+Use virtualenv
+..............
+
+This is a general Python-recommendation. Save yourself from classpath and library hells by using `virtualenv`!
+
+Use SSL (HTTPS)
+...............
+
+As users and admin may login, running on plain http will send passwords in the clear.
+These days it has become almost trivial to automatically install SSL certificates
+with `Let's Encrypt <https://letsencrypt.org/>`_.